# Guardia MCP Server

A production Model Context Protocol (MCP) server with 70+ tools, OAuth 2.1 authentication, and frame-based tool filtering. Built with Python and FastAPI.

## What It Does

This server exposes tools to AI assistants (Claude, etc.) via the [MCP protocol](https://modelcontextprotocol.io). Tools span multiple domains — business operations, trading, creative writing, infrastructure, and more — organized into **frames** that let each client see only the tools relevant to its context.

### Key Features

- **70+ tools** across 12 domain modules with decorator-based auto-registration
- **Frame-based filtering** — clients request a frame (`serberus`, `paradise`, `luna`, etc.) and only see relevant tools
- **OAuth 2.1** — full authorization server with PKCE, JWT (RS256), refresh tokens
- **Streamable HTTP + SSE** — compatible with Claude.ai, Claude Desktop, and custom clients
- **REST fallback** — `/mcp/tools` and `/mcp/call` endpoints for non-MCP clients
- **Stdio bridge** — `bridge.js` connects Claude Desktop (stdio transport) to the remote server

## Architecture

```
main.py                 FastAPI app, SSE endpoints, protocol wiring
config.py               Pydantic settings (env-driven)
bridge.js               Claude Desktop stdio-to-HTTP bridge

mcp/
  protocol.py           JSON-RPC message handling
  transport.py          HTTP/SSE transport layer
  sessions.py           Session management

auth/
  oauth_server.py       OAuth 2.1 authorization server
  jwt_handler.py        RS256 JWT signing/verification
  middleware.py          Request authentication
  models.py             Auth data models

tools/
  registry.py           @tool decorator, auto-registration, frame filtering
  cortex.py             Brain/awareness tools
  business.py           Client and revenue tools
  paradise.py           Trading system tools
  athernyx.py           Creative writing tools
  dev.py                Development utilities
  web.py                Web search and browsing
  atomic.py             System tools (shell, files, queries)
  ...                   (12 modules total)

db/
  cortex.py             Cortex database helpers
  spire.py              App database helpers
  oauth.py              OAuth token storage
```

## Adding a Tool

Tools are registered with a decorator. Drop this in any `tools/*.py` file:

```python
from tools.registry import tool, json_result, error_result

@tool(
    name="my_tool",
    description="What this tool does",
    properties={
        "input": {"type": "string", "description": "The input"}
    },
    required=["input"],
    frames=["core"]  # Which frames include this tool
)
async def my_tool(args: dict) -> dict:
    value = args.get("input", "")
    return json_result({"result": value})
```

The registry auto-discovers all decorated functions at import time.

## Frame Filtering

Frames control which tools a client sees. Pass `?frame=X` on the SSE connection URL:

| Frame | Tools | Use Case |
|-------|-------|----------|
| `core` | ~14 | Essential tools (boot, cortex, system) |
| `serberus` | ~23 | Business operations + dev tools |
| `paradise` | ~25 | Trading system tools |
| `magii` | ~37 | Creative writing tools |
| `luna` | ~55 | Full assistant tools |
| *(none)* | ~95 | All tools |

Frame only affects `tools/list` — all tools remain callable regardless of frame.

## Setup

```bash
# Clone and install
git clone https://github.com/alexlaguardia/guardia-mcp.git
cd guardia-mcp
pip install -r requirements.txt

# Configure
cp .env.example .env
# Edit .env with your settings

# Generate RSA keys for JWT
mkdir -p keys
openssl genrsa -out keys/private.pem 2048
openssl rsa -in keys/private.pem -pubout -out keys/public.pem

# Run
python main.py
# Server starts on port 8100
```

## Connecting Clients

**Claude.ai (remote):**
```
SSE URL: https://your-domain.com/sse?frame=serberus
```

**Claude Desktop (stdio bridge):**
```json
{
  "mcpServers": {
    "guardia": {
      "command": "node",
      "args": ["bridge.js"],
      "env": {
        "MCP_BASE_URL": "https://your-domain.com",
        "MCP_DEV_KEY": "your-dev-key"
      }
    }
  }
}
```

## Stack

- **Runtime:** Python 3.11+
- **Framework:** FastAPI + Uvicorn
- **Auth:** RS256 JWT, OAuth 2.1 with PKCE
- **Transport:** Streamable HTTP, SSE, stdio (via bridge)
- **Database:** SQLite (via raw queries)
- **Process Manager:** PM2

## License

MIT