MCPサーバー開発ガイド

MCPサーバー開発ガイド は何をしますか？

概要

LLMが外部サービスとやり取りできるようにする、適切に設計されたツールを備えたMCP（Model Context Protocol）サーバーを作成します。MCPサーバーの品質は、LLMが実世界のタスクをどの程度達成できるかによって評価されます。

---

プロセス

🚀 高レベルワークフロー

高品質なMCPサーバーを作成するには、4つの主要フェーズがあります。

フェーズ1：徹底的な調査と計画

1.1 最新のMCP設計を理解する

APIカバレッジ vs ワークフローツール： 包括的なAPIエンドポイントカバレッジと、特殊なワークフローツールのバランスを取ります。ワークフローツールは特定のタスクに便利ですが、包括的なカバレッジによりエージェントは柔軟に操作を組み合わせられます。パフォーマンスはクライアントによって異なります。基本ツールを組み合わせたコード実行が効果的なクライアントもいれば、より高レベルのワークフローが有効なクライアントもいます。不明な場合は、包括的なAPIカバレッジを優先してください。

ツールの命名と発見容易性： 明確で説明的なツール名は、エージェントが適切なツールを迅速に見つけるのに役立ちます。一貫性のあるプレフィックス（例：github_create_issue、github_list_repos）とアクション指向の命名を使用してください。

コンテキスト管理： エージェントは簡潔なツール説明と、結果をフィルタリング/ページネーションする機能を活用します。焦点を絞った関連性の高いデータを返すツールを設計してください。一部のクライアントはコード実行をサポートしており、エージェントがデータを効率的にフィルタリング・処理するのに役立ちます。

実用的なエラーメッセージ： エラーメッセージは、具体的な提案と次のステップを示すことで、エージェントを解決策に導く必要があります。

1.2 MCPプロトコルドキュメントを学習する

MCP仕様を参照する：

サイトマップから関連ページを見つけます：https://modelcontextprotocol.io/sitemap.xml

その後、.md サフィックスを付けて特定のページを取得します（例：https://modelcontextprotocol.io/specification/draft.md）。

確認すべき主要ページ：

• 仕様の概要とアーキテクチャ
• トランスポートメカニズム（Streamable HTTP、stdio）
• ツール、リソース、プロンプトの定義

1.3 フレームワークドキュメントを学習する

推奨スタック：

• 言語: TypeScript（高品質なSDKサポート、多くの実行環境（例：MCPB）での互換性が良好。さらに、AIモデルはTypeScriptコードの生成に優れており、広範な使用、静的型付け、優れたリンティングツールの恩恵を受けられます）
• トランスポート: リモートサーバーにはStreamable 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/false
• destructiveHint: true/false
• idempotentHint: true/false
• openWorldHint: true/false

---

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

3.1 コード品質

以下を確認します：

• コードの重複なし（DRY原則）
• 一貫性のあるエラーハンドリング
• 完全な型カバレッジ
• 明確なツール説明

3.2 ビルドとテスト

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>動物のコードネームを持つ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）
  • ページネーションのベストプラクティス
  • トランスポート選択（Streamable 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形式仕様
  • 質問と回答の例
  • 提供スクリプトを使用した評価の実行