MCPサーバー開発ガイド
概要
LLMが適切に設計されたツールを通じて外部サービスと連携できるMCP(Model Context Protocol)サーバーを作成します。MCPサーバーの品質は、LLMが実世界のタスクをどれだけうまく達成できるかによって評価されます。
プロセス
🚀 ハイレベルワークフロー
高品質なMCPサーバーの作成は、主に4つのフェーズで構成されます。
フェーズ1:詳細な調査と計画
1.1 現代のMCP設計を理解する
APIカバレッジとワークフローツールのバランス: 包括的なAPIエンドポイントカバレッジと、特殊なワークフローツールのバランスを取ります。ワークフローツールは特定のタスクに便利ですが、包括的なカバレッジはエージェントに操作を構成する柔軟性を与えます。パフォーマンスはクライアントによって異なります。基本ツールを組み合わせたコード実行が有効なクライアントもいれば、より高レベルのワークフローが適しているクライアントもいます。不明な場合は、包括的なAPIカバレッジを優先してください。
ツールの命名と発見可能性:
明確で説明的なツール名は、エージェントが適切なツールを素早く見つけるのに役立ちます。一貫性のあるプレフィックス(例:github_create_issue、github_list_repos)とアクション指向の命名を使用します。
コンテキスト管理: エージェントは簡潔なツール説明と結果のフィルタリング/ページネーション機能の恩恵を受けます。焦点を絞った関連データを返すツールを設計します。一部のクライアントはコード実行をサポートしており、エージェントがデータを効率的にフィルタリングおよび処理するのに役立ちます。
実用的なエラーメッセージ: エラーメッセージは、具体的な提案と次のステップを提示することで、エージェントを解決策に導く必要があります。
1.2 MCPプロトコルドキュメントの学習
MCP仕様を確認する:
サイトマップから関連ページを見つけます:https://modelcontextprotocol.io/sitemap.xml
次に、.mdサフィックスを付けて特定のページをフェッチします(例:https://modelcontextprotocol.io/specification/draft.md)。
確認すべき主要ページ:
- 仕様の概要とアーキテクチャ
- トランスポートメカニズム(ストリーミング可能HTTP、stdio)
- ツール、リソース、プロンプトの定義
1.3 フレームワークドキュメントの学習
推奨スタック:
- 言語:TypeScript(高品質なSDKサポート、多くの実行環境(例:MCPB)での互換性が良好。さらに、AIモデルはTypeScriptコードの生成が得意で、幅広い使用実績、静的型付け、優れたリンターツールの恩恵を受けられる)
- トランスポート:リモートサーバーにはストリーミング可能HTTP(ステートフルなセッションやストリーミング応答とは対照的に、ステートレスなJSONの方がスケールとメンテナンスが容易)。ローカルサーバーにはstdio。
フレームワークドキュメントを読み込む:
- MCPベストプラクティス: 📋 ベストプラクティスを表示 - コアガイドライン
TypeScript(推奨)の場合:
- TypeScript SDK: WebFetchを使用して
https://raw.githubusercontent.com/modelcontextprotocol/typescript-sdk/main/README.mdを読み込みます - ⚡ TypeScriptガイド - TypeScriptのパターンと例
Pythonの場合:
- Python SDK: WebFetchを使用して
https://raw.githubusercontent.com/modelcontextprotocol/python-sdk/main/README.mdを読み込みます - 🐍 Pythonガイド - Pythonのパターンと例
1.4 実装計画を立てる
APIを理解する: サービスのAPIドキュメントを確認し、主要なエンドポイント、認証要件、データモデルを特定します。必要に応じてウェブ検索とWebFetchを使用します。
ツールの選択: 包括的なAPIカバレッジを優先します。最も一般的な操作から始めて、実装するエンドポイントをリストアップします。
フェーズ2:実装
2.1 プロジェクト構造のセットアップ
プロジェクトのセットアップについては、言語固有のガイドを参照してください:
- ⚡ TypeScriptガイド - プロジェクト構造、package.json、tsconfig.json
- 🐍 Pythonガイド - モジュール構成、依存関係
2.2 コアインフラストラクチャの実装
共有ユーティリティを作成する:
- 認証機能付きAPIクライアント
- エラーハンドリングヘルパー
- レスポンスフォーマット(JSON/Markdown)
- ページネーションサポート
2.3 ツールの実装
各ツールについて:
入力スキーマ:
- Zod(TypeScript)またはPydantic(Python)を使用
- 制約と明確な説明を含める
- フィールドの説明に例を追加
出力スキーマ:
- 構造化データが可能な場合は
outputSchemaを定義 - ツールレスポンスで
structuredContentを使用(TypeScript SDKの機能) - クライアントがツール出力を理解して処理するのに役立つ
ツールの説明:
- 機能の簡潔な要約
- パラメータの説明
- 戻り値の型スキーマ
実装:
- I/O操作にはasync/await
- 実用的なメッセージによる適切なエラーハンドリング
- 該当する場合はページネーションをサポート
- 最新のSDKを使用する場合は、テキストコンテンツと構造化データの両方を返す
注釈:
readOnlyHint:true/falsedestructiveHint:true/falseidempotentHint:true/falseopenWorldHint:true/false
フェーズ3:レビューとテスト
3.1 コード品質
以下を確認する:
- 重複コードがないこと(DRY原則)
- 一貫性のあるエラーハンドリング
- 完全な型カバレッジ
- 明確なツール説明
3.2 ビルドとテスト
TypeScript:
npm run buildを実行してコンパイルを確認- MCPインスペクターでテスト:
npx @modelcontextprotocol/inspector
Python:
- 構文確認:
python -m py_compile your_server.py - MCPインスペクターでテスト
詳細なテストアプローチと品質チェックリストについては、言語固有のガイドを参照してください。
フェーズ4:評価の作成
MCPサーバーを実装したら、包括的な評価を作成してその効果をテストします。
完全な評価ガイドラインについては、✅ 評価ガイドを読み込んでください。
4.1 評価の目的を理解する
評価を使用して、LLMがMCPサーバーを効果的に使用して、現実的で複雑な質問に回答できるかどうかをテストします。
4.2 10個の評価質問を作成する
効果的な評価を作成するには、評価ガイドに概説されているプロセスに従います:
- ツール検査:利用可能なツールをリストアップし、その機能を理解する
- コンテンツ探索:読み取り専用操作を使用して、利用可能なデータを探索する
- 質問生成:10個の複雑で現実的な質問を作成する
- 回答検証:各質問を自分で解決して回答を検証する
4.3 評価要件
各質問が以下を満たしていることを確認する:
- 独立している:他の質問に依存しない
- 読み取り専用:破壊的な操作が不要
- 複雑:複数のツール呼び出しと深い探索が必要
- 現実的:人間が気にする実際のユースケースに基づいている
- 検証可能:文字列比較で検証できる単一の明確な回答がある
- 安定している:回答が時間の経過とともに変わらない
4.4 出力形式
以下の構造のXMLファイルを作成する:
<evaluation>
<qa_pair>
<question>動物コードネームを持つAIモデルのローンチに関する議論を見つけてください。あるモデルには、ASL-X形式の特定の安全性指定が必要でした。斑点のある野生の猫にちなんで名付けられたモデルについて、どの番号Xが決定されていましたか?</question>
<answer>3</answer>
</qa_pair>
<!-- その他のqa_pair... -->
</evaluation>
リファレンスファイル
📚 ドキュメントライブラリ
開発中に必要に応じてこれらのリソースを読み込んでください:
コアMCPドキュメント(最初に読み込む)
- MCPプロトコル:
https://modelcontextprotocol.io/sitemap.xmlのサイトマップから始め、.mdサフィックスを付けて特定のページをフェッチする - 📋 MCPベストプラクティス - 普遍的なMCPガイドライン。以下を含む:
- サーバーとツールの命名規則
- レスポンス形式ガイドライン(JSON vs Markdown)
- ページネーションのベストプラクティス
- トランスポート選択(ストリーミング可能HTTP vs stdio)
- セキュリティとエラーハンドリングの標準
SDKドキュメント(フェーズ1/2で読み込む)
- Python SDK:
https://raw.githubusercontent.com/modelcontextprotocol/python-sdk/main/README.mdからフェッチ - TypeScript SDK:
https://raw.githubusercontent.com/modelcontextprotocol/typescript-sdk/main/README.mdからフェッチ
言語固有の実装ガイド(フェーズ2で読み込む)
-
🐍 Python実装ガイド - 完全なPython/FastMCPガイド。以下を含む:
- サーバー初期化パターン
- Pydanticモデルの例
@mcp.toolによるツール登録- 完全な動作例
- 品質チェックリスト
-
⚡ TypeScript実装ガイド - 完全なTypeScriptガイド。以下を含む:
- プロジェクト構造
- Zodスキーマパターン
server.registerToolによるツール登録- 完全な動作例
- 品質チェックリスト
評価ガイド(フェーズ4で読み込む)
- ✅ 評価ガイド - 完全な評価作成ガイド。以下を含む:
- 質問作成ガイドライン
- 回答検証戦略
- XML形式の仕様
- 質問と回答の例
- 提供されたスクリプトを使用した評価の実行