# MacroMCP

Remote **MCP server** for natural-language calorie/macro and weight tracking, designed to
connect to Claude.ai as a custom connector. You describe meals in plain language; Claude calls
structured tools; MacroMCP is the system of record and the guardrail (it never lets the model
guess unverifiable numbers).

Full docs:
- [docs/connector-setup.md](docs/connector-setup.md) — connect MacroMCP to Claude
- [docs/architecture.md](docs/architecture.md) — how it fits together
- [docs/deployment.md](docs/deployment.md) — AWS EC2 + RDS + DuckDNS runbook + security gate
- [docs/security.md](docs/security.md) — controls by surface

## Quick start (local)

```bash
make install          # install deps (editable)
make keys             # generate a dev JWT signing key
cp .env.example .env  # then edit as needed
make up               # docker compose: Postgres + app at http://localhost:8000
# or, against a local Postgres:
make migrate && make run
```

Health check: `GET http://localhost:8000/healthz` → `{"status":"ok"}`.

## Testing

```bash
make test                                  # unit tests (no DB)
TEST_DATABASE_URL=postgresql+asyncpg://macro:macro@localhost:5432/macromcp_test \
  .venv/bin/python -m pytest               # + DB tests (isolation, RLS, OAuth flow)
make audit                                 # pip-audit (security gate)
```

Interactively exercise the MCP tools and OAuth with the Inspector:

```bash
npx @modelcontextprotocol/inspector
# transport: Streamable HTTP, URL: http://localhost:8000/mcp  (it will run the OAuth flow)
```

## Stack

Python · FastMCP · FastAPI · PostgreSQL (RDS) · Authlib (self-hosted OAuth 2.1) · Docker +
Caddy on EC2. See [docs/architecture.md](docs/architecture.md).

## Security

Multi-user with strict per-user isolation (token `sub` + Postgres RLS), OAuth 2.1 + PKCE,
audience-bound JWTs, and a gated security checklist. See `docs/security.md`.