mcpField
M
mcp-builder

mcp-builder

github.com/zrt-ai-lab開発29665 回インストール14 週間前に更新
リポジトリ

mcp-builder について

mcp-builder は、LLM 向けの MCP サーバーを開発するためのガイドスキルです。調査、設計、実装、レビュー、評価を扱い、エージェントのワークフローに沿ったツール設計を重視します。

主な機能

  1. 01プロトコルとサービス API の調査
  2. 02ツールと入出力の計画
  3. 03ツール、検証、エラー処理の実装
  4. 04コードレビューとビルドテスト
  5. 05評価用質問の設計と検証

活用シーン

  1. 01外部 API 向け MCP サーバーの計画
  2. 02エージェントのワークフローに沿ったツール設計
  3. 03サーバー実装とテストのレビュー
  4. 04現実的なタスクでツールを評価

MCP 対応

LLM がツールを介して外部サービスや API にアクセスできる MCP サーバーの開発をガイドします。プロトコル、SDK、ツール設計、評価を扱います。

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/zrt-ai-lab/opencode-skills --skill mcp-builder

インストール後、Claude Code で/mcp-builderを入力して読み込まれたか確認します。

詳細

MCP サーバー開発ガイド

概要

LLM が外部サービスと効果的にやり取りできる、高品質な MCP（Model Context Protocol）サーバーを作成するには、このスキルを使用します。MCP サーバーは、LLM が外部サービスや API にアクセスできるようにするツールを提供します。MCP サーバーの品質は、提供するツールを使用して LLM が現実世界のタスクをどれだけうまく達成できるかで測られます。

プロセス

大まかなワークフロー

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

フェーズ 1：詳細な調査と計画
1.1 エージェント中心の設計原則を理解する

実装に取りかかる前に、以下の原則を確認し、AI エージェント向けのツールの設計方法を理解してください。

API エンドポイントだけでなく、ワークフローを構築する：

  • 既存の API エンドポイントを単にラップするのではなく、よく考えられた、影響の大きいワークフローツールを構築します
  • 関連する操作をまとめます（例：空き状況の確認とイベントの作成を両方行う schedule_event）
  • 個々の API 呼び出しだけでなく、タスク全体を完了できるツールに焦点を当てます
  • エージェントが実際にどのようなワークフローを達成する必要があるかを検討します

限られたコンテキストに最適化する：

  • エージェントが利用できるコンテキストウィンドウには制約があるため、すべてのトークンを有効に使います
  • 網羅的なデータの羅列ではなく、重要な情報を返します
  • 「簡潔」または「詳細」の応答形式を選べるようにします
  • 技術的なコードより、人が読みやすい識別子（ID より名前）をデフォルトにします
  • エージェントのコンテキスト予算を限りあるリソースとして考慮します

実行可能なエラーメッセージを設計する：

  • エラーメッセージは、適切な使用方法をエージェントに示す必要があります
  • 「結果を減らすには、filter='active_only' を使ってみてください」のように、具体的な次の手順を提案します
  • エラーは単に問題を診断するだけでなく、学びにつながるものにします
  • 明確なフィードバックを通じて、エージェントが適切なツールの使用方法を学べるようにします

自然なタスクの分割に従う：

  • ツール名は、人がタスクについて考える方法を反映する必要があります
  • 関連するツールを一貫したプレフィックスでグループ化し、見つけやすくします
  • API の構造だけでなく、自然なワークフローを中心にツールを設計します

評価主導型の開発を行う：

  • 現実的な評価シナリオを早い段階で作成します
  • エージェントからのフィードバックに基づいてツールを改善します
  • すばやくプロトタイプを作成し、実際のエージェントのパフォーマンスに基づいて反復します
1.2 MCP プロトコルのドキュメントを確認する

最新の MCP プロトコルのドキュメントを取得します：

WebFetch を使用して、https://modelcontextprotocol.io/llms-full.txt を読み込みます。

この包括的なドキュメントには、MCP の仕様とガイドラインがすべて記載されています。

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

以下のリファレンスファイルを読み込み、確認します：

Python で実装する場合は、以下も読み込みます：

  • Python SDK のドキュメント：WebFetch を使用して https://raw.githubusercontent.com/modelcontextprotocol/python-sdk/main/README.md を読み込みます
  • Python 実装ガイド - Python 固有のベストプラクティスと例

