mcp-builder

MCP サーバー開発ガイド

概要

LLM が適切に設計されたツールを通じて外部サービスとやり取りできるようにする MCP（Model Context Protocol）サーバーを作成します。MCP サーバーの品質は、LLM が実際のタスクをどれだけうまく遂行できるようにするかで測られます。

---

プロセス

🚀 大まかなワークフロー

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

フェーズ 1：詳細な調査と計画

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

API カバレッジとワークフローツール： 幅広い API エンドポイントのカバレッジと、特定のワークフローに特化したツールのバランスを取ります。ワークフローツールは特定のタスクに便利ですが、幅広いカバレッジがあれば、エージェントは操作を柔軟に組み合わせられます。パフォーマンスはクライアントによって異なります。基本的なツールを組み合わせるコード実行が役立つクライアントもあれば、より高レベルのワークフローが適しているクライアントもあります。判断に迷う場合は、幅広い API カバレッジを優先してください。

ツールの命名と見つけやすさ： 明確で説明的なツール名を付けると、エージェントは適切なツールをすばやく見つけられます。一貫性のあるプレフィックス（例：github_create_issue、github_list_repos）を使い、アクションが分かる名前にします。

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

実行可能なエラーメッセージ： エラーメッセージでは、具体的な提案と次のステップを示し、エージェントが解決策を見つけられるようにしてください。

1.2 MCP プロトコルのドキュメントを確認する

MCP 仕様を参照する：

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

次に、特定のページに .md サフィックスを付けて取得し、Markdown 形式で確認します（例：https://modelcontextprotocol.io/specification/draft.md）。

確認すべき主なページ：

• 仕様の概要とアーキテクチャ
• トランスポート方式（ストリーミング可能な HTTP、stdio）
• ツール、リソース、プロンプトの定義

1.3 フレームワークのドキュメントを確認する

推奨スタック：

• 言語：TypeScript（高品質な SDK サポートがあり、多くの実行環境で優れた互換性があります。AI モデルは TypeScript コードの生成を得意としており、幅広い利用、静的型付け、優れたリンティングツールのメリットを活用できます）
• トランスポート：リモートサーバーには、ステートレスな JSON を使用するストリーミング可能な HTTP を使います（ステートフルなセッションやストリーミングレスポンスと比べて、スケーリングと保守が容易です）。ローカルサーバーには stdio を使います。
• 認証：リモートサーバーでは、OAuth 2.1（MCP 仕様の標準）または Authorization ヘッダーを介した API キーを使用します。標準的な OAuth フローについては、MCP 仕様の authorization.md を参照してください。

フレームワークのドキュメントを読み込む：

• 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>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>

</evaluation>

---

セキュリティのベストプラクティス

MCP サーバーはインターネットに公開され、機密性の高い操作を処理する可能性があります。次のガイドラインに従ってください。

認証と認可

• リモートサーバー：OAuth 2.1 または API キー認証を実装します
• すべての入力を検証する：クライアントから提供されたデータを決して信頼せず、スキーマと照合して検証します
• シークレット：API キーをハードコードせず、環境変数を使用します
• スコープの制限：クライアントに必要なツールのみを公開し、最小権限の原則を適用します

入力検証

// Use Zod with strict schemas
const DeleteUserSchema = z.object({
  userId: z.string().uuid(),  // UUID format enforced
  reason: z.enum(["spam", "policy_violation", "user_request"]),  // Enum limits
});

// Never allow arbitrary code execution
const QuerySchema = z.object({
  table: z.enum(["users", "orders", "products"]),  // No arbitrary tables
  id: z.number().int().positive(),
});

レート制限と不正使用の防止

// Add rate limiting to destructive operations
const rateLimiter = new Map<string, number[]>();

function checkRateLimit(clientId: string, limit: number, windowMs: number): boolean {
  const now = Date.now();
  const calls = rateLimiter.get(clientId) ?? [];
  const windowCalls = calls.filter(t => now - t < windowMs);
  if (windowCalls.length >= limit) return false;
  rateLimiter.set(clientId, [...windowCalls, now]);
  return true;
}

監査ログ

// Log all tool calls for sensitive operations
server.registerTool("delete_record", {
  // ...
  handler: async ({ id }) => {
    console.error(JSON.stringify({  // stderr for logging
      event: "tool_call",
      tool: "delete_record",
      params: { id },
      timestamp: new Date().toISOString(),
    }));
    // ... implementation
  }
});

---

よくある落とし穴

MCP サーバーの開発では、いくつかの予測可能な失敗が発生します。これらの注意点は、実装中に見つかった実際の問題を示しています。

1. 生成後にサーバーが起動しない

症状：

• npm start が終了コード 1 で失敗する
• プロセスは起動するが、すぐにクラッシュする
• ポートがすでに使用中というエラーが発生する

主な原因：

• 依存関係の不足（SDK のバージョン不一致、不完全な npm install）
• 既存のプロセスとのポート競合
• 環境変数の設定ミス
• .npmrc または tsconfig.json の設定が無効

