Mein Versuch, das Model Context Protocol zu verstehen, indem ich einen Server für die GitHub-API baue.

Python SDK v2, läuft über stdio und ist an Claude Code angebunden.

Was es tut

Zwei Tools, eines für eine Zusammenfassung eines Repos und eines für dessen letzte Commit-Nachrichten. Es gibt auch eine Ressource, die das rohe README eines Repos bereitstellt, und eine Prompt-Vorlage zur Bewertung eines Repos als Portfolio-Stück.

Related MCP server: MCP GitHub Reader

So führst du es aus

uv sync
uv run mcp dev server.py          # opens the inspector
uv run python test_server.py      # calls the server directly, no host needed

Um es bei Claude Code zu registrieren:

claude mcp add gh-lab -- uv run --directory /path/to/mcp-trial mcp run server.py

Was ich gelernt habe

Deine Typannotationen sind der eigentliche API-Vertrag, da das SDK das JSON-Schema der Tools direkt aus der Funktionssignatur erstellt. Wenn du limit: int = 5 schreibst, wird dieser Parameter dadurch auch optional – der Parameter kann also weggelassen werden.

Docstrings sind wichtiger, als ich erwartet hatte, weil sie als Tool-Beschreibung an das Modell gesendet werden und darüber entscheiden, welches Tool das Modell auswählt. Ich habe Claude Code gefragt, ob ein Repo aktiv gepflegt wird, und es hat beide Tools aufgerufen und die Sache selbst herausgefunden, was nur funktionierte, weil die Beschreibungen die Kombination nahegelegt haben.

Alles, was ein Tool zurückgibt, wird im Kontext des Modells zu Text, also kostet jedes Feld Tokens. GitHub liefert etwa hundert Felder zurück und ich gebe nur fünf zurück.

Einen Fehler zu werfen ist besser, als einen zurückzugeben, da das Werfen ein Flag setzt, das der Host prüft, und die Nachricht erreicht das Modell als etwas, auf das es reagieren kann.

Async macht nichts schneller. Ein einzelner Aufruf dauert genauso lange. Was await bewirkt, ist, die Funktion zu pausieren und die Ereignisschleife freizugeben, damit andere Aufrufe während des Wartens laufen können.

Notizen

mcp-reference.md enthält meine handschriftlichen Notizen aus der Entwicklung.