mcp-server-builder

MCP サーバービルダー

ティア： 強力 カテゴリー： エンジニアリング／AI インテグレーション メンテナー： Claude Skills Team

概要

API コントラクトから、本番環境ですぐに使える MCP（Model Context Protocol）サーバーを設計し、リリースします。ツール定義のベストプラクティス、リソースプロバイダー、プロンプトテンプレート、OpenAPI から MCP への変換、TypeScript と Python によるサーバー実装、トランスポートの選択（stdio、SSE、StreamableHTTP）、認証パターン、テスト戦略、デプロイ設定を扱います。スキーマの品質とツールの発見しやすさを、第一級の関心事として扱います。

キーワード

MCP、Model Context Protocol、MCP サーバー、ツール定義、リソースプロバイダー、プロンプトテンプレート、stdio トランスポート、SSE トランスポート、OpenAPI から MCP への変換、AI ツールサーバー、Claude ツール

主な機能

• ツール設計とスキーマ品質 — 動詞と名詞を組み合わせた命名、説明文の設計、型付き入力スキーマ、LLM に適した出力形式
• サーバー実装 — TypeScript（@modelcontextprotocol/sdk）と Python（mcp[cli]）によるサーバー、ツール／リソース／プロンプトの登録、構造化されたエラー処理、ログ記録、認証、レート制限のミドルウェア
• トランスポートとデプロイ — stdio（ローカル／CLI）、SSE（ウェブ）、StreamableHTTP（本番環境）、Docker によるコンテナ化、ヘルスチェック、グレースフルシャットダウン
• テストと検証 — スキーマ検証、MCP Inspector の結合テスト、コントラクトテスト／スナップショットテスト、リモートサーバーの負荷テスト

使用する場面

• 内部 REST API を Claude、Cursor、その他の MCP クライアントに公開する場合
• 壊れやすいブラウザー自動化を、型付きツールインターフェースに置き換える場合
• 複数のチームや AI アシスタントで共有する MCP サーバーを構築する場合
• OpenAPI 仕様を MCP ツールに自動変換する場合
• ドメイン固有のツールサーバー（データベース、監視、デプロイなど）を作成する場合

まず確認すること

サーバーを構築する前に、次の入力情報を確認してください。不明または曖昧な点があれば、推測せずに質問してください。

• ソースコントラクト — 公開する OpenAPI 仕様または API、あるいはツールをゼロから構築するかどうか（ツール定義と変換の基となる入力）
• 言語 — TypeScript（@modelcontextprotocol/sdk）または Python（mcp[cli]）（生成するサーバー実装を決定します）
• トランスポート — stdio（ローカル／CLI）、SSE（ウェブ）、または StreamableHTTP（本番環境）（トランスポート、認証、デプロイのパターンを決定します）

停止ルール：出力に最も大きく影響する 2～3 項目だけを質問してください。ユーザーが「ひとまずドラフトを作って」と言った場合は、そのまま進め、成果物の冒頭に前提条件を記載してください。

参考資料

タスクに合った参考資料を読み込みます。このファイルは簡潔に保ち、必要な詳細はその都度参照してください。

• references/tool-schema-design.md — 命名規則、説明文を作成するためのテンプレート、入力スキーマのベストプラクティスです。説明文の質が LLM によるツール選択を左右するため、ツールを定義する際は最初に読んでください。
• references/server-implementation.md — ツール、リソース、プロンプトを含む TypeScript および Python のサーバーコード一式と、OpenAPI から MCP への変換ルールおよびスクリプトです。サーバーを実装する際に読んでください。
• references/transport-and-deployment.md — クライアント設定（stdio とリモート用の claude_desktop_config.json）とツールのバージョニング戦略です。クライアントを接続する際やリリースを計画する際に読んでください。
• references/testing-and-troubleshooting.md — スキーマ検証関数、MCP Inspector のコマンド、よくある落とし穴、ベストプラクティス、トラブルシューティング表、成功基準です。検証、本番環境向けの強化、障害の診断を行う際に読んでください。
• references/streaming-batch-and-computer-use.md — 長時間実行ツールの進捗／ストリーミングとキャンセル、コンピューター操作／ブラウザー／デスクトップ操作のラップ（粒度、状態の返却、安全対策）、バッチ処理に適したツール設計（配列、冪等性、一部失敗の結果、ページネーション）について説明しています。ツールの実行に時間がかかる場合、操作中の画面を制御する場合、または多数の項目を処理する場合に読んでください。

