# Cloudflare Email MCP Server

A comprehensive Model Context Protocol server for Cloudflare KV operations and automated email processing from ProtonMail Bridge to Cloudflare KV namespaces.

## Features

### KV Operations
- **Key Management**: List, count, get, put, delete keys in any KV namespace
- **Pagination**: Handle large datasets with cursor-based pagination
- **Bulk Operations**: Retrieve multiple keys efficiently

### Email Processing
- **Automated Transfer**: Move emails from specific IMAP folders to corresponding KV namespaces
- **UUID v5 Body IDs**: Deterministic body identification with separate storage
- **Folder Mapping**: Pre-configured mappings for court, government, and legal correspondence
- **Status Tracking**: Pending/processed status for workflow management

## Architecture

### Two-Tier Storage
```
Court KV Namespace:
├── Key: 2026.02.09_casework_ico_org_uk_10-30-45
└── Value: {
    "from": "casework@ico.org.uk",
    "to": "rose@mobicycle.ee", 
    "subject": "Your complaint reference IC-...",
    "body": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "namespace": "ICO Complaints",
    "status": "pending"
}

Body KV Namespace (by year):
├── Key: f47ac10b-58cc-4372-a567-0e02b2c3d479
└── Value: { "text": "Dear Ms Liu..." }
```

### Folder Mappings
Automatically processes emails from:
- **Courts**: Appeal, Chancery, Admin Court, King's Bench, Supreme, etc.
- **Government**: GLD, US State Dept, Estonian Government  
- **Complaints**: HMCTS, ICO, PHSO, Bar Standards, Parliament
- **Parties**: Liu Litigation, HK Law, Lessel Property, etc.

## Setup

### Prerequisites
- Bun runtime
- ProtonMail Bridge running locally
- Cloudflare account with KV access
- Wrangler CLI configured

### Authentication
The server uses Wrangler OAuth tokens automatically:
```bash
wrangler auth login
```

### Installation
```bash
bun install
bun run build
bun start
```

## Usage

### MCP Tools

#### KV Operations
```javascript
// Count keys in a namespace
kv_keys_count({
  namespace_id: "your-namespace-id",
  prefix: "email:"
})

// List keys with pagination  
kv_keys_list({
  namespace_id: "your-namespace-id",
  prefix: "2026.02",
  limit: 100,
  cursor: "next-page-cursor"
})

// Get/set individual values
kv_key_get({ namespace_id: "...", key: "..." })
kv_key_put({ namespace_id: "...", key: "...", value: "..." })
```

#### Email Processing
```javascript
// Transfer emails from approved folders
email_transfer_folders({
  folders: ["INBOX/Courts/Supreme"],
  since: "2026-02-01T00:00:00Z",
  dry_run: true
})

// Check processing stats
email_folder_stats({
  folder_name: "INBOX/Complaints/ICO"
})

// List all folders and their approval status
email_list_folders()
```

## Configuration

### Approved Folders
Only pre-configured folders automatically sync to KV:
- Legal correspondence folders
- Court communications  
- Government agencies
- Complaint systems

### KV Namespaces
- **Court namespaces**: One per jurisdiction
- **Body storage**: Separated by year (`email-bodies-2026`)
- **Account mapping**: Bridge gRPC account information

## Development

### Project Structure
```
src/
├── index.ts           # Main MCP server with stdio transport
├── cloudflare-api.ts  # KV operations via Cloudflare API
└── email-processor.ts # IMAP to KV sync logic

dist/                  # Built JavaScript
README.md             # This file
package.json          # Dependencies and scripts
```

### Building
```bash
bun run build    # TypeScript compilation
bun run dev     # Watch mode
```

### Testing
```bash
# Dry run email processing
email_transfer_folders({ dry_run: true })

# Test KV operations
kv_keys_count({ namespace_id: "test-namespace" })
```

## Integration

### Claude Code MCP Configuration
Add to Claude Code MCP settings:
```json
{
  "mcpServers": {
    "cloudflare-email": {
      "command": "bun",
      "args": ["start"],
      "cwd": "/path/to/this/directory"
    }
  }
}
```

### Environment Variables
```bash
# Optional - detected automatically from wrangler
CLOUDFLARE_API_TOKEN=your-token
CLOUDFLARE_ACCOUNT_ID=your-account-id
```

## Automation

### Bridge Integration
Works with ProtonMail Bridge gRPC for account mapping:
- Automatic token capture on Bridge restart
- Account structure pushed to KV
- Prevents email double-counting

### Workflow
1. Bridge receives emails in configured folders
2. MCP server syncs new emails to KV namespaces
3. AI triage system processes pending emails
4. Status updates track workflow progress

## License

Internal MobiCycle OÜ project - Not for public distribution