# 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

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

### 3. Configure

```bash
cp .env.example .env
```

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

**Required:**
```env
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

```bash
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

```bash
loop dev
```

### 6. Explore tools

```bash
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.

```bash
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