デバッグ用コマンド：

# Verify dependencies are installed
npm list @modelcontextprotocol/sdk

# Check if port is in use
lsof -i :3000  # Replace 3000 with your port
netstat -an | grep LISTEN | grep 3000

# Clear cache and reinstall
rm -rf node_modules package-lock.json
npm install

# Run with verbose output to see initialization errors
npm start -- --debug
NODE_DEBUG=* npm start  # Maximum verbosity for Node.js internals

# For TypeScript, verify compilation first
npm run build
npx tsc --noEmit  # Check for type errors without building

# Check for missing env variables
env | grep MCP  # See what MCP-related vars are set

予防策：

• プロジェクトの生成後は、必ず npm install を実行します
• 設定ファイルではポート番号を明示的に指定します
• 必要な環境変数を .env.example に記載します
• 起動前にコンパイルをテストします：npm run build

---

2. ツールのスキーマが検証に失敗する

症状：

• MCP Inspector に「Invalid schema」エラーが表示される
• クライアントがツールを 422 エラーで拒否する
• ある SDK バージョンではツールが動作するが、別のバージョンでは動作しない

主な原因：

• Zod/Pydantic の定義で JSON Schema 違反がある
• スキーマオブジェクトに必須フィールドがない
• type の注釈が正しくない
• スキーマ参照が循環している
• 制約が無効（数値型ではないのにパターンの正規表現や最小値／最大値を指定している）

デバッグ用コマンド：

# Validate schema syntax
npx @modelcontextprotocol/inspector  # GUI debugger, shows schema errors clearly

# Test schema compilation directly (TypeScript)
cat > test-schema.ts << 'EOF'
import { z } from 'zod';
const schema = z.object({
  // your schema here
});
console.log(JSON.stringify(schema.safeParse({}), null, 2));
EOF
npx ts-node test-schema.ts

# For Python, test Pydantic directly
python3 << 'EOF'
from pydantic import BaseModel
class MyTool(BaseModel):
    # your fields here
    pass
print(MyTool.model_json_schema())
EOF

# Print actual schema being sent to client
# In your server code, log before registration:
console.log(JSON.stringify(toolSchema, null, 2));

# Test with invalid inputs to see error messages
# In MCP Inspector, try calling tool with:
# - Missing required fields
# - Wrong types (string instead of number)
# - Values outside constraints

予防策：

• strict モードを有効にして TypeScript を使用します（tsconfig.json の strict: true）
• スキーマを変更するたびにテストします：npm run build
• 開発中にスキーマの JSON をコンソールに出力します
• MCP Inspector のスキーマ検証を使用します（これを正とします）
• スキーマはシンプルに保ち、複雑なツールは小さなツールに分割します
• フィールドの説明に制約（最小値／最大値、正規表現パターン）を記載します

---

3. 認証フローが失敗する

症状：

• 「Unauthorized」または「403 Forbidden」エラーが発生する
• API キーがリクエストに含まれない
• OAuth トークンの期限が切れている、または無効である
• 認証情報はローカルでは機能するが、デプロイ後は失敗する

主な原因：

• デプロイ環境で環境変数が設定されていない
• 認証情報の期限が切れている、または取り消されている
• API 認証のヘッダー形式が間違っている（Bearer と Basic の違い）
• OAuth のリダイレクト URI が登録内容と一致しない
• OAuth リクエストにスコープが不足している
• 環境変数を使用せず、認証情報を誤ってハードコードしている

デバッグ用コマンド：

# Verify environment variables are accessible
node -e "const k = process.env.API_KEY; console.log('Key set:', !!k, '| Length:', k?.length, '| Prefix:', k?.substring(0, 4) + '***')"

# Check if file-based credentials exist
test -f ~/.aws/credentials && echo "AWS creds found" || echo "AWS creds missing"
test -f ~/.config/github-cli/hosts.yml && echo "GitHub token found" || echo "GitHub token missing"

# Validate API key format before use
node -e "const key = process.env.API_KEY; console.log('Key length:', key?.length); console.log('Key prefix:', key?.substring(0, 10));"

# Test API authentication directly
curl -H "Authorization: Bearer $API_KEY" https://api.example.com/v1/test
curl -H "X-API-Key: $API_KEY" https://api.example.com/v1/test  # Alternative header

# Check OAuth token expiration
node -e "const payload = JSON.parse(Buffer.from(process.env.OAUTH_TOKEN.split('.')[1], 'base64url').toString()); console.log('Expires:', new Date(payload.exp * 1000));"

# For deployed servers, check what environment was actually loaded
# Add this to your server initialization:
console.error('Auth check:', {
  hasApiKey: !!process.env.API_KEY,
  keyLength: process.env.API_KEY?.length,
  keyPrefix: process.env.API_KEY?.substring(0, 10) + '***'
});

予防策：

