mini-mcp

MCP (Model Context Protocol)は、第一原理から約200行の読みやすいコードで実装されている。 サーバー、クライアント、そしてそれらの間のJSON-RPCメカニズム—すべてのエージェント統合が依存するツール呼び出しの中核であり、一気に読めるほど小さい。

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

SDKが存在するのに、なぜこれを構築するのか

フレームワークはプロトコルを隠す。そして隠されたプロトコルは、統合を配線できてもデバッグできないエンジニアを生み出す。コアを実装することで、SDKが実際に何をしているのかが分かる。MCPはトランスポート上のJSON-RPC 2.0であり、重要な3つのメソッド——initialize（ハンドシェイクと機能）、tools/list（JSON-Schema記述による発見）、tools/call（検証付き呼び出し）——を備えている。それを理解すれば、すべてのMCP SDKは便利なラッパーとして読める。実際、その通りである。

Related MCP server: toolbox-mcp

実装内容

スコープは意図的に絞られている。リソース、プロンプト、サンプリング、通知は対象外である。ツールのサブセットはエージェントが依存する部分であり、完全な小さなものは、不完全な大きなものに勝る。

議論に値する設計判断

トランスポートに依存しないサーバー。 handle_line は1つのリクエスト文字列を1つのレスポンス文字列にマッピングする。同じサーバーがstdio、ソケット、またはそれを直接呼び出す単体テスト上で動作する—そのため、プロトコルテストはサブプロセスを必要とせず、決して不安定にならない。

未知のツール引数は無視されず、拒否される。 宣言していないパラメータを受け取るツールは、本番環境に向かう途中のバグである。ここでの厳格さこそが、エージェントのツール呼び出しをデバッグ可能にする。

ツールの例外はクラッシュではなくプロトコルエラーになる。 バグのあるツールはサーバーやセッションをダウンさせてはならない。クライアントはメッセージ付きの -32603 を受け取り、ループは継続する。

bool は integer ではない。 Pythonの bool は int のサブクラスであるため、素朴なバリデータはカウントが入るべき場所で True を受け入れてしまう。これはそれを受け入れず、テストがそれを固定している。

テスト

PYTHONPATH=src python3 -m pytest tests -q

ハンドシェイク、検出、有効な呼び出しと無効な呼び出し、すべてのJSON-RPCエラーコード、そして実際のクライアントを実際のサーバーに対してサブプロセスとして実行する1つのエンドツーエンドテストをカバーする。

ライセンス

MIT