mcp-builder（MCP サーバーの開発ガイド）

MCP（Model Context Protocol）サーバーを作るためのガイドです。description では、外部の API やサービスをつなぐ MCP サーバーを Python（FastMCP）または Node/TypeScript（MCP SDK）で作るときに使うとされています。SKILL.md は冒頭で、MCP サーバーの良し悪しは「LLM が実際の作業をどれだけうまくこなせるようになるか」で決まる、と位置づけています。

全体は「調査と計画」「実装」「見直しとテスト」「評価づくり」の4段階です。推奨構成は TypeScript で、リモートなら Streamable HTTP（状態を持たない JSON）、ローカルなら stdio。TypeScript SDK は新しい v2（@modelcontextprotocol/server）を新規開発に使い、既存の v1（@modelcontextprotocol/sdk）プロジェクトにはそのまま v1 を使う、と書き分けています。

言語ごとの詳しい実装ガイドや、MCP サーバーのベストプラクティス、評価の作り方は reference/ フォルダに分けられており、必要な段階で読み込む構成です。評価を実際に回すための Python スクリプトも付いています。

第1段階：調査と計画

最新の MCP 設計の考え方として、次の点が挙げられています。

• API を広く網羅するか、作業単位のツールにするか：両方のバランスを取る。迷ったら網羅を優先する
• ツール名：github_create_issue のように一貫した接頭辞と動詞で、見つけやすくする
• 文脈の節約：説明は簡潔にし、結果を絞り込んだりページ分けしたりできるようにする
• エラーメッセージ：次に何をすればよいかを具体的に示す

続いて、MCP の仕様はサイトマップから必要なページを探し、.md を付けて Markdown で読むこと、SDK の README を WebFetch で読み込むことを指示しています。TypeScript SDK については、v2 と v1 のどちらを使うかを最初に決め、混ぜないこと、既存の v1 プロジェクトでは v2 が現行の安定版で v1 は不具合とセキュリティの修正のみであることを一度だけ伝え、移行用の codemod コマンドを案内したうえで、頼まれない限り v1 のまま進めること、が書かれています。最後に対象 API の認証やデータ構造を調べ、実装するエンドポイントを洗い出します。

第2段階：実装

• 言語別ガイドに沿ってプロジェクト構成を作る
• 認証付きの API クライアント、エラー処理、JSON/Markdown の整形、ページ分けといった共通部分を先に作る
• 各ツールは、入力スキーマを Zod（TypeScript）か Pydantic（Python）で定義し、制約と説明と例を付ける。可能なら outputSchema と構造化された結果も返す
• I/O は async/await、エラーは対処法が分かる文面に
• ツールの性質を示すヒント（読み取り専用か、破壊的か、何度呼んでも同じ結果か、外部世界とやり取りするか）を付ける

第3段階：見直しとテスト

重複のなさ、エラー処理の一貫性、型の網羅、ツール説明の明確さを見直します。TypeScript は npm run build でビルドを確かめ、v2 ならガイドにある自己チェック用スクリプトを実行します。Python は python -m py_compile で構文を確かめます。どちらも MCP Inspector（npx @modelcontextprotocol/inspector）で動作を確認します。

第4段階：評価をつくる

完成したサーバーを LLM が使いこなせるかを確かめるため、質問と答えの組を10個作ります。ツールの一覧を確認し、読み取り専用の操作でデータを調べ、複雑で現実的な質問を作り、自分で解いて答えを確かめる、という流れです。各質問には、他の質問に依存しない、読み取り操作だけで解ける、複数回のツール呼び出しが要る、現実的、文字列比較で答え合わせできる、時間が経っても答えが変わらない、という条件が付きます。出力は <evaluation> の中に <qa_pair> を並べた XML ファイルです。

付属の参考資料

• reference/mcp_best_practices.md … サーバー名・ツール名の付け方、JSON と Markdown の使い分け、ページ分け、Streamable HTTP と stdio の選び方、認証・入力検証・DNS リバインディング対策などのセキュリティ、ツールのヒント、エラー処理、テストとドキュメントの要件
• reference/node_mcp_server_v2.md … TypeScript SDK v2 のガイド（プロジェクト構成、Zod 4 のスキーマ、stdio と Streamable HTTP を両方出す例、Bearer 認証、自己チェック用スクリプト、v1 からの対応表など）
• reference/node_mcp_server.md … 既存の v1 プロジェクト向けの同等のガイド
• reference/python_mcp_server.md … Python（FastMCP）のガイド。Pydantic モデル、@mcp.tool によるツール登録、品質チェックリストなど
• reference/evaluation.md … 質問と答えの作り方、良い例と悪い例、評価の実行方法

付属スクリプト

• scripts/evaluation.py … 評価用 XML の各質問を Claude に解かせ、MCP サーバーのツールを使った手順の要約やツールへの意見も含めて結果をまとめる。接続方法は stdio・SSE・HTTP から選べ、使うモデルやサーバーの起動コマンド、URL、ヘッダーなどを引数で指定する
• scripts/connections.py … 上記で使う、stdio・SSE・HTTP それぞれの MCP 接続クラス
• scripts/requirements.txt … anthropic と mcp パッケージ
• scripts/example_evaluation.xml … 評価ファイルの例

Claude Code（プラグインマーケットプレイスから）

リポジトリの README によると、このリポジトリ自体を Claude Code のプラグインマーケットプレイスとして登録できます。

/plugin marketplace add anthropics/skills
/plugin install example-skills@anthropic-agent-skills

/plugin の画面から「Browse and install plugins」→「anthropic-agent-skills」→「example-skills」→「Install now」と選んでも入ります。example-skills プラグインには、このスキルを含む複数のスキルがまとめて入っています。

評価スクリプトを使う場合は、scripts/requirements.txt のパッケージ（anthropic、mcp）を Python 環境に入れておきます。

Claude Code（フォルダを置く）

公式ドキュメントでは、スキルは ~/.claude/skills/<スキル名>/SKILL.md（自分の全プロジェクト）か .claude/skills/<スキル名>/SKILL.md（そのプロジェクトだけ）に置けば使えるとされています。リポジトリのフォルダを付属ファイルごとコピーします。入れたあとは、依頼内容が description に合えば自動で読み込まれるほか、/スキル名 で直接呼び出すこともできます（プラグイン経由のときは /プラグイン名:スキル名 の形）。

Claude（アプリ）と Claude API

README には、このリポジトリのサンプルスキルは Claude.ai の有料プランですでに使える状態になっていると書かれています。自作スキルのアップロード方法はヘルプ記事「Using skills in Claude」に、API での使い方は Skills API のクイックスタートに案内されています。

• 評価スクリプト（evaluation.py）は Anthropic の Python SDK で Claude API を呼ぶため、API キーと API の利用料金が必要です。
• evaluation.py の既定のモデルは claude-3-7-sonnet-20250219 になっています。古いモデル ID なので、実行するときは -m で現在使えるモデルを指定する必要がある可能性があります。
• SDK のドキュメントや MCP の仕様は、実行時に Web から読み込む前提で書かれています。ネットに接続できない環境では、その部分を手元の資料で補う必要があります。
• TypeScript SDK は v1 と v2 で import 先が違い、混ぜて使えないと明記されています。
• ライセンスはフォルダ内の LICENSE.txt で Apache License 2.0（Copyright 2026 Anthropic, PBC.）。