mcp-trial

Model Context Protocol を学ぶために、GitHub API 用のサーバーを構築しています。Python SDK v2 で、stdio 上で動作し、Claude Code に接続されています。

機能

2つのツールがあります。1つはリポジトリの概要用、もう1つは最近のコミットメッセージ用です。また、リポジトリの生の README を提供するリソースと、リポジトリをポートフォリオ作品として評価するためのプロンプトテンプレートもあります。

Related MCP server: MCP GitHub Reader

実行方法

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

Claude Code に登録するには:

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

学んだこと

型ヒントが実際の API 契約になります。SDK が関数シグネチャから直接ツールの JSON スキーマを構築するからです。limit: int = 5 と書くと、そのパラメータはオプションになり、モデルはそれを省略できます。

ドキュメント文字列は思った以上に重要でした。モデルにツールの説明として送られ、どのツールを選ぶかを決定するからです。Claude Code にリポジトリが活発にメンテナンスされているか尋ねたところ、両方のツールを呼び出して解決しました。これは、説明が組み合わせ可能に見えたからこそ起こったことです。

ツールが返すものはすべてモデルのコンテキスト内のテキストになるため、各フィールドはトークンを消費します。GitHub は約100のフィールドを返しますが、私は5つだけ返します。

エラーを返すよりも例外を発生させる方が優れています。例外を発生させるとホストがチェックするフラグが設定され、メッセージがモデルに届いて対処可能になるからです。

非同期は何も速くしません。単一の呼び出しはどちらでも同じ時間がかかります。await が行うのは、関数を一時停止してイベントループを解放し、待機中に他の呼び出しを実行できるようにすることです。

メモ

mcp-reference.md には、これを構築する際の作業メモがあります。