LOOP Developer Agent

AI-powered developer platform for building on LOOP financial infrastructure. Built for the LOOP Hackathon — Sandbox environment.

---

What is this?

LOOP Developer Agent is an MCP-compliant AI platform that:

1. Inspects your project — detects framework (Django, FastAPI, Flask, Next.js, Express), package manager, and existing payment integrations.
2. Generates integration code — produces production-ready LOOP payment code tailored to your stack.
3. Runs sandbox tests — validates signing, authentication, and API calls against the real LOOP sandbox.
4. Enforces policy — a deterministic policy engine gates every financial operation before the LLM can act.
5. Provides a full CLI — loop init, loop dev, loop tools, loop doctor, loop test.

The demo: a developer says "Add LOOP payments" → the agent inspects the Django shop → discovers the MCP server → generates the integration code → runs sandbox validation → detects issues → fixes → marks READY.

---

Architecture

┌─────────────────────────────────────────────────────────────┐
│  Developer (CLI / Claude Desktop / IDE)                     │
└──────────────────────┬──────────────────────────────────────┘
                       │ MCP protocol (stdio)
┌──────────────────────▼──────────────────────────────────────┐
│  MCP Server (mcp_server/server.py)                          │
│  14 tools  ·  2 resources  ·  2 prompts                     │
└──────────┬────────────────────────┬────────────────────────-┘
           │                        │
┌──────────▼──────────┐   ┌─────────▼─────────────────────────┐
│  Policy Engine      │   │  Service Layer (mcp_server/        │
│  (policy/engine.py) │   │  service.py) — idempotency,        │
│  ALLOW / DENY /     │   │  credential validation             │
│  REQUIRES_APPROVAL  │   └──────────────┬────────────────────-┘
└─────────────────────┘                  │
                                ┌────────▼────────────────────┐
                                │  LOOP Adapter               │
                                │  (loop/adapters/sandbox.py) │
                                │  All 10 LOOP APIs           │
                                └────────────────────────────-┘

---

Quick Start

1. Prerequisites