• 認証情報をハードコードせず、必ず環境変数を使用します
• 必要な認証情報すべてについて、プレースホルダー値を記載した .env.example を作成します
• どの認証情報が任意で、どれが必須かを記載します
• 開発時は dotenv ライブラリを使用して .env ファイルを読み込みます
• 起動時に認証情報の状態をログに記録します（実際の値は公開しません）
• サーバー起動時に認証情報を検証し、問題があればすぐに失敗するようにします
• デプロイ済みサーバーでは、プラットフォーム標準のシークレット管理機能（GitHub Secrets、Fly.io Secrets など）を使用します
• ツールのテスト前に認証を個別にテストします：まず認証情報を指定して curl を実行します

---

4. クライアント接続がタイムアウトする

症状：

• 30 秒後に「Connection timeout」エラーが発生する
• クライアントがサーバーを見つけられない
• Stdio トランスポートはローカルでは動作するが、MCP Inspector では動作しない
• Streamable HTTP サーバーがリクエストをまったく受信しない

主な原因：

• クライアントが接続する前にサーバープロセスがクラッシュする
• クライアント設定のポートまたはホスト名が間違っている
• ファイアウォールが接続をブロックしている
• 初期化中にサーバースレッドがデッドロックする
• Stdio トランスポートの設定が正しくない（stdin/stdout が適切に接続されていない）
• サーバーの初期化に時間がかかりすぎる（デフォルトのタイムアウトを超過する）

デバッグ用コマンド：

# For stdio transport, test directly
npx @modelcontextprotocol/inspector stdio node dist/index.js

# For HTTP transport, verify server is listening
lsof -i -n -P | grep LISTEN  # See all listening ports
curl http://localhost:3000/ -v  # Try to reach server directly

# Monitor server startup time
time npm start  # Measure total startup duration

# Check if process is using all CPU (deadlock indicator)
top -n1 | grep node  # See if CPU% is stuck at 100

# For stdio issues, run server directly to see output
node dist/index.js  # If it hangs here, initialization is blocking
# Try interrupt (Ctrl+C) to see if it's truly stuck

# Check for port binding issues
ss -tlnp | grep 3000  # Linux
netstat -tlnp | grep 3000  # Linux alternative
lsof -i TCP:3000  # macOS/BSD

# Test server connectivity with timeout
timeout 5 curl -v http://localhost:3000/ || echo "Connection failed or timeout"

予防策：

• 起動ログを追加します：サーバーの起動時と、主要な初期化ステップごとにログを記録します
• ヘルスチェックエンドポイントを実装します：GET /health が 200 OK を返すようにします
• テストには MCP Inspector を使用します（接続の問題をすばやく検出できます）
• サーバーの初期化は軽量に保ち、負荷の高い処理は最初のリクエストまで延期します
• 外部 API 呼び出しには明示的なタイムアウトを設定します（無期限に待機させないでください）
• npx @modelcontextprotocol/inspector stdio <command> を使用して Stdio トランスポートをテストします
• HTTP トランスポートでは、/health を公開して個別にテストします
• 起動中のメモリ使用量を監視します（メモリリークは問題の兆候です）

---

系統的なデバッグワークフロー

MCP サーバーが動作しない場合：

1. まずログを確認する：ほとんどの失敗はログに記録されます。詳細な出力を有効にして実行します：

   NODE_DEBUG=* npm start 2>&1 | head -50
   

2. MCP Inspector を使用する：単独で起動し、サーバーを選択します：

   npx @modelcontextprotocol/inspector
   

   スキーマエラー、接続の問題、ツール実行の失敗が明確に表示されます。

3. 単独でテストする：クライアントでテストする前に、サーバーが単独で動作することを確認します：

   npm run build && node dist/index.js
   

4. 外部依存関係を確認する：API 認証情報、ネットワークアクセス、ファイアウォールを確認します：

   curl -v https://api.example.com/  # Does API respond?
   

5. 計測を追加する：行き詰まったら、何が起きているのかを把握するためにログを追加します：

   server.setRequestHandler(Tool, async (request) => {
     console.error('Tool called:', request.params.name);
     try {
       // implementation
       console.error('Tool succeeded');
     } catch (error) {
       console.error('Tool failed:', error);
       throw error;
     }
   });
   

---

参考ファイル

📚 ドキュメントライブラリ

開発中に必要に応じて、これらのリソースを読み込みます：

MCP のコアドキュメント（最初に読み込む）

• MCP プロトコル：https://modelcontextprotocol.io/sitemap.xml のサイトマップを確認し、その後 .md サフィックスを付けて特定のページを取得します
• 📋 MCP のベストプラクティス - 以下を含む、MCP に関する普遍的なガイドライン：
  • サーバーとツールの命名規則
  • 応答形式のガイドライン（JSON 対 Markdown）
  • ページネーションのベストプラクティス
  • トランスポートの選択（ストリーム可能な HTTP 対 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 形式の仕様
  • 質問と回答の例
  • 提供されたスクリプトを使った評価の実行