# mini-mcp

**MCP (Model Context Protocol), implemented from first principles in ~200 readable
lines.** A server, a client, and the JSON-RPC mechanics between them — the
tool-calling core that every agent integration depends on, small enough to read in
one sitting.

```bash
git clone https://github.com/harshadkhetpal/mini-mcp
cd mini-mcp
PYTHONPATH=src python3 -m minimcp.client
```

```
connected: mini-mcp-demo protocol 2025-06-18
tools discovered: calc.add, text.word_count, text.summarize_naive
calc.add(2, 40) -> 42
word_count -> 6
```

## Why build this when SDKs exist

Frameworks hide the protocol, and hidden protocols produce engineers who can wire an
integration but cannot debug one. Implementing the core teaches what the SDKs
actually do: MCP is JSON-RPC 2.0 over a transport, plus three methods that matter —
`initialize` (handshake and capabilities), `tools/list` (discovery with JSON-Schema
descriptions), and `tools/call` (validated invocation). Once that is understood, every
MCP SDK reads as a convenience wrapper, which is what it is.

## What's implemented

| Piece | Detail |
|---|---|
| **Server** | Tool registry via decorator, JSON-RPC dispatch, correct error codes (-32700 parse, -32600 invalid request, -32601 method not found, -32602 invalid params, -32603 internal) |
| **Schema validation** | Minimal JSON-Schema subset (type, required, properties), written not imported |
| **Client** | Spawns any stdio MCP server, handshakes, discovers, calls |
| **Demo server** | Three deterministic tools, so the loop runs offline |

Scope is deliberate: resources, prompts, sampling and notifications are out. The
tools subset is the part agents live on, and a complete small thing beats an
incomplete big one.

## Design decisions worth arguing with

**Transport-agnostic server.** `handle_line` maps one request string to one response
string. The same server runs over stdio, a socket, or a unit test calling it
directly — which is why the protocol tests need no subprocess and never flake.

**Unknown tool arguments are rejected, not ignored.** A tool receiving parameters it
never declared is a bug on its way to production. Strictness here is what makes agent
tool-calling debuggable.

**Tool exceptions become protocol errors, not crashes.** A buggy tool must not take
down the server or the session; the client gets `-32603` with the message, and the
loop continues.

**`bool` is not an `integer`.** Python's `bool` subclasses `int`, so naive validators
accept `True` where a count belongs. This one doesn't, and a test pins it.

## Testing

```bash
PYTHONPATH=src python3 -m pytest tests -q
```

Covers the handshake, discovery, valid and invalid calls, every JSON-RPC error code,
and one end-to-end test running the real client against the real server as a
subprocess.

## Licence

MIT