protocol-implementation-framework

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/llms-full.txt を確認してください。 特定のページを確認する場合は、サイトマップ https://modelcontextprotocol.io/sitemap.xml から始めてください。

次に、特定のページを .md サフィックス付きで取得し、Markdown 形式で確認します（例：https://modelcontextprotocol.io/specification/draft.md）。

確認すべき主なページ：

• 仕様の概要とアーキテクチャ
• トランスポート方式（ストリーミング可能な HTTP、stdio）
• ツール、リソース、プロンプトの定義

1.3 フレームワークのドキュメントを調べる

推奨スタック：

• 言語：TypeScript（高品質な SDK サポートがあり、MCPB など、多くの実行環境との互換性に優れています。また、AI モデルは TypeScript コードの生成が得意です。幅広く利用され、静的型付けと優れたリンティングツールを備えていることも利点です）
• トランスポート：リモートサーバーには、ステートレス JSON を使用するストリーミング可能な HTTP（ステートフルなセッションやストリーミング応答より、スケーリングとメンテナンスが簡単です）。ローカルサーバーには 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/false
• destructiveHint: true/false
• idempotentHint: true/false
• openWorldHint: true/false

---

フェーズ 3：レビューとテスト

3.1 コード品質

次の点を確認します：

• 重複コードがない（DRY 原則）
• エラー処理に一貫性がある
• 型が完全に網羅されている
• ツールの説明が明確である

3.2 ビルドとテスト

注： MCP サーバーは長時間実行されるプロセスです。直接実行すると、リクエストを待つためにプロセスがブロックされます。評価ハーネスを使用するか、別のセッション（tmux）でサーバーを実行するか、タイムアウトを設定して実行してください。

TypeScript：

• npm run build を実行してコンパイルを確認します
• MCP Inspector でテストします：npx @modelcontextprotocol/inspector

Python：

• 構文を確認します：python -m py_compile your_server.py
• MCP Inspector でテストします

詳しいテスト方法と品質チェックリストについては、各言語のガイドを参照してください。

---

フェーズ 4：評価を作成する

MCP サーバーを実装したら、その有効性をテストするための包括的な評価を作成します。

完全な評価ガイドラインについては、✅ 評価ガイドを読み込んでください。

4.1 評価の目的を理解する

評価を使用して、LLM が MCP サーバーを効果的に利用し、現実的で複雑な質問に回答できるかをテストします。

4.2 評価用の質問を 10 件作成する

効果的な評価を作成するには、評価ガイドに記載されている手順に従います。

1. ツールの調査：利用可能なツールを一覧表示し、それぞれの機能を理解します
2. コンテンツの探索：読み取り専用操作を使用して、利用可能なデータを探索します
3. 質問の作成：複雑で現実的な質問を 10 件作成します
4. 回答の検証：各質問を自分で解いて、回答を検証します

4.3 評価の要件

各質問が次の条件を満たすようにします：

• 独立している：ほかの質問に依存しない
• 読み取り専用である：破壊的でない操作のみを必要とする
• 複雑である：複数のツール呼び出しと詳細な探索を必要とする
• 現実的である：人々が関心を持つ実際のユースケースに基づいている
• 検証可能である：文字列比較で検証できる、明確で一意の回答がある
• 安定している：回答が時間の経過によって変化しない

4.4 出力形式

次の構造の XML ファイルを作成します：

<evaluation>
  <qa_pair>
    <question>Find discussions about AI model launches with animal codenames. One model needed a specific safety designation that uses the format ASL-X. What number X was being determined for the model named after a spotted wild cat?</question>
    <answer>3</answer>
  </qa_pair>

</evaluation>

---

リファレンスファイル

📚 ドキュメントライブラリ

開発中、必要に応じて以下のリソースを読み込みます。

MCP のコアドキュメント（最初に読み込む）

• MCP プロトコル：仕様全体については https://modelcontextprotocol.io/llms-full.txt を優先してください。特定のページを参照するには、サイトマップ https://modelcontextprotocol.io/sitemap.xml を使用してください。
• 📋 MCP のベストプラクティス - 次の項目を含む、MCP 全般のガイドライン：
  • サーバーとツールの命名規則
  • レスポンス形式のガイドライン（JSON と Markdown）
  • ページネーションのベストプラクティス
  • トランスポートの選択（ストリーミング可能な HTTP と 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 形式の仕様
  • 質問と回答の例
  • 提供されたスクリプトを使った評価の実行