mcp-creator

MCP Creator — FastMCP v3

FastMCP v3（3.0.0rc2）で、本番環境に対応した MCP サーバーを構築します。このスキルでは、調査、雛形の作成、実装、テスト、デプロイを順を追って説明します。ファーストパーティの出力はすべて、このリポジトリの規約に従います。mcp/<name>/ ディレクトリ、fastmcp.json 設定、正確な uv ワークスペースメンバー、命令形の文体、ケバブケースの命名を使用します。mcp/servers/ は、マシンローカルのサードパーティ製 MCP インストール用に確保されています。このディレクトリは Git の追跡対象外です。

対象： FastMCP v3 rc2 — Provider/Transform アーキテクチャ、組み込みミドルウェア 14 種、OAuth 2.1、サーバー合成、コンポーネントのバージョン管理、構造化出力、バックグラウンドタスク、エリシテーション、サンプリング。

入力： $ARGUMENTS — MCP サーバーとしてラップするサービス、API、または機能。

---

振り分け

$ARGUMENTS を適切なモードに振り分けます。

$ARGUMENTS のパターン	モード	開始位置
サービス/API 名（例：「GitHub」、「Stripe」）	新規サーバー	フェーズ 1
既存のファーストパーティサーバーへのパス（例：mcp/myserver/）	拡張	フェーズ 3
OpenAPI 仕様の URL またはファイルパス	OpenAPI の変換	フェーズ 2（雛形作成）、続けて references/server-composition.md §6 を読み込む
変換する FastAPI アプリ	FastAPI の変換	フェーズ 2（雛形作成）、続けて references/server-composition.md §7 を読み込む
エラーメッセージ、または「debug」と説明	デバッグ	references/common-errors.md を読み込み、症状と照合する
「learn」または概念に関する質問	学習	関連するリファレンスファイルを読み込み、説明する
空	ギャラリー／ヘルプ概要	利用可能なモードと呼び出し例を表示する

---

最新のドキュメントを確認する

実装の前に、FastMCP v3 の最新ドキュメントを取得します。同梱のリファレンスは rc2 の内容を反映していますが、最新ドキュメントのほうが新しい場合があります。

1. Context7 — 「fastmcp」の resolve-library-id を実行し、続けてトピックの query-docs を実行します。
2. WebFetch — https://gofastmcp.com/llms-full.txt — LLM 向けに最適化された包括的なドキュメントです。
3. WebSearch のフォールバック — 特定のトピックについて site:gofastmcp.com <topic> を検索します。

最新ドキュメントと同梱のリファレンスが矛盾する場合は、最新ドキュメントを優先します。rc2 から安定版への移行で API の詳細が変わるため、必ず最初に最新ドキュメントを取得してください。

---

フェーズ 1：調査と計画

目標： 対象サービスを理解し、MCP サーバーのツール／リソース／プロンプトの一覧を設計します。

読み込み： references/tool-design.md（命名、説明、パラメーター設計、8 つのツールパターン）

1.1 対象を理解する

• 対象サービスのドキュメント、SDK、API リファレンスを読みます。
• ユーザーに必要な主要な操作（CRUD、検索、ステータス、設定）を特定します。
• 認証要件（API キー、OAuth、トークン）を確認します。
• 対象サービス用の既存 MCP サーバーがないか確認し、作業の重複を避けます。

1.2 アーキテクチャのチェックリスト

先に進む前に回答します。

• 認証が必要ですか？（API キー → 環境変数、OAuth → HTTP トランスポート、不要 → stdio）
• トランスポートは何ですか？（ローカル用 → stdio、リモート／複数クライアント用 → Streamable HTTP）
• バックグラウンドタスクは必要ですか？（長時間実行される操作 → task=True、fastmcp[tasks] が必要）
• OpenAPI 仕様はありますか？（→ OpenAPIProvider または FastMCP.from_openapi()）
• 複数のドメインがありますか？（→ mount() と名前空間を使ったサーバー合成）

1.3 ツール一覧を設計する

サーバーごとに 5～15 個のツールを計画します。各ツールについて、次の項目を定義します。

フィールド	要件
名前	snake_case の verb_noun 形式、最大 64 文字
説明	3～5 文で、対象（WHAT）、使用する場合（WHEN）、使用しない場合（WHEN NOT）、返される内容（WHAT it returns）を記述
パラメーター	各パラメーターに型、説明、Annotated[type, Field(...)] による制約を指定
アノテーション	readOnlyHint、destructiveHint、idempotentHint、openWorldHint
エラーケース	想定される失敗に対して発生させる ToolError メッセージ

