MCP Server Development Guide

Overview

LLMが外部サービスと相互作用できるようにする、適切に設計されたツールを備えたMCP (Model Context Protocol) サーバーを作成します。MCPサーバーの品質は、LLMが実際のタスクを達成できるようにサポートする程度によって測定されます。

---

Process

🚀 High-Level Workflow

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

Phase 1: Deep Research and Planning

1.1 Modern MCP Designの理解

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

Tool Naming and Discoverability: 明確で説明的なツール名により、エージェントが適切なツールをすばやく見つけられます。一貫したプレフィックス (例: github_create_issue、github_list_repos) とアクション志向の命名を使用します。

Context Management: エージェントは簡潔なツール説明と、結果をフィルタリング/ページネーションできる機能から恩恵を受けます。焦点を絞った関連データを返すツールを設計します。一部のクライアントはコード実行をサポートしており、エージェントがデータを効率的にフィルタリングおよび処理するのに役立ちます。

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

1.2 MCPプロトコルドキュメントの学習

MCPスペシフィケーションをナビゲート:

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

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

確認すべき主要ページ:

• Specification overview and architecture
• Transport mechanisms (streamable HTTP, stdio)
• Tool, resource, and prompt definitions

1.3 Framework Documentationの学習

推奨スタック:

• Language: TypeScript (高品質なSDKサポートと多くの実行環境での良好な互換性。例: MCPB。加えて、AIモデルはTypeScriptコードの生成に優れており、広範な使用、静的型付け、優れたlintingツールから恩恵を受けます)
• Transport: リモートサーバーの場合はStreamable HTTP、ステートレスJSON (ステートフルセッションおよびストリーミングレスポンスよりも、スケールと保守がシンプル)。ローカルサーバーの場合はstdio。

Framework documentationをロード:

• MCP Best Practices: 📋 View Best Practices - Core guidelines

TypeScript (推奨) の場合:

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

Pythonの場合:

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

1.4 実装計画

APIを理解: サービスのAPIドキュメントをレビューして、主要なエンドポイント、認証要件、およびデータモデルを特定します。必要に応じて、Web検索とWebFetchを使用します。

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

---

Phase 2: Implementation

2.1 プロジェクト構造の設定

言語固有のガイドでプロジェクトセットアップを参照:

• ⚡ TypeScript Guide - Project structure, package.json, tsconfig.json
• 🐍 Python Guide - Module organization, dependencies

2.2 コアインフラストラクチャの実装

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

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

2.3 Toolsの実装

各ツールについて:

Input Schema:

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

Output Schema:

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

Tool Description:

• 機能の簡潔な概要
• パラメータの説明
• 戻り値のスキーマ

Implementation:

• I/O操作の非同期/待機
• アクション可能なメッセージを含む適切なエラーハンドリング
• 該当する場合はページネーションサポート
• モダンSDKを使用する場合、テキストコンテンツと構造化データの両方を返す

Annotations:

• readOnlyHint: true/false
• destructiveHint: true/false
• idempotentHint: true/false
• openWorldHint: true/false

---

Phase 3: Review and Test

3.1 コード品質

以下をレビュー:

• 重複したコードがない (DRY principle)
• 一貫したエラーハンドリング
• 完全な型カバレッジ
• 明確なツール説明

3.2 Build and Test

TypeScript:

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

Python:

• 構文を確認: python -m py_compile your_server.py
• MCP Inspectorでテスト

詳細なテストアプローチと品質チェックリストについては、言語固有のガイドを参照してください。

---

Phase 4: Create Evaluations

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

✅ Evaluation Guide をロードして、完全な評価ガイドラインを確認してください。

4.1 評価目的の理解

評価を使用して、LLMがMCPサーバーを効果的に使用して現実的な複雑な質問に答えられるかどうかをテストします。

4.2 10個の評価質問の作成

効果的な評価を作成するには、評価ガイドで概説されているプロセスに従います:

1. Tool Inspection: 利用可能なツールをリストアップし、その機能を理解
2. Content Exploration: READ-ONLY操作を使用して利用可能なデータを探索
3. Question Generation: 10個の複雑でリアルな質問を作成
4. Answer Verification: 各質問に自分で答えて、答えを確認

4.3 評価要件

各質問は以下であることを確認:

• Independent: 他の質問に依存していない
• Read-only: 非破壊的な操作のみが必要
• Complex: 複数のツール呼び出しと深い探索が必要
• Realistic: 人間が気にかける実際のユースケースに基づいている
• Verifiable: 文字列比較で検証できる単一の明確な答え
• Stable: 答えが時間とともに変わらない

4.4 Output Format

この構造で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>

---

Reference Files

📚 Documentation Library

開発中に必要に応じてこれらのリソースをロード:

Core MCP Documentation (Load First)

• MCP Protocol: https://modelcontextprotocol.io/sitemap.xml のサイトマップから始めて、次に .md サフィックス付きで特定ページを取得
• 📋 MCP Best Practices - 以下を含むユニバーサルMCPガイドライン:
  • Server and tool naming conventions
  • Response format guidelines (JSON vs Markdown)
  • Pagination best practices
  • Transport selection (streamable HTTP vs stdio)
  • Security and error handling standards

SDK Documentation (Load During Phase 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 からフェッチ

Language-Specific Implementation Guides (Load During Phase 2)

• 🐍 Python Implementation Guide - 以下を含む完全なPython/FastMCPガイド:

  • Server initialization patterns
  • Pydantic model examples
  • Tool registration with @mcp.tool
  • Complete working examples
  • Quality checklist

• ⚡ TypeScript Implementation Guide - 以下を含む完全なTypeScriptガイド:

  • Project structure
  • Zod schema patterns
  • Tool registration with server.registerTool
  • Complete working examples
  • Quality checklist

Evaluation Guide (Load During Phase 4)

• ✅ Evaluation Guide - 以下を含む完全な評価作成ガイド:
  • Question creation guidelines
  • Answer verification strategies
  • XML format specifications
  • Example questions and answers
  • Running an evaluation with the provided scripts

When to Use

このスキルは、上記の概要で説明されているワークフローまたはアクションを実行するために適用可能です。

Limitations

• このスキルは、タスクが上記で説明されたスコープと明確に一致する場合にのみ使用してください。
• 出力を環境固有の検証、テスト、またはエキスパートレビューの代替として扱わないでください。
• 必要な入力、権限、安全境界、または成功基準が欠けている場合は、停止して説明を求めてください。