# Agent Bridge MCP Server

An MCP server + Lambda API that enables **real-time communication between Kiro and Amazon Quick** across environments (local Windows ↔ cloud DevSpaces). Messages are stored in S3 and accessible via API Gateway — no shared filesystem required.

## Architecture

```
┌──────────────────┐                              ┌──────────────────┐
│   Amazon Quick   │                              │       Kiro       │
│   (Windows PC)   │                              │   (DevSpaces)    │
│                  │                              │                  │
│  MCP Server      │         ┌──────────┐        │  curl / shell    │
│  (stdio, boto3)  │────────►│    S3    │◄───────│                  │
│                  │         │  bucket  │        │                  │
│      — OR —      │         └──────────┘        │      — OR —      │
│                  │              ▲               │                  │
│  Lambda invoke   │              │               │  API Gateway     │
│  (via Matilda)   │────────►┌────┴─────┐◄───────│  (HTTPS POST)    │
│                  │         │  Lambda  │        │                  │
└──────────────────┘         └──────────┘        └──────────────────┘
```

## Components

| Component | Purpose |
|-----------|---------|
| `server.py` | Local MCP server (stdio) — Quick connects directly via S3 |
| `lambda/lambda_function.py` | Lambda function — HTTP API relay to same S3 store |
| API Gateway | Public HTTPS endpoint for Kiro (DevSpaces can't hit Lambda URLs directly) |
| S3 Bucket | Shared message store |

## Endpoints

| Who | How they connect |
|-----|-----------------|
| **Quick** | MCP server (local stdio) with `AGENT_BRIDGE_BUCKET` env var, OR Lambda invoke via Matilda |
| **Kiro** | `POST https://<your-api-id>.execute-api.<region>.amazonaws.com/` with `x-bridge-secret` header |

## Setup

### Prerequisites
- Python 3.10+
- `pip install mcp boto3`
- AWS credentials with S3 access

### Environment Variable
```bash
export AGENT_BRIDGE_BUCKET=your-bucket-name
```

### Amazon Quick (local MCP)
Settings → Capabilities → MCP → Add Server:
- **Command:** `py`
- **Args:** path to `server.py`
- **Env:** `AGENT_BRIDGE_BUCKET=your-bucket-name`

### Kiro (DevSpaces — via API Gateway)
```bash
# Send a message
curl -s -X POST "https://<your-api-id>.execute-api.<region>.amazonaws.com/" \
  -H "Content-Type: application/json" \
  -H "x-bridge-secret: YOUR_SECRET" \
  -d '{"action":"send_message","sender":"kiro","recipient":"quick","content":"Hello from Kiro!"}'

# Check for messages
curl -s -X POST "https://<your-api-id>.execute-api.<region>.amazonaws.com/" \
  -H "Content-Type: application/json" \
  -H "x-bridge-secret: YOUR_SECRET" \
  -d '{"action":"get_messages","agent":"kiro"}'

# Get stats
curl -s -X POST "https://<your-api-id>.execute-api.<region>.amazonaws.com/" \
  -H "Content-Type: application/json" \
  -H "x-bridge-secret: YOUR_SECRET" \
  -d '{"action":"get_stats"}'
```

## API Actions

All requests are `POST` with JSON body containing `"action"` plus parameters:

| Action | Parameters | Description |
|--------|-----------|-------------|
| `send_message` | `sender`, `recipient`, `content`, `conversation_id?`, `title?`, `message_type?` | Send a message |
| `get_messages` | `agent`, `status?` (unread/read/all), `limit?` | Check inbox |
| `mark_read` | `agent`, `message_ids?`, `conversation_id?` | Mark messages read |
| `list_conversations` | `status?` (active/closed/all) | List threads |
| `get_conversation` | `conversation_id` | Full thread history |
| `get_stats` | (none) | Bridge statistics |

## Message Types
`message`, `task`, `response`, `context`, `status`, `question`

## S3 Structure
```
bridge/
├── inbox/
│   ├── quick/          ← Quick's messages
│   └── kiro/           ← Kiro's messages
└── conversations/
    └── {conv_id}/
        ├── meta.json   ← Thread metadata
        └── messages/   ← Chronological messages
```

## Security
- S3 bucket: private, all public access blocked
- API Gateway: secured by `x-bridge-secret` header checked in Lambda code
- Lambda function URL: `AuthType: NONE` (backup path)

## AWS Resources (you'll create these)
- **S3 Bucket:** any name (set as `AGENT_BRIDGE_BUCKET`)
- **Lambda:** handles API actions against the S3 bucket
- **API Gateway:** HTTP API fronting the Lambda
- **IAM Role:** Lambda execution role with S3 read/write on the bucket

## License
MIT