# Python MCP Server Kit

A backend-only starter for secure, typed, and testable Model Context Protocol
servers. It targets the MCP `2026-07-28` protocol through the official Python
SDK v2 and uses stateless Streamable HTTP for deployment.

## Features

- Typed tools with structured Pydantic output
- Generic calculator and deterministic catalog examples
- MCP tools, resources, and prompts
- Bearer-token boundary and per-tool scopes
- Request-size, host, and in-process rate limits
- Correlation IDs and structured request logs
- Public health and readiness probes
- Unit and HTTP integration tests
- Production-style non-root Docker image
- CI for lint, formatting, typing, tests, image build, secrets, and workflows

## Architecture

```text
HTTP request
  -> SecurityMiddleware (host, size, auth, rate limit, request ID)
  -> MCP Streamable HTTP transport
  -> typed tool/resource/prompt
  -> scope check
  -> deterministic domain function
```

Protocol registration lives in `src/mcp_server_kit/server.py`; reusable domain
logic stays in separate modules. `TokenStore` is intentionally a replaceable
deployment boundary, not a full authorization server.

## Quick start

Python 3.11+ is required.

```powershell
python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -e ".[dev]"
Copy-Item .env.example .env
.\scripts\dev.ps1
```

The MCP endpoint is `http://127.0.0.1:8000/mcp`. Health probes are available at
`/health` and `/ready`. The local-only demo tokens are:

- `demo-reader` — `catalog:read`
- `demo-operator` — `catalog:read`, `calculator:use`

Run MCP Inspector with `npx -y @modelcontextprotocol/inspector` and set an
`Authorization: Bearer demo-operator` header. A credential-free client shape
is available in `examples/client.json`; inject `MCP_CLIENT_TOKEN` locally.

## Commands

```powershell
.\scripts\dev.ps1    # development server with reload
.\scripts\check.ps1  # lint, format check, mypy, and tests
docker compose up --build
```

## Configuration

| Variable | Default | Purpose |
| --- | --- | --- |
| `MCP_ENVIRONMENT` | `development` | Rejects unsafe demo auth in production |
| `MCP_HOST` / `MCP_PORT` | `127.0.0.1` / `8000` | Bind address |
| `MCP_AUTH_MODE` | `demo` | `demo`, `bearer`, or local-only `disabled` |
| `MCP_BEARER_TOKENS` | empty | `token:scope[,scope];...` secret value |
| `MCP_ALLOWED_HOSTS` | local hosts | Exact accepted HTTP hostnames |
| `MCP_MAX_REQUEST_BYTES` | `1048576` | Maximum declared request body |
| `MCP_RATE_LIMIT_REQUESTS` | `60` | Requests allowed per subject/window |
| `MCP_RATE_LIMIT_WINDOW_SECONDS` | `60` | Rate-limit window |
| `MCP_LOG_LEVEL` | `INFO` | Uvicorn log level |

Never commit `.env`. See [security and deployment](docs/security.md) before an
internet-facing deployment and [adding tools](docs/adding-tools.md) when
extending the registry.

## Deployment notes

Set `MCP_ENVIRONMENT=production`, `MCP_AUTH_MODE=bearer`, a secret-managed
`MCP_BEARER_TOKENS` value, and the exact public host allowlist. Terminate TLS at
a trusted reverse proxy. Replace the starter token store with your OAuth 2.1
resource-server verifier when user delegation or token lifecycle management is
required.

## License

MIT