1.4 リソースとプロンプトを設計する

• リソース：静的、または変更頻度の低いデータ（設定、スキーマ、ステータス）に使用します。URI でアドレス指定します。
• プロンプト：LLM の動作を導く、再利用可能なメッセージテンプレートに使用します。
• URI パターンとプロンプト設計については、references/fastmcp-v3-api.md §6-7 を参照してください。

1.5 アーキテクチャを計画する

構成戦略を決定します。

• 単一サーバー — ほとんどの場合に適しています。すべてのツールを持つ単一の FastMCP インスタンスを使用します。
• サーバーの合成 — 大規模な API に適しています。ドメインサーバーを mount() でマウントし、名前空間を設定します。
• プロバイダーベース — ツールを動的に登録します。FileSystemProvider またはカスタムの Provider を使用します。
• OpenAPI 変換 — OpenAPI 仕様からツールを自動生成します。OpenAPIProvider または FastMCP.from_openapi() を使用します。

パターンについては references/server-composition.md を参照してください。

1.6 成果物

次に進む前に、ツール／リソース／プロンプトの一覧表を作成します。

| Component | Type | Name | Description (brief) |
|-----------|------|------|---------------------|
| Tool | tool | search_issues | Search GitHub issues by query |
| Resource | resource | config://settings | Current server configuration |
| Prompt | prompt | summarize_pr | Summarize a pull request for review |

---

フェーズ 2：スキャフォールド

目標： プロジェクトディレクトリとテストを作成し、依存関係を設定します。

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

python scripts/scaffold_mcp.py <name> を実行してスキャフォールドを作成します。

mcp/<name>/
├── server.py          # FastMCP entry point
├── pyproject.toml     # uv project config
├── fastmcp.json       # FastMCP CLI config
└── tests/
    ├── conftest.py    # Client fixture, mock Context
    └── test_server.py # Automated test suite

スキャフォールドをカスタマイズします。

• server.py でサーバー名を設定します：mcp = FastMCP("name")。
• pyproject.toml でパッケージ名を設定します：name = "mcp-<name>"。
• pyproject.toml の説明を更新します。
• サービス固有の依存関係を pyproject.toml と fastmcp.json の両方に追加します。

2.2 テスト設定を追加する

pyproject.toml に追加します。

[tool.pytest.ini_options]
asyncio_mode = "auto"

[dependency-groups]
dev = ["pytest>=8", "pytest-asyncio>=0.25"]

tests/conftest.py を作成します。完全なテンプレートについては references/testing.md §4 を参照してください。

2.3 設定して検証する

• ルートの pyproject.toml に [tool.uv.workspace] members = ["mcp/<name>"] があることを確認します。
• cd mcp/<name> && uv sync を実行して依存関係をインストールします。
• 次のコマンドで検証します：uv run python -c "from server import mcp; print(mcp.name)"。

注：python scripts/check.py で検証されるのはこのスキルのみであり、MCP サーバーではありません。MCP サーバーの検証には、上記のインポートチェックを使用してください。

---

フェーズ 3：実装

目標： フェーズ 1 の一覧にあるすべてのツール、リソース、プロンプトを構築します。

読み込むもの： references/fastmcp-v3-api.md（API 全体）、references/tool-design.md（パターン）

3.1 サーバーをセットアップする

from fastmcp import FastMCP, Context

mcp = FastMCP(
    "server-name",
    instructions="Description of what this server provides and when to use it.",
)

共有リソース（HTTP クライアント、DB 接続）には、合成可能なライフスパンを追加します。

from fastmcp.server.lifespan import lifespan

@lifespan
async def http_lifespan(server):
    import httpx
    async with httpx.AsyncClient() as client:
        yield {"http": client}

mcp = FastMCP("server-name", lifespan=http_lifespan)
# Access in tools: ctx.lifespan_context["http"]

ライフスパンは | で結合します：mcp = FastMCP("name", lifespan=db_lifespan | cache_lifespan)

3.2 ツールを実装する

一覧の各ツールについて、次のパターンに従います。

from typing import Annotated
from pydantic import Field
from fastmcp import Context
from fastmcp.exceptions import ToolError