Node/TypeScript で実装する場合は、以下も読み込みます：

  • TypeScript SDK のドキュメント：WebFetch を使用して https://raw.githubusercontent.com/modelcontextprotocol/typescript-sdk/main/README.md を読み込みます
  • TypeScript 実装ガイド - Node/TypeScript 固有のベストプラクティスと例
1.4 API のドキュメントを徹底的に確認する

サービスを統合するには、利用可能なすべての API ドキュメントに目を通します。

  • 公式 API リファレンスドキュメント
  • 認証および認可の要件
  • レート制限とページネーションのパターン
  • エラー応答とステータスコード
  • 利用可能なエンドポイントとそのパラメーター
  • データモデルとスキーマ

包括的な情報を集めるには、必要に応じてウェブ検索と WebFetch ツールを使用します。

1.5 包括的な実装計画を作成する

調査結果に基づき、以下を含む詳細な計画を作成します。

ツールの選定：

  • 実装する価値が最も高いエンドポイント／操作を一覧にします
  • 最も一般的で重要なユースケースを実現するツールを優先します
  • 複雑なワークフローを実現するために、連携して動作するツールを検討します

共通ユーティリティとヘルパー：

  • 共通する API リクエストのパターンを特定します
  • ページネーション用ヘルパーを計画します
  • フィルタリングと書式設定のユーティリティを設計します
  • エラー処理の方針を計画します

入力／出力の設計：

  • 入力検証モデルを定義します（Python では Pydantic、TypeScript では Zod）
  • 一貫性のあるレスポンス形式（例：JSON または Markdown）と、設定可能な詳細度（例：詳細または簡潔）を設計します
  • 大規模な利用（数千人のユーザー／リソース）に備えます
  • 文字数制限と切り捨ての方針（例：25,000 トークン）を実装します

エラー処理戦略：

  • 適切なフォールバック動作を計画します
  • 次のアクションを促す、明確で実行可能な、LLM に適した自然言語のエラーメッセージを設計します
  • レート制限やタイムアウトの状況を考慮します
  • 認証と認可のエラーに対応します
フェーズ 2：実装

包括的な計画ができたら、言語ごとのベストプラクティスに従って実装を開始します。

2.1 プロジェクト構成を設定する

Python の場合：

  • 単一の .py ファイルを作成するか、複雑な場合はモジュールに分割します（Python Guideを参照）
  • MCP Python SDK を使用してツールを登録します
  • 入力検証用の Pydantic モデルを定義します

Node/TypeScript の場合：

  • 適切なプロジェクト構成を作成します（TypeScript Guideを参照）
  • package.json と tsconfig.json を設定します
  • MCP TypeScript SDK を使用します
  • 入力検証用の Zod スキーマを定義します
2.2 まずコアインフラストラクチャを実装する

実装を始めるにあたり、ツールを実装する前に共通ユーティリティを作成します。

  • API リクエスト用ヘルパー関数
  • エラー処理ユーティリティ
  • レスポンス書式設定関数（JSON と Markdown）
  • ページネーション用ヘルパー
  • 認証／トークン管理
2.3 ツールを体系的に実装する

計画に含まれる各ツールについて、以下を行います。

入力スキーマを定義する：

  • 検証には Pydantic（Python）または Zod（TypeScript）を使用します
  • 適切な制約（最小／最大文字数、正規表現パターン、最小／最大値、範囲）を含めます
  • フィールドについて、明確で説明的な説明を記載します
  • フィールドの説明に多様な例を含めます

包括的な docstring／説明を記述する：

  • ツールの機能を一文で要約します
  • 目的と機能を詳しく説明します
  • 例を含め、パラメーターの型を明示します
  • 戻り値の型スキーマをすべて記載します
  • 使用例（使用する場合、使用しない場合）を記載します
  • 特定のエラーが発生した際の対処方法を示すエラー処理の説明を記載します

ツールのロジックを実装する：

  • 共通ユーティリティを使用してコードの重複を避けます
  • すべての I/O で async/await パターンに従います
  • 適切なエラー処理を実装します
  • 複数のレスポンス形式（JSON と Markdown）に対応します
  • ページネーションのパラメーターを尊重します
  • 文字数制限を確認し、適切に切り捨てます

