MCP サーバー開発ガイド

概要

LLM（大規模言語モデル）が外部サービスと対話できるようにする、よく設計されたツールを備えた MCP (Model Context Protocol) サーバーを作成します。MCP サーバーの品質は、LLM が現実世界のタスクをどの程度効果的に達成できるかで測定されます。

重要: 既存のものを確認する

MCP サーバーを作成する前に、以下を確認してください:

既存の MCP サーバーを確認:

ls -la mcp-servers/ src/mcp/ 2>/dev/null
rg "McpServer|FastMCP|@modelcontextprotocol" --type ts --type py

既存の統合を確認:

cat package.json | grep -i "mcp\|modelcontextprotocol"
cat pyproject.toml requirements.txt 2>/dev/null | grep -i "mcp\|fastmcp"

MCP 設定を確認:

cat mcp.json .mcp/config.json claude_desktop_config.json 2>/dev/null

既存のツールパターンを確認:

既存のツール命名規則をチェック
使用中の認証パターンを確認
共有ユーティリティを探索

理由: MCP サーバーは一貫したパターンに従うべきです。既存のインフラを再利用します。

プロセス

🚀 高レベルワークフロー

高品質な MCP サーバーの作成には、4 つの主要なフェーズが含まれます:

フェーズ 1: 深い調査と計画

1.1 モダン MCP デザインを理解する

API カバレッジ対ワークフローツール: 包括的な API エンドポイントカバレッジと特定のワークフロータスク用の特化したツールのバランスを取ってください。ワークフローツールは特定のタスクにより便利な場合がありますが、包括的なカバレッジはエージェントに操作を組み合わせる柔軟性を与えます。パフォーマンスはクライアントによって異なります。基本的なツールを組み合わせるコード実行の恩恵を受けるクライアントもあれば、より高度なワークフローがうまく機能するクライアントもあります。不確定な場合は、包括的な API カバレッジを優先してください。

ツール命名と発見可能性: 明確で説明的なツール名は、エージェントが適切なツールを素早く見つけるのに役立ちます。一貫したプレフィックス (例: github_create_issue, github_list_repos) とアクション指向の命名を使用してください。

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

実行可能なエラーメッセージ: エラーメッセージは、エージェントに具体的な提案と次のステップを含めて解決策に導くべきです。

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

MCP 仕様をナビゲート:

サイトマップで関連ページを探してください: https://modelcontextprotocol.io/sitemap.xml

次に、マークダウン形式で特定のページを取得してください (例: https://modelcontextprotocol.io/specification/draft.md)。

確認すべき主要ページ:

仕様の概要とアーキテクチャ
トランスポート機構 (ストリーム可能な HTTP、stdio)
ツール、リソース、プロンプト定義

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

推奨スタック:

言語: TypeScript (高品質の SDK サポートと多くの実行環境での互換性の良さ)
トランスポート: リモートサーバーではストリーム可能な HTTP、ステートレス JSON を使用。ローカルサーバーでは stdio。

フレームワークドキュメントをロード:

MCP ベストプラクティス: reference/mcp_best_practices.md を参照

TypeScript の場合 (推奨):

TypeScript SDK: WebFetch を使用して https://raw.githubusercontent.com/modelcontextprotocol/typescript-sdk/main/README.md をロード

Python の場合:

Python SDK: WebFetch を使用して https://raw.githubusercontent.com/modelcontextprotocol/python-sdk/main/README.md をロード

1.4 実装を計画する

API を理解する: サービスの API ドキュメントをレビューして、主要なエンドポイント、認証要件、データモデルを特定してください。必要に応じてウェブ検索と WebFetch を使用してください。

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

フェーズ 2: 実装

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

TypeScript プロジェクトセットアップ:

// package.json
{
  "name": "my-mcp-server",
  "type": "module",
  "scripts": {
    "build": "tsc",
    "start": "node dist/index.js"
  },
  "dependencies": {
    "@modelcontextprotocol/sdk": "^1.0.0",
    "zod": "^3.23.0"
  },
  "devDependencies": {
    "typescript": "^5.0.0"
  }
}

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

共有ユーティリティを作成:

認証付き API クライアント
エラー処理ヘルパー
レスポンスのフォーマット (JSON/Markdown)
ページネーションサポート

2.3 ツールを実装する

各ツール:

入力スキーマ:

Zod (TypeScript) または Pydantic (Python) を使用
制約と明確な説明を含める
フィールド説明に例を追加

出力スキーマ:

構造化されたデータの場合は outputSchema を定義
ツールレスポンスで structuredContent を使用 (TypeScript SDK の機能)
クライアントがツール出力を理解して処理するのに役立ちます

ツール説明:

機能の簡潔な概要
パラメータの説明
リターン型スキーマ

実装:

I/O 操作の非同期/待機
実行可能なメッセージを含む適切なエラー処理
適用可能な場所ではページネーションをサポート
モダン 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 個の評価質問を作成する

ツール検査: 利用可能なツールとその機能を一覧表示して理解する
コンテンツ探索: 読み取り専用操作を使用して利用可能なデータを探索する
質問生成: 10 個の複雑で現実的な質問を作成する
回答検証: 各質問を自分で解いて回答を検証する

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>
<!-- More qa_pairs... -->
</evaluation>

ライセンス: MIT(寛容ライセンスのため全文を引用しています) · 原本リポジトリ

meta-mcp-builder

SKILL.md 本文