@mcp.tool(
    annotations={
        "readOnlyHint": True,
        "openWorldHint": True,
    },
)
async def search_items(
    query: Annotated[str, Field(description="Search term to find items.", min_length=1)],
    limit: Annotated[int, Field(description="Max results to return.", ge=1, le=100)] = 10,
    ctx: Context | None = None,
) -> dict:
    """Search for items matching a query.

    Use this tool when you need to find items by keyword. Returns a list of
    matching items with their IDs and titles. Use the limit parameter to
    control result count. Does not search archived items.

    Returns a dictionary with 'items' list and 'total' count.
    """
    if ctx:
        await ctx.info(f"Searching for: {query}")
    try:
        results = await do_search(query, limit)
        return {"items": results, "total": len(results)}
    except ServiceError as e:
        raise ToolError(f"Search failed: {e}")

すべてのツールに適用される主なルール：

• すべてのパラメーターに Annotated[type, Field(description=...)] を指定します。
• 詳細な docstring を記述します。内容：機能、使用するタイミング、使用しないタイミング、返す値。
• 想定されるエラーには ToolError を使用します（常にクライアントに表示されます）。
• すべてのツールに annotations 辞書を指定します。最低限 readOnlyHint が必要です。
• MCP ランタイムなしでもテストできるよう、ctx: Context | None = None を指定します。

同期、非同期＋Context、ステートフル、外部 API、データ処理、依存性注入、サンプリング、エリシテーションの 8 つの完全なツールパターンについては、references/tool-design.md §9 を参照してください。

3.3 リソースを実装する

import json

@mcp.resource("config://settings", mime_type="application/json")
async def get_settings() -> str:
    """Current server configuration."""
    return json.dumps(settings)

@mcp.resource("users://{user_id}/profile")
async def get_user_profile(user_id: str) -> str:
    """User profile by ID."""
    return json.dumps(await fetch_profile(user_id))

URI テンプレート、クエリパラメーター、ワイルドカード、クラスベースのリソースについては、references/fastmcp-v3-api.md §6 を参照してください。

3.4 プロンプトを実装する

from fastmcp.prompts import Message

@mcp.prompt
def summarize_pr(pr_number: int, detail_level: str = "brief") -> list[Message]:
    """Generate a prompt to summarize a pull request."""
    return [Message(
        role="user",
        content=f"Summarize PR #{pr_number} at {detail_level} detail level.",
    )]

3.5 合成（該当する場合）

大規模なサーバーでは、ドメインモジュールに分割して合成します。references/server-composition.md を参照してください。

from fastmcp import FastMCP
from .issues import issues_server
from .repos import repos_server

mcp = FastMCP("github")
mcp.mount(issues_server, namespace="issues")
mcp.mount(repos_server, namespace="repos")

3.6 認証（該当する場合）

認証を実装する際は、references/auth-and-security.md を読み込みます。

• stdio トランスポート： MCP レベルの認証はありません。バックエンド API キーには環境変数を使用します。
• HTTP トランスポート： JWTVerifier、GitHubProvider、または RemoteAuthProvider を使用した OAuth 2.1。
• ツールごとの認証： @mcp.tool(auth=require_scopes("admin"))。
• デュアルモードパターン： 共通ツールを common.py にまとめ、認証あり／なしのエントリーポイントを分けます。

---

フェーズ 4：テスト

目標： 決定論的なテストで、すべてのコンポーネントが正しく動作することを確認します。

読み込むもの： references/testing.md（パターン、18 項目のチェックリスト）

4.1 テストを作成する

インメモリの Client を使用します。ネットワークもサブプロセスも不要です。

import pytest
from fastmcp import Client
from server import mcp

@pytest.fixture
async def client():
    async with Client(mcp) as c:
        yield c

async def test_search_items(client):
    result = await client.call_tool("search_items", {"query": "test"})
    assert result.data is not None
    assert not result.is_error

async def test_list_tools(client):
    tools = await client.list_tools()
    names = [t.name for t in tools]
    assert "search_items" in names

4.2 テストカテゴリ

references/testing.md にある8つのカテゴリをすべて網羅します。

1. ディスカバリー — list_tools()、list_resources()、list_prompts() が想定される名前を返します。
2. 正常系 — 各ツールが有効な入力に対して想定される出力を返します。
3. エラー処理 — 無効な入力でクラッシュせず、ToolError が発生します。
4. エッジケース — 空文字列、境界値、Unicode、大きな入力をテストします。
5. リソース — read_resource(uri) が正しいコンテンツと MIME タイプを返します。
6. プロンプト — get_prompt(name, args) が想定されるメッセージを返します。
7. 統合 — ツールチェーン、ライフスパンのセットアップ／ティアダウンをテストします。
8. 並行処理 — 複数の呼び出しを同時に行っても互いに干渉しません。