一般的なパターン

• 長時間実行ツールのストリーミング — 呼び出しが通常数秒を超える場合（ビルド、クロール、自動化など）は、安定した相関ハンドルを使って頻度を抑えた進捗更新を送信し、明示的な終了シグナルで締めくくる、意味的にまとまったチャンクをストリーミングし、実際の処理を中断してセッションをクリーンアップすることでキャンセルに対応してください。最終応答だけで内容が完結している必要があります。references/streaming-batch-and-computer-use.md を参照してください。
• バッチ処理に適したツール — 操作を自然に繰り返せる場合は、項目ごとにチャットを何度も呼び出させるのではなく、上限付き配列を受け付けるようにしてください。操作を冪等にする（または冪等性キーを受け取る）とともに、項目ごとの成功／失敗結果を返し、エージェントが失敗した項目だけを再試行できるようにしてください。一覧表示／読み取りツールでは、上限を明記し、カーソルを使ってページネーションする必要があります。scripts/tool_schema_linter.py を実行すると、チャットを何度も必要とする単一項目ツールや、ページネーションの不足を検出できます。
• MCP によるコンピューター操作 — 生のピクセル操作ではなく、意図レベルのアクション（navigate、click、read_page）を公開し、現在観測可能な状態を返してください（まずテキストを返し、レイアウトが重要な場合に限りスクリーンショットを返します）。破壊的または取り消し不能な操作は、秘密情報をマスキングした許可リストに適用される confirm／dry_run パラメーターで制御してください。自動化エンジン自体については、computer-use-automation スキルを参照してください。

対象範囲と制限事項

このスキルの対象：

• MCP サーバー向けのツールスキーマ、リソースプロバイダー、プロンプトテンプレートの設計
• TypeScript（@modelcontextprotocol/sdk）および Python（mcp[cli]）でのサーバー実装
• トランスポートの選択とクライアント設定（stdio、SSE、StreamableHTTP）
• OpenAPI から MCP への変換パターンとテスト戦略

このスキルの対象外：

• MCP クライアントやカスタム LLM オーケストレーションレイヤーの構築 — engineering/agent-workflow-designer を参照してください
• MCP ツールを利用するマルチエージェントシステムの設計 — engineering/agent-designer を参照してください
• API 自体の設計（REST の規約、エンドポイントの命名、バージョニング） — engineering/api-design-reviewer を参照してください
• MCP サーバーをデプロイするためのインフラストラクチャのプロビジョニング、コンテナーオーケストレーション、CI/CD パイプライン — engineering/ci-cd-pipeline-builder を参照してください

統合ポイント

スキル	統合	データフロー
engineering/api-design-reviewer	MCP ツールに変換する前に、基盤となる REST API をレビューします	OpenAPI 仕様 → API レビュー結果 → 改訂された仕様 → MCP への変換
engineering/api-test-suite-builder	MCP ツールがラップする HTTP エンドポイントの統合テストを生成します	MCP ツール定義 → エンドポイントのマッピング → テストスイートの生成
engineering/agent-designer	このスキルが生成する MCP ツールを利用するエージェントを設計します	MCP ツールスキーマ → エージェントのツール一覧 → エージェントの動作設計
engineering/observability-designer	MCP サーバーのハンドラーに構造化ログ、トレース、メトリクスを追加します	MCP サーバーコード → 計装計画 → ログ／トレースのミドルウェア
engineering/ci-cd-pipeline-builder	MCP サーバーのリリース用のビルド、テスト、デプロイのパイプラインを自動化します	MCP サーバーのリポジトリ → パイプライン設定 → ステージング／本番環境への自動デプロイ
engineering/env-secrets-manager	MCP サーバーの設定で使用する API キー、データベース認証情報、トークンを管理します	MCP サーバーの環境変数 → シークレット監査 → 安全な注入パターン