David-Li0406/meta-skill-evolving

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）。

確認すべき主要ページ：

• 仕様の概要とアーキテクチャ
• トランスポートメカニズム（ストリーミング可能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ドキュメントをレビューして、主要なエンドポイント、認証要件、データモデルを特定します。必要に応じてWeb検索とWebFetchを使用します。

ツールの選択: 包括的なAPIカバレッジを優先します。最も一般的な操作から始めて、実装するエンドポイントをリストアップします。

---

フェーズ2: 実装

2.1 プロジェクト構造をセットアップする

プロジェクトのセットアップについては、言語固有のガイドを参照してください：

• ⚡ TypeScriptガイド - プロジェクト構造、package.json、tsconfig.json
• 🐍 Pythonガイド - モジュール構成、依存関係

2.2 コアインフラを実装する

共有ユーティリティを作成します：

• 認証付きAPIクライアント
• エラーハンドリングヘルパー
• レスポンスフォーマット（JSON/マークダウン）
• ページネーションサポート

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. コンテンツの探索: READ-ONLY操作を使用して利用可能なデータを探索する
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 マークダウン）
  • ページネーションのベストプラクティス
  • トランスポートの選択（ストリーミング可能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形式の仕様
  • 質問と回答の例
  • 提供されたスクリプトを使用した評価の実行