4.3 対話型テスト

# MCP Inspector (browser-based)
fastmcp dev inspector mcp/<name>/server.py

# CLI testing
fastmcp list mcp/<name>/server.py
fastmcp call mcp/<name>/server.py search_items '{"query": "test"}'

4.4 テストの実行

cd mcp/<name> && uv run pytest -v

---

フェーズ5：デプロイと設定

目標： MCP クライアントがサーバーを利用できるようにします。

参照： references/deployment.md（トランスポート、クライアント設定、Docker）

5.1 トランスポートの選択

シナリオ	トランスポート	コマンド
ローカル／Claude Desktop	stdio	fastmcp run server.py
リモート／マルチクライアント	Streamable HTTP	fastmcp run server.py --transport http --port 8000
開発	Inspector	fastmcp dev inspector server.py

5.2 クライアント設定の生成

クライアント設定（Claude Desktop、Claude Code、Cursor）に追加します。

{
  "mcpServers": {
    "server-name": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/mcp/<name>", "fastmcp", "run", "server.py"]
    }
  }
}

クライアントごとの完全な設定については、references/deployment.md の §7 を参照してください。

5.3 検証

MCP サーバーの検証（スキルの check.py は MCP サーバーをチェックしません）：

# Import check
uv run python -c "from server import mcp; print(mcp.name)"

# List registered components
fastmcp list mcp/<name>/server.py

# Interactive inspection
fastmcp dev inspector mcp/<name>/server.py

5.4 品質チェックリスト

サーバーの完成を宣言する前に、以下を確認します。

• すべてのツールの全パラメーターに Annotated と Field(description=...) が指定されている
• すべてのツールに詳細な docstring（WHAT、WHEN、WHEN NOT、RETURNS）がある
• すべてのツールに annotations（最低限 readOnlyHint）がある
• すべてのツールで、想定される失敗に ToolError を使用している
• どのツールにも print() や stdout への書き込みがない
• リソースの URI スキームと MIME タイプが正しい
• テストが成功する：uv run pytest -v
• MCP Inspector にすべてのコンポーネントが正しく表示される
• fastmcp.json に必要な依存関係がすべて記載されている
• pyproject.toml のメタデータと依存関係が正しい
• 非推奨のコンストラクター引数がない（rc1 で削除済み）
• 機密性の高いカスタムルートに手動の認証がある
• 本番環境へのデプロイ時に mask_error_details=True が設定されている

---

参照ファイル一覧

該当するフェーズで必要に応じてこれらのファイルを読み込んでください。一度にすべて読み込まないでください。

ファイル	内容	読み込むタイミング
references/fastmcp-v3-api.md	v3 API 全体：コンストラクター、デコレーター、Context、戻り値の型、リソース、プロンプト、プロバイダー、トランスフォーム、14 個のミドルウェア、バックグラウンドタスク、可視性、v2 から v3 への変更点	フェーズ 3
references/tool-design.md	LLM に最適化された名前付け、説明、パラメーター、アノテーション、エラー処理、8 種類のツールパターン、構造化出力、応答パターン、アンチパターン	フェーズ 1、3
references/server-composition.md	mount()、import_server()、プロキシ、FileSystemProvider、OpenAPI（OpenAPIProvider と from_openapi）、FastAPI 変換、カスタムプロバイダー、トランスフォーム、ゲートウェイパターン、DRY 登録	フェーズ 1、3
references/testing.md	インメモリ Client、pytest のセットアップ、conftest.py のテンプレート、8 種類のテストカテゴリ、MCP Inspector、CLI テスト、18 項目のチェックリスト	フェーズ 4
references/auth-and-security.md	OAuth 2.1、JWTVerifier、コンポーネントごとの認証、カスタム認証チェック、セッションベースの可視性、カスタムルートの認証バイパス、SSRF 防止、デュアルモードパターン、15 のセキュリティルール	フェーズ 3
references/deployment.md	トランスポート、FastMCP CLI、ASGI、カスタムルート、クライアント設定、fastmcp.json スキーマ、Docker、バックグラウンドタスクワーカー、本番環境向けチェックリスト	フェーズ 5
references/resources-and-prompts.md	リソース（静的、動的、バイナリ）、プロンプト（単一メッセージ／複数メッセージ）、リソースとツールの使い分け、テストパターン	フェーズ 3
references/common-errors.md	34 件のエラー：症状 → 原因 → v3 向けに更新された修正方法、クイック修正の一覧表	デバッグモード
references/quick-reference.md	最小限の例：サーバー、ツール、リソース、プロンプト、ライフスパン、テスト、実行	クイックスタート

