# Passport MCP Server (mock)

A mock [MCP](https://modelcontextprotocol.io) server for the Passport ELM legal
matter-management system: 13 typed tools (create/enrich/search/submit matters,
budgets, allocations, entitlements) over Streamable HTTP, backed by Postgres,
with a deterministic rules engine and an append-only audit log.

Extracted from the `legalDashboard` monorepo with history preserved. Sibling repos:

| Repo | Role |
|---|---|
| **passport-mcp-server** (this) | Tool contract + business rules + persistence |
| `matter-assistant-backend` | LangGraph wizard agent / SSE BFF (MCP client) |
| `matter-assistant-ui` | Next.js chat portal |

## Run

```bash
docker compose up -d --build     # Postgres on host :5433, MCP server on :8081
```

The MCP endpoint is `http://localhost:8081/mcp`. Migrations in
`src/passport_mcp/migrations/` are idempotent and run at startup; mock reference
data lives in `src/passport_mcp/data/`.

## Develop & test

```bash
docker compose up -d postgres            # tests only need the database
python -m venv .venv && . .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -e ".[dev]"
python -m pytest tests/ -q
```

Config is env-driven (`src/passport_mcp/config.py`); the default
`DATABASE_URL` is `postgresql://passport:passport@localhost:5433/passport`.

## Invariants

- Business rules and error codes are defined once in `src/passport_mcp/rules.py`
  and re-emitted verbatim by tools.
- Tools never raise for business failures — they return
  `{"ok": false, "error": {code, message, field}}`.
- Writes are idempotent (client-supplied `idempotency_key`) and audited.

Behind a corporate TLS-intercepting proxy, drop its root CA as a `.crt` into
`certs/` (gitignored) before building the image.