mcpField
M
mcp-builder

mcp-builder

github.com/partme-ai開発71871 回インストール4 週間前に更新
リポジトリ

mcp-builder について

mcp-builderは、MCPサーバー開発者向けのガイドスキルです。調査から実装、テスト、評価までを扱い、TypeScriptとPythonの資料も含みます。

主な機能

  1. 01MCP仕様とフレームワークの調査
  2. 02API範囲とツールの計画
  3. 03ツール実装とエラー処理
  4. 04ビルド、テスト、品質確認
  5. 05検証可能な評価質問の作成

活用シーン

  1. 01外部サービス向けMCPインターフェースの計画
  2. 02ページネーションと構造化出力を備えたツールの実装
  3. 03MCP Inspectorによるサーバーの検査
  4. 04サーバー向け読み取り専用評価質問の作成

MCP 対応

MCPサーバーの開発をガイドし、ツール、リソース、プロンプト、トランスポート、SDKの利用からテストと評価までを扱います。

インストール

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

$npx skills add https://github.com/partme-ai/full-stack-skills --skill mcp-builder

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

同梱ファイル

SKILL.md と一緒にインストールされる参考資料やスクリプト。

LICENSE.txt
__init__.py
reference/
evaluation.md
mcp_best_practices.md
node_mcp_server.md
python_mcp_server.md
scripts/
__init__.py
connections.py
evaluation.py
example_evaluation.xml
requirements.txt

詳細

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 のサポートと、多くの実行環境（例：MCPB）での優れた互換性を備えています。また、AI モデルは TypeScript コードの生成が得意です。広く使われていること、静的型付け、優れたリンティングツールも利点です）
  • トランスポート：リモートサーバーには、ステートレス JSON を使用するストリーミング可能な HTTP を使用します（ステートフルなセッションやストリーミングレスポンスに比べ、スケーリングと保守が容易です）。ローカルサーバーには stdio を使用します。

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

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 プロジェクト構成を設定する

プロジェクトの設定については、言語別ガイドを参照してください。

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. コンテンツの探索：READ-ONLY 操作を使用して、利用可能なデータを調べます
  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/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 形式の仕様
    • 質問と回答の例
    • 提供されたスクリプトを使用した評価の実行

コメント

Markdown 対応