• Python 3.11+
• A LOOP Developer Portal account (https://sandbox.loop.co.ke/devportal)
• Your Consumer Key and Consumer Secret from the portal

2. Install

git clone <this-repo>
cd loop_mcp
pip install -e ".[dev]"

3. Configure

cp .env.example .env

Edit .env — see docs/HUMAN_INPUT_REQUIRED.md for what each value means and where to get it.

Required:

LOOP_CONSUMER_KEY=your_consumer_key
LOOP_CONSUMER_SECRET=your_consumer_secret
LOOP_MERCHANT_TILL=133239           # Use sandbox test till
LOOP_TILL_SECRET_KEY=hyqd7bwMr9Kv-C5PW4n7uF4TiMnMp_hyvyhYYkYlcU8  # Sandbox shared secret

4. Verify everything works

loop doctor

Expected output:

✓ Settings loaded
✓ LOOP credentials present
✓ HMAC test vector: PASS
✓ MCP server importable
✓ Policy engine: ALLOW (sandbox, READ tool)
All checks passed.

5. Start the MCP server

loop dev

6. Explore tools

loop tools        # List all 14 MCP tools
loop sandbox      # Run sandbox scenarios interactively

---

Demo: Django Laptop Shop

The demo ecommerce application sells a laptop for KES 75,000 and accepts M-Pesa payments via LOOP.

cd demo/django_shop
pip install -r requirements.txt
cp ../../.env .env           # Reuse root .env
python manage.py migrate
python manage.py seed_products
python manage.py runserver

Open http://localhost:8000 — you will see the ProBook Laptop at KES 75,000. Click Buy with M-Pesa to trigger the full LOOP STK Push flow.

Webhook: For the callback to work in sandbox, expose your local server with ngrok http 8000 and set LOOP_WEBHOOK_CALLBACK_URL=https://<your-ngrok>.ngrok.io/loop/webhook/.

---

CLI Reference

Command	Description
loop init	Initialise a new LOOP integration in the current project
loop dev	Start the MCP server (stdio)
loop tools	List all available MCP tools with their LOOP API sources
loop doctor	Run health checks (credentials, signing, server import)
loop test	Run sandbox integration tests
loop sandbox	Interactive sandbox scenarios menu
loop docs	Open LOOP API documentation
loop agent	Run the developer agent on a project path

---

MCP Tools

Tool	Operation	Risk	LOOP API
initiate_mpesa_stk_push	M-Pesa STK Push	WRITE	Mpesa Prompt API
initiate_loop_prompt	LOOP Prompt	WRITE	Loop Prompt API
get_transaction_status	Transaction inquiry	READ	Transaction Inquiry API
list_transactions	Transaction history	READ	Transaction History API
pay_to_loop_till	Pay to LOOP Till	WRITE	Pay to Loop Till API
pay_to_mpesa_till	Pay to M-Pesa Till	WRITE	Pay to Mpesa Till API
pay_to_paybill	Pay to Paybill	WRITE	Pay to Paybill API
send_money_loop	Send to LOOP	SENSITIVE	Send Money (LOOP) API
send_money_mpesa	Send to M-Pesa	SENSITIVE	Send Money (Mpesa) API
send_money_pesalink	Send via PesaLink	SENSITIVE	Send Money (PesaLink) API
validate_loop_integration	Health check	READ	—
reconcile_transactions	Reconciliation	READ	Transaction History API
get_loop_capabilities	Capabilities	READ	—
get_sandbox_credentials	Sandbox creds	READ	—

---

Policy Engine

Every tool call is gated by PolicyEngine.check() before any API call is made. The LLM cannot bypass it.

• ALLOW — READ tools always; WRITE tools in sandbox.
• REQUIRES_APPROVAL — SENSITIVE tools always; WRITE tools in production; amounts > KES 10,000.
• DENY — Invalid amounts; wrong till number; missing credentials.

---

Project Structure

loop_mcp/
├── loop/                    # Core library
│   ├── config.py            # Settings (pydantic-settings)
│   ├── errors.py            # Typed error hierarchy
│   ├── signing.py           # HMAC-SHA256 signing
│   ├── auth/                # OAuth2 Client Credentials
│   ├── models/              # Pydantic request/response models
│   └── adapters/            # LOOP HTTP client (sandbox + production)
├── policy/                  # Deterministic policy engine
├── mcp_server/              # MCP server (official MCP Python SDK)
│   ├── server.py            # 14 tools, 2 resources, 2 prompts
│   └── service.py           # Service layer with idempotency
├── agent/                   # AI developer agent (Claude)
├── cli/                     # Typer CLI
├── demo/django_shop/        # Demo ecommerce app
├── docs/                    # API inventory, human input guide, security
├── pyproject.toml
├── .env.example
├── Dockerfile
└── docker-compose.yml

---

Human Input Required

See docs/HUMAN_INPUT_REQUIRED.md for a full list of what must be provided. The critical items:

Variable	Where to get it
LOOP_CONSUMER_KEY	LOOP Developer Portal → Applications
LOOP_CONSUMER_SECRET	LOOP Developer Portal → Applications
LOOP_MERCHANT_TILL	Use 133239 for sandbox
LOOP_TILL_SECRET_KEY	Use documented sandbox secret (in .env.example)

---

Security

See docs/security.md for the full security model covering: secret management, OAuth2, HMAC signing, policy engine, idempotency, MCP security, Django app hardening, and OWASP Top 10 mitigations.

---

What is NOT implemented (by design)

• No invented endpoints — every API call uses a URL from the official LOOP OpenAPI spec.
• No production deployment — RealLoopAdapter raises NotImplementedError until the production URL is confirmed.
• No webhook signature verification — LOOP docs do not specify this; see docs/security.md §Known Gaps.

---

License

MIT