mini-mcp

MCP (Model Context Protocol), aus ersten Prinzipien in ~200 lesbaren Zeilen implementiert. Ein Server, ein Client und die JSON-RPC-Mechanik dazwischen — der Kern für Werkzeugaufrufe, von dem jede Agent-Integration abhängt, klein genug, um in einer Sitzung gelesen zu werden.

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

Warum das bauen, wenn es SDKs gibt

Frameworks verbergen das Protokoll, und verborgene Protokolle erzeugen Ingenieure, die eine Integration verdrahten, aber nicht debuggen können. Die Implementierung des Kerns lehrt, was die SDKs tatsächlich tun: MCP ist JSON-RPC 2.0 über einen Transport, plus drei Methoden, die zählen — initialize (Handshake und Fähigkeiten), tools/list (Entdeckung mit JSON-Schema-Beschreibungen) und tools/call (validierter Aufruf). Sobald das verstanden ist, liest sich jedes MCP-SDK als Komfort-Wrapper, was es auch ist.

Related MCP server: toolbox-mcp

Was implementiert ist

Der Umfang ist bewusst gewählt: Ressourcen, Prompts, Sampling und Benachrichtigungen sind ausgeschlossen. Die Werkzeug-Teilmenge ist der Teil, von dem Agenten leben, und ein vollständiges kleines Ding schlägt ein unvollständiges großes.

Designentscheidungen, über die es sich zu streiten lohnt

Transportunabhängiger Server. handle_line bildet eine Anfragezeichenkette auf eine Antwortzeichenkette ab. Derselbe Server läuft über stdio, einen Socket oder einen Unit-Test, der ihn direkt aufruft — weshalb die Protokolltests keinen Subprozess benötigen und nie flaky sind.

Unbekannte Werkzeugargumente werden abgelehnt, nicht ignoriert. Ein Werkzeug, das Parameter erhält, die es nie deklariert hat, ist ein Bug auf dem Weg in die Produktion. Striktheit hier macht Werkzeugaufrufe durch Agenten debugbar.

Werkzeugausnahmen werden zu Protokollfehlern, nicht zu Abstürzen. Ein fehlerhaftes Werkzeug darf weder den Server noch die Sitzung zu Fall bringen; der Client erhält -32603 mit der Nachricht, und die Schleife läuft weiter.

bool ist kein integer. Pythons bool ist eine Unterklasse von int, daher akzeptieren naive Validierer True, wo eine Anzahl hingehört. Dieses hier nicht, und ein Test hält das fest.

Tests

PYTHONPATH=src python3 -m pytest tests -q

Deckt den Handshake, die Entdeckung, gültige und ungültige Aufrufe, jeden JSON-RPC-Fehlercode und einen Ende-zu-Ende-Test ab, der den echten Client gegen den echten Server als Subprozess ausführt.

Lizenz

MIT