MCP Server + Client

PersonalKB: ein echter Model Context Protocol (MCP)-Server, Notizsuche plus eine Live-Wetterabfrage und ein Client/Agent, der mit ihm kommuniziert. Die MCP-Protokollebene wird niemals gemockt: Jeder Test startet einen echten Server-Subprozess und führt echte JSON-RPC-Kommunikation darüber durch, entweder über stdio oder über echtes HTTP. Das Einzige, was offline simuliert wird, ist die Tool-Auswahl-Entscheidung des LLM selbst; um hier irgendetwas auszuführen, wird kein API-Schlüssel benötigt, außer für das finale --real-Flag.

Problem: Ein Modell mit einem handgestrickten JSON-Blob an Tools anzubinden funktioniert, bis du einen zweiten Client, einen entfernten Server oder die Tools von jemand anderem brauchst. MCP ist der offene Standard von Anthropic dafür, wie ein Modell Tools entdeckt und aufruft, Ressourcen liest und Prompt-Vorlagen verwendet – stattdessen über ein echtes Drahtprotokoll. Dieses Projekt baut einen echten Server gegen dieses Protokoll, von den Dekoratoren bis hin zu einer funktionierenden Client-Brücke und Agenten-Schleife.

Gezeigte Fähigkeiten: Aufbau eines MCP-Servers (Tools, Ressourcen, Prompts) mit FastMCP, sowohl stdio- als auch streamable-HTTP-Transporte, eine Client-Brücke, die Tools live über das Protokoll entdeckt, ein deterministischer Offline-Tool-Router und eine echte agentische Schleife gegen die Claude API, SQLite-Volltextsuche (FTS5) sowie pytest gegen echten Protokollverkehr (ohne Mocking).

Tech-Stack: Python 3.10+, das mcp SDK (FastMCP), SQLite (Standardbibliothek), das Anthropic SDK für den echten Agent-Pfad, requests für Live-Wetter (Open-Meteo), pytest.

Was es bereitstellt

Das Ausführen von mcp_kb.server startet einen MCP-Server, PersonalKB, der auf Notizen aufsetzt, die in SQLite mit Volltextsuche gespeichert sind:

• Tools: search_notes(query, limit), add_note(title, body, tags), list_tags(), get_weather(city).

• Ressourcen: note://{note_id} (eine Notiz abrufen), notebook://summary (eine Zusammenfassung des gesamten Notizbuchs).

• Prompt: research_prompt(topic), eine wiederverwendbare Prompt-Vorlage.

Related MCP server: MCP Apple Notes

Ausführen

python -m venv .venv ; .\.venv\Scripts\Activate.ps1
pip install -r requirements.txt
python generate_data.py           # seeds data/notes.db with 15 hand-written notes

python -m mcp_kb tools                                  # list tools/resources/prompts
python -m mcp_kb ask "find notes about python"
python -m mcp_kb ask "what's the weather in Paris"
python -m mcp_kb serve                                  # run the server directly (stdio)
python -m mcp_kb serve --http                            # or over streamable-HTTP

pytest -q                          # the full suite, all real protocol traffic, no key needed

ask startet den echten Server, entdeckt seine Tools live über MCP und beantwortet deine Frage standardmäßig mit einem deterministischen Offline-Router oder mit der echten Claude API, wenn --real gesetzt ist (dafür wird ANTHROPIC_API_KEY in .env benötigt).

Wie es zusammenspielt

mcp_kb/
├── db.py         SQLite + FTS5 notes store: search, add, tags
├── weather.py     an offline table, or real keyless Open-Meteo data with --live-weather
├── server.py      the actual MCP server (FastMCP-based): tools, resources, a prompt
├── bridge.py       the MCP client wrapper: discovers tools/resources/prompts live
├── llm.py         the offline deterministic tool-choice router
├── agent.py        the agentic loop: offline router, or a real Claude tool-use loop
└── cli.py           python -m mcp_kb tools|ask|serve
tests/                41 tests, all real protocol traffic (stdio and HTTP), no mocking

Die entscheidende Designentscheidung: server.py ist ein dünner Wrapper um db.py und weather.py; die einzige Aufgabe der MCP-Ebene ist es, zwischen dem Protokoll und einfachen Python-Funktionen zu übersetzen. Genau diese Trennung macht die zugrunde liegende Logik ohne Protokoll-Overhead testbar, während die Protokollebene selbst in jedem Test real durchlaufen wird.

Einen echten MCP-Client verbinden

Derselbe Server läuft auch unverändert in der echten Claude Desktop-App: Richte die MCP-Konfiguration auf python -m mcp_kb serve aus, und sie kann in einem normalen Chat deine Notizen durchsuchen oder das Wetter abfragen, wobei sie genau die in server.py definierten Tools aufruft. Siehe hosting/HOSTING_GUIDE.md für die Verbindungsschritte und für die Bereitstellung des HTTP-Transports an einem Ort, den ein entfernter Client erreichen kann.

Was ich gelernt habe

• MCP trennt was ein Tool tut von wie ein Client es findet und aufruft: Der Server deklariert Tools, Ressourcen und Prompts einmal, und jeder konforme Client (eine handgestrickte Brücke oder Claude Desktop) kann sie ohne eigenen Klebecode entdecken und nutzen.

• Die Protokollebene dünn zu halten und die Logik in einfache, testbare Python-Funktionen zu verschieben, hat es der Testsuite ermöglicht, echten Client/Server-Verkehr auszuführen, ohne dass es langsam oder zerbrechlich ist.

• stdio und streamable-HTTP sind nur zwei Transporte unter demselben Protokoll; die Tools, Ressourcen und Prompts, die ein Server bereitstellt, ändern sich nicht dadurch, wie ein Client ihn erreicht.