creating-mcp-servers

MCP サーバーの作成

FastMCP v2 を使用して、本番環境に対応した MCP サーバーを構築し、プログレッシブ開示パターンによってコンテキスト効率を最適化します。

主な機能

1. コアパターンを適用 - 一貫性を保つための 4 つの要件
2. プログレッシブ開示を実装 - 85～93％のトークン削減を実現するゲートウェイパターン
3. ツールの説明を最適化 - 適切なパターンによって 65～70％のトークン削減
4. サーバーをバンドル - 検証を行い、MCPB ファイルとしてパッケージ化
5. 実績のあるゲートウェイパターン - 3 つの完全な実装（Skills、API、Query）

アーキテクチャの決定

1-3 simple tools?
  → Standard FastMCP with optimized tools
  Load: references/MANDATORY_PATTERNS.md

5+ related capabilities?
  → Gateway pattern (progressive disclosure)
  Load: references/PROGRESSIVE_DISCLOSURE.md
  Load: references/GATEWAY_PATTERNS.md

Optimize existing server?
  → Apply mandatory patterns
  Load: references/MANDATORY_PATTERNS.md

Package for distribution?
  → MCPB bundler
  Load: references/MCPB_BUNDLING.md
  Execute: scripts/create_mcpb.py

Need FastMCP documentation?
  → Search references/LLMS_TXT.md for relevant URLs
  → Use web_fetch on gofastmcp.com URLs

必須パターン（概要）

すべての実装で、次の 4 つの要件を満たす必要があります。

1. uv（pip は使用しない） - uv pip install fastmcp
2. 最適化されたツールの説明 - アノテーション、Annotated、簡潔な docstring
3. 信頼できるドキュメント - LLMS_TXT.md インデックスを使って gofastmcp.com から取得
4. すべてのパターンを適用 - すべての実装で検証チェックリストを満たす

詳細は references/MANDATORY_PATTERNS.md を参照してください。

ドキュメントの取得手順

FastMCP のドキュメントを取得するには：

1. Read references/LLMS_TXT.md - complete URL index
2. Search for relevant topic keywords
3. Use web_fetch on matched URLs (append .md for markdown)
4. Apply patterns from fetched documentation

例： 認証パターン → LLMS_TXT.md で「authentication」を検索 → web_fetch https://gofastmcp.com/servers/auth/authentication.md

プログレッシブ開示パターン

機能が 5 つ以上あるサーバー向け：

3 層の読み込み：

1. メタデータ（機能あたり約 20 トークン） - 常に読み込み済み
2. コンテンツ（約 500 トークン） - 必要に応じて読み込み
3. 実行（0 トークン） - 読み込まずに実行

これにより、ベースラインを 85～93％削減できます。references/PROGRESSIVE_DISCLOSURE.md を参照してください。

実装フェーズ

フェーズ 1：調査

LLMS_TXT.md を読む → 関連する URL を見つける → web_fetch でドキュメントを取得

フェーズ 2：実装

アーキテクチャの決定に基づいて適切なリファレンスを読み込みます。4 つすべてのパターンを適用します。

フェーズ 3：パッケージ化（任意）

cd /home/claude
zip -r server-name.mcpb manifest.json server.py README.md
cp server-name.mcpb /mnt/user-data/outputs/

マニフェストの形式については、references/MCPB_BUNDLING.md を参照してください。

リファレンスライブラリ

ドキュメントインデックス（FastMCP の知識を得るために最初に読み込む）：

• LLMS_TXT.md - FastMCP v2 のドキュメント URL 一覧

コアパターン：

• MANDATORY_PATTERNS.md - 4 つのコア要件
• PROGRESSIVE_DISCLOSURE.md - 機能が 5 つ以上ある場合のアーキテクチャ

実装：

• GATEWAY_PATTERNS.md - 本番環境に対応した 3 つの実装
• MCPB_BUNDLING.md - パッケージ化と配布

スクリプト：

• scripts/create_mcpb.py - MCP サーバーを .mcpb ファイルにバンドル

検証チェックリスト

FastMCP の実装を完了する前に、次の項目を確認してください。

✓ Uses uv (not pip)
✓ FastMCP docs fetched from LLMS_TXT.md URLs (not web_search)
✓ Tool annotations (readOnlyHint, title, openWorldHint)
✓ Annotated parameters with Field
✓ Single-sentence docstrings
✓ 65-70% token reduction vs verbose
✓ Server instructions concise (<100 chars)

ゲートウェイの実装では、さらに次の項目も確認してください。

✓ 85%+ baseline context reduction
✓ Discover returns metadata only
✓ Load fetches content on demand
✓ Execute runs without context cost

ツールの説明パターン

変更前（180 トークン）：

@mcp.tool()
async def search_items(query: str):
    """Search for items in the database.
    This tool allows comprehensive searching..."""

変更後（55 トークン）：

@mcp.tool(
    annotations={"title": "Search", "readOnlyHint": True, "openWorldHint": False}
)
async def search_items(
    query: Annotated[str, Field(description="Search text")],
    ctx: Context = None
):
    """Search items. Fast full-text search across all fields."""

よくある落とし穴

❌ mcpb pack CLI を使用する（クラッシュの原因になります。代わりに zip を使用してください）
❌ uv ではなく pip を使用する
❌ FastMCP のドキュメントに web_search を使用する（LLMS_TXT.md の URL に web_fetch を使用してください）
❌ ツールの説明が冗長
❌ ツールのアノテーションがない
❌ ツールが 1～3 個の場合にゲートウェイを使用する（オーバーヘッドがメリットを上回ります）
❌ 関連性のない機能を 1 つのゲートウェイに混在させる