# MCP Powered AI Assistance

A secure, standardised AI assistant on the [Model Context Protocol](https://modelcontextprotocol.io):
an OpenAI-driven LangGraph agent that can query databases, fetch metrics, and run
Python — with every untrusted execution confined to an ephemeral Docker sandbox.

```
User ──▶ Client Gateway (LangGraph + OpenAI)
             │  MCP over SSE (remote) or stdio (local)
             ▼
        MCP Server (FastAPI + official MCP SDK)
             │  run_python · execute_sql · fetch_metrics
             ▼
        Ephemeral Docker sandbox (no network, read-only,
        cpu/mem/pid quotas, hard timeout, orphan reaper)

State: Postgres (LangGraph checkpointer) · Events: Redis pub/sub
```

## Layout

- [server/tools.py](server/tools.py) — tool registry; Pydantic-typed schemas exposed at capability negotiation
- [server/sandbox.py](server/sandbox.py) — ephemeral Docker execution + orphan reaper
- [server/main.py](server/main.py) — FastAPI app (SSE transport) and stdio entrypoint
- [client/gateway.py](client/gateway.py) — MCP client + LangGraph function-calling loop
- [tests/](tests/) — protocol compliance, schema validation, sandbox security E2E

## Quick start

```bash
uv sync
docker compose up -d postgres redis     # infra
uv run python -m server.main            # MCP server on :8000 (SSE at /sse)

export OPENAI_API_KEY=sk-...
uv run python -m client.gateway "How many run_python calls in the last hour?"

# or local stdio (no server process needed):
MCP_TRANSPORT=stdio uv run python -m client.gateway "print hello from the sandbox"
```

## Tests (V&V)

```bash
uv run pytest
```

- **Protocol compliance** — `initialize`, `tools/list` (schemas present), `tools/call` round-trip.
- **Schema validation** — malformed payloads return actionable Pydantic errors to the LLM; the server never crashes.
- **Sandbox security (E2E)** — injected malicious code attempting host env-var reads,
  directory traversal, network egress, and filesystem writes is blocked; runaway
  code is killed at the timeout; the reaper removes crash orphans.

## Production deployment

```bash
# self-signed cert for local TLS testing (use real certs / cert-manager in prod)
mkdir -p deploy/certs && openssl req -x509 -newkey rsa:2048 -nodes -days 365 \
  -keyout deploy/certs/server.key -out deploy/certs/server.crt -subj "/CN=mcp"

MCP_API_KEY=$(openssl rand -hex 32) docker compose up --build
# clients connect to https://host:8443/sse with header X-Api-Key: <key>
```

Containerising the MCP server is the industry standard so AI-generated code never
executes with raw host access. On **Kubernetes**: run the server as a Deployment,
give sandboxes their own node pool or use a socketless runtime (Kata/gVisor) instead
of mounting the Docker socket, front with an Ingress terminating TLS. On **AWS ECS**:
one service for the server, sandbox tasks via `RunTask` with an isolated task
security group, ALB + ACM for TLS.

### Readiness checklist

- [x] **Network isolation** — sandboxes run with `network_disabled=True`: no egress at all, including VPC metadata endpoints.
- [x] **Resource quotas** — 256 MB memory (no swap), 0.5 CPU, 64 pids, read-only rootfs, 16 MB noexec tmpfs per sandbox.
- [x] **TLS & auth** — Nginx reverse proxy enforcing HTTPS and `X-Api-Key` auth in front of the SSE endpoint.
- [x] **Ephemeral cleanup** — containers force-removed after each run; background reaper kills anything labelled `mcp-sandbox=1` older than 120 s.