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:

Inspects your project — detects framework (Django, FastAPI, Flask, Next.js, Express), package manager, and existing payment integrations.
Generates integration code — produces production-ready LOOP payment code tailored to your stack.
Runs sandbox tests — validates signing, authentication, and API calls against the real LOOP sandbox.
Enforces policy — a deterministic policy engine gates every financial operation before the LLM can act.
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