---

重要なルール

以下は必ず守ってください。違反すると、MCP サーバーが正常に動作しません。

1. 標準出力を使用しないでください。 ツール／リソース／プロンプト内で print() を使用したり、標準出力に書き込んだりしないでください。標準出力は MCP のトランスポートです。ログには ctx.info()、ctx.warning()、ctx.error() を使用してください。

2. 想定されるエラーには ToolError を使用してください。 ユーザーに表示するエラーには、必ず raise ToolError("message") を使用してください。本番環境では、標準の例外は mask_error_details によってマスクされます。

3. 説明は詳しく記述してください。 すべてのツールに 3～5 文の docstring が必要です。すべてのパラメーターに Field(description=...) が必要です。LLM は、内容を理解できないツールを使用できません。

4. すべてのツールにアノテーションを設定してください。 readOnlyHint、destructiveHint、idempotentHint、openWorldHint を設定してください。クライアントはこれらを確認フローや再試行ロジックに使用します。

5. *args や **kwargs を使用しないでください。 MCP では、ツール入力に固定の JSON スキーマが必要です。動的なシグネチャはスキーマ生成を妨げます。

6. 状態へのアクセスは非同期で行ってください。 v3 では、ctx.get_state() と ctx.set_state() は非同期です。必ず await を付けて呼び出してください。

7. URI スキームは必須です。 すべてのリソース URI にスキーム（data://、config://、users://）を指定してください。スキームのないパスは失敗します。

8. 決定的にテストしてください。 手動でプロンプトを入力するのではなく、インメモリの Client(mcp) を使用してください。テストは繰り返し実行でき、自動化されている必要があります。

9. モジュールレベルの mcp 変数を使用してください。 FastMCP インスタンスはモジュールレベルでインポートできなければなりません。デフォルトでは、fastmcp run は server:mcp をインポートします。

10. シークレットは環境変数にのみ保存してください。 API キーをハードコードしないでください。トークンをツールのパラメーターとして受け取らないでください。環境から読み込み、起動時に検証してください。

---

クイックリファレンス

サーバー、ツール、リソース、プロンプト、ライフスパン、テスト、実行コマンドの最小限の例を含む完全なクイックリファレンスについては、references/quick-reference.md を読み込んでください。

---

標準用語

以下の用語を一貫して使用してください。同義語を独自に作らないでください。

標準用語	意味	使用しない用語
tool	クライアントに公開される、呼び出し可能な MCP 関数	「エンドポイント」、「アクション」、「コマンド」
resource	クライアントに公開される、URI で指定される読み取り専用データ	「アセット」、「ファイル」、「データソース」
prompt	LLM の動作を導く再利用可能なメッセージテンプレート	「指示」、「システムメッセージ」
provider	動的なコンポーネントのソース（例：FileSystemProvider、OpenAPIProvider）	「プラグイン」、「アダプター」
transform	マウント時にコンポーネントを変更するミドルウェア	「フィルター」、「インターセプター」
middleware	サーバーのパイプラインでリクエスト／レスポンスを処理するフック	「ハンドラー」、「デコレーター」
lifespan	サーバーリソースを共有するための非同期コンテキストマネージャー	「起動フック」、「初期化」
mount	子サーバーを名前空間のプレフィックス付きでアタッチすること	「登録」、「インクルード」
namespace	マウント時にコンポーネント名に追加されるプレフィックス	「スコープ」、「プレフィックス」
Context	ロギング、状態、サンプリングのためにツールへ渡される実行時オブジェクト	「リクエスト」、「セッション」
ToolError	ユーザーに表示するエラーメッセージ用の例外クラス	「raise Exception」
annotation	ツールのメタデータに関するヒント（readOnlyHint、destructiveHint など）	「タグ」、「ラベル」
transport	stdio または Streamable HTTP を使用する通信レイヤー	「プロトコル」、「チャネル」

検証要件

このスキルの変更を完了とする前に、次を実行してください。

python skills/mcp-creator/scripts/check.py

完了条件：

1. scripts/check.py が終了コード 0 で終了すること。
2. MCP スキャフォールドのスモークチェック：python scripts/scaffold_mcp.py --dry-run example-server。