# public-mcp

A public MCP server on AWS Lambda that exposes deterministic checking tools.

**Status:** Plan 01 implemented: the three `spec.*` tools run locally over stateless
Streamable HTTP. No AWS deployment yet (Plan 03).

**Principle:** no server-side LLM: the client brings the model, the server checks, validates, seals.

See [Roadmap.md](Roadmap.md) and [.claude/plans/Plan-01.md](.claude/plans/Plan-01.md).

## Tools

| Tool | Input | Result |
|------|-------|--------|
| `spec.validate` | `spec` | `verdict` valid/invalid, `problems`, `modules` |
| `spec.check_tests` | `spec`, `tests`, `mode` = permissive/strict | `verdict` pass/fail, `violations`, `unknown_methods`, `mode` |
| `spec.check_impl` | `source` | `verdict` pass/fail, `classes_checked`, `violations` |

All inputs are text; caller code is parsed, never executed. Each text field may be at most
32 KiB (UTF-8) and an HTTP body at most 80 KiB. Invalid input (too large, not valid Python,
too deeply nested) is an MCP tool error (`isError: true`) whose message names the field.

## Run locally

Requires Python 3.12 or newer.

```bash
python -m venv .venv
```

```bash
.venv/bin/pip install -e ".[dev]"
```

```bash
.venv/bin/pytest
```

```bash
.venv/bin/ruff check .
```

Start the server (endpoint `http://127.0.0.1:8000/mcp`; `--host`/`--port` or
`PUBLIC_MCP_HOST`/`PUBLIC_MCP_PORT` override the defaults):

```bash
.venv/bin/python -m public_mcp.http
```

Inspect it with the MCP Inspector (UI), or list the tools from the command line:

```bash
npx @modelcontextprotocol/inspector@0.17.2 --cli http://127.0.0.1:8000/mcp --transport http --method tools/list
```

Add it to Claude Code:

```bash
claude mcp add --transport http public-mcp http://127.0.0.1:8000/mcp
```

## Layout

```
src/public_mcp/
  server.py      build_server(): registers the tools, transport-agnostic
  http.py        local stateless Streamable HTTP entry (python -m public_mcp.http)
  limits.py      MAX_FIELD_BYTES, MAX_BODY_BYTES, check_field()
  errors.py      tool error messages
  spec/          the checking core: pure, standard library only
  tools/         one adapter per tool: limits -> core -> structured result
tests/
```

## Provenance and licence

`src/public_mcp/spec/` is derived from [Agora](https://github.com/fabs133/agora) `v0.1.0`
(Copyright 2026 Agora contributors, Apache License 2.0) and maintained here; each module's
docstring names its source file, the functions taken and the changes made. This project is
licensed under the Apache License 2.0 (see `LICENSE`).