ツールのアノテーションを追加する：

  • readOnlyHint: true（読み取り専用の操作の場合）
  • destructiveHint: false（破壊的でない操作の場合）
  • idempotentHint: true（呼び出しを繰り返しても効果が同じ場合）
  • openWorldHint: true（外部システムと連携する場合）
2.4 言語ごとのベストプラクティスに従う

Python の場合：Python Implementation Guide を読み込み、次の点を確認してください。

  • MCP Python SDK を使って適切にツールを登録する
  • model_config を使用した Pydantic v2 モデル
  • 全体を通じて型ヒントを使用する
  • すべての I/O 操作で Async/await を使用する
  • インポートを適切に整理する
  • モジュールレベルの定数（CHARACTER_LIMIT、API_BASE_URL）

Node/TypeScript の場合：TypeScript Implementation Guide を読み込み、次の点を確認してください。

  • server.registerTool を適切に使用する
  • .strict() を指定した Zod スキーマ
  • TypeScript の厳密モードを有効にする
  • any 型は使わず、適切な型を使用する
  • Promise<T> の戻り値の型を明示する
  • ビルドプロセスを設定する（npm run build）
フェーズ 3：レビューと改善

初期実装の後：

3.1 コード品質のレビュー

品質を確保するため、次の点についてコードをレビューしてください。

  • DRY 原則：ツール間でコードを重複させない
  • 合成可能性：共通ロジックを関数に切り出す
  • 一貫性：類似する操作では類似した形式を返す
  • エラー処理：すべての外部呼び出しでエラーを処理する
  • 型安全性：型を全面的に適用する（Python の型ヒント、TypeScript の型）
  • ドキュメント：すべてのツールに包括的な docstring／説明を付ける
3.2 テストとビルド

重要： MCP サーバーは、stdio/stdin または sse/http 経由のリクエストを待ち受ける長時間実行プロセスです。メインプロセスで直接実行すると（例：python server.py や node dist/index.js）、プロセスが無期限にハングします。

サーバーを安全にテストする方法：

  • 評価ハーネスを使用する（フェーズ 4 を参照）。推奨される方法です
  • tmux でサーバーを実行し、メインプロセスとは別に稼働させる
  • テスト時にタイムアウトを指定する：timeout 5s python server.py

Python の場合：

  • Python の構文を検証する：python -m py_compile your_server.py
  • ファイルを確認し、インポートが正しく動作することを確認する
  • 手動でテストする場合：tmux でサーバーを実行し、メインプロセスで評価ハーネスを使ってテストする
  • または、評価ハーネスを直接使用する（stdio トランスポート用のサーバー管理は評価ハーネスが行います）

Node/TypeScript の場合：

  • npm run build を実行し、エラーなく完了することを確認する
  • dist/index.js が作成されたことを確認する
  • 手動でテストする場合：tmux でサーバーを実行し、メインプロセスで評価ハーネスを使ってテストする
  • または、評価ハーネスを直接使用する（stdio トランスポート用のサーバー管理は評価ハーネスが行います）
3.3 品質チェックリストを使用する

実装の品質を確認するには、言語ごとのガイドから該当するチェックリストを読み込んでください。

  • Python：Python Guide の「Quality Checklist」を参照してください
  • Node/TypeScript：TypeScript Guide の「Quality Checklist」を参照してください
フェーズ 4：評価を作成する

MCP サーバーを実装したら、その有効性をテストするための包括的な評価を作成してください。

評価の完全なガイドラインについては、Evaluation Guide を読み込んでください。

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 のコアドキュメント（最初に読み込む）
  • MCP プロトコル：https://modelcontextprotocol.io/llms-full.txt から取得してください — MCP の完全な仕様
  • MCP のベストプラクティス — 以下を含む、MCP に関する一般的なガイドライン：
    • サーバーとツールの命名規則
    • 応答形式のガイドライン（JSON と Markdown の比較）
    • ページネーションのベストプラクティス
    • 文字数制限と切り詰めの方針
    • ツール開発のガイドライン
    • セキュリティとエラー処理の標準
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 形式の仕様
    • 質問と回答の例
    • 提供されたスクリプトを使った評価の実行方法

コメント

Markdown 対応