agencelutie/LP-lutie

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コードの生成に優れており、その幅広い使用、静的型付け、優れたリンティングツールの恩恵を受けています）
• トランスポート：リモートサーバーにはストリーミング可能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/マークダウン）
• ページネーションサポート

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 マークダウン）
  • ページネーションのベストプラクティス
  • トランスポート選択（ストリーミング可能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形式の仕様
  • 質問と回答の例
  • 提供されたスクリプトを使用した評価の実行