mcp-builder

MCP サーバー開発ガイド

適切に設計されたツールを通じて、LLM が外部サービスを利用できるようにする MCP サーバーを作成します。

大まかなワークフロー

フェーズ 1：調査と計画

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

• API を網羅することと、特定のワークフローに特化したツールを用意することのバランスを取ります
• 一貫したプレフィックスを使い、明確で説明的なツール名を付けます（例：github_create_issue）
• 焦点を絞った、関連性の高いデータを返すツールを設計します
• 実行可能なエラーメッセージを提供します

MCP プロトコルを調べる：

• サイトマップから始めます：https://modelcontextprotocol.io/sitemap.xml
• 主要なページ：仕様、トランスポートの仕組み、ツールの定義

フェーズ 2：実装

推奨スタック：

• 言語：TypeScript（SDK のサポートが最も充実）
• トランスポート：リモートには Streamable HTTP、ローカルには stdio

プロジェクト構成：

my-mcp-server/
├── src/
│   ├── index.ts      # Server entry point
│   ├── tools/        # Tool implementations
│   └── utils/        # Shared utilities
├── package.json
└── tsconfig.json

ツール実装パターン：

server.registerTool({
  name: "github_create_issue",
  description: "Create a new GitHub issue",
  inputSchema: z.object({
    repo: z.string().describe("Repository name (owner/repo)"),
    title: z.string().describe("Issue title"),
    body: z.string().optional().describe("Issue body")
  }),
  outputSchema: z.object({
    id: z.number(),
    url: z.string()
  }),
  annotations: {
    readOnlyHint: false,
    destructiveHint: false,
    idempotentHint: false
  },
  handler: async (input) => {
    // Implementation
    return { id: 123, url: "https://..." };
  }
});

フェーズ 3：テスト

# TypeScript
npm run build
npx @modelcontextprotocol/inspector

# Python
python -m py_compile your_server.py

フェーズ 4：評価の作成

MCP サーバーをテストするため、複雑で現実的な質問を 10 個作成します。

<evaluation>
  <qa_pair>
    <question>Find all open issues labeled 'bug' in the repo</question>
    <answer>5</answer>
  </qa_pair>
</evaluation>

ツール設計のベストプラクティス

• スキーマには Zod（TS）または Pydantic（Python）を使用します
• フィールドの説明に制約と例を含めます
• 構造化データには outputSchema を定義します
• 該当する場合はページネーションをサポートします
• ツールアノテーション（readOnly、destructive、idempotent）を追加します