MCPサーバー + クライアント

PersonalKB: 実際のModel Context Protocol (MCP)サーバーであり、ノート検索に加えてライブの天気検索、そしてそれと通信するクライアント/エージェントです。MCPプロトコルレイヤーがモックされることは決してありません。すべてのテストは実際のサーバーサブプロセスを起動し、stdioまたは実際のHTTP経由で、その上で実際のJSON-RPCを行います。オフラインで偽装されるのは、LLM自身のツール選択判断だけです。最後の--realフラグ以外は、ここで何かを実行するのにAPIキーは必要ありません。

問題: 手作りのJSONブロブでモデルをツールに接続する方法は、2つ目のクライアント、リモートサーバー、または他人のツールが必要になるまでは機能します。MCPは、モデルがツールを発見・呼び出し、リソースを読み、プロンプトテンプレートを使用するための、実際のワイヤープロトコル上のAnthropicのオープン標準です。このプロジェクトは、そのプロトコルに沿って、デコレータから動作するクライアントブリッジとエージェントループに至るまで、実際のサーバーを構築します。

実証されているスキル: FastMCPを使用したMCPサーバー（ツール、リソース、プロンプト）の構築、stdioとstreamable-HTTPの両トランスポート、プロトコル経由でツールをライブに発見するクライアントブリッジ、オフラインの決定的ツールルーター、Claude APIに対する実際のエージェントループ、SQLite全文検索（FTS5）、そして実際のプロトコルトラフィックに対するpytest（モックなし）。

技術スタック: Python 3.10+、mcp SDK（FastMCP）、SQLite（標準ライブラリ）、実際のエージェント経路用のAnthropic SDK、ライブ天気用のrequests（Open-Meteo）、pytest。

公開するもの

mcp_kb.serverを実行すると、全文検索付きSQLiteに保存されたノートを対象とするMCPサーバー、PersonalKBが起動します。

• ツール: search_notes(query, limit)、add_note(title, body, tags)、list_tags()、get_weather(city)。

• リソース: note://{note_id}（1件のノートを取得）、notebook://summary（ノート全体の要約）。

• プロンプト: research_prompt(topic)、再利用可能なプロンプトテンプレート。

Related MCP server: MCP Apple Notes

実行方法

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は実際のサーバーを起動し、MCP経由でツールをライブに発見します。デフォルトではオフラインの決定的ルーターで質問に答え、--realを付けると実際のClaude APIを使います（.env内のANTHROPIC_API_KEYが必要）。

全体の構成

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

重要な設計上の選択: server.pyはdb.pyとweather.pyの薄いラッパーであり、MCPレイヤーの唯一の仕事は、プロトコルと素のPython関数の間を変換することです。この分割により、基盤となるロジックはプロトコルのオーバーヘッドなしでテスト可能になり、一方でプロトコルレイヤー自体もすべてのテストで実際に実行されます。

実際のMCPクライアントとの接続

同じサーバーは、実際のClaude Desktopアプリ内でもそのまま動作します。そのMCP設定をpython -m mcp_kb serveに向ければ、通常のチャットでserver.pyに定義されているまさにそのツールを呼び出して、ノートの検索や天気の確認ができます。接続手順と、リモートクライアントが到達できる場所へのHTTPトランスポートのデプロイについては、hosting/HOSTING_GUIDE.mdを参照してください。

学んだこと

• MCPは、ツールが何をするかとクライアントがそれをどのように見つけて呼び出すかを分離します。サーバーはツール、リソース、プロンプトを一度宣言するだけで、準拠したクライアント（自作のブリッジでもClaude Desktopでも）は、独自のグルーコードなしでそれらを発見して使用できます。

• プロトコルレイヤーを薄く保ち、ロジックを素のテスト可能なPython関数に移すことが、テストスイートが遅くも壊れやすくもならずに、実際のクライアント/サーバートラフィックを実行できるようにしたのです。

• stdioとstreamable-HTTPは、同じプロトコル上の単なる2つのトランスポートです。サーバーが公開するツール、リソース、プロンプトは、クライアントがどのように到達するかによって変わりません。