fastmcp-builder

FastMCP ビルダー - 本番環境向け MCP サーバー開発

概要

このスキルでは、公式の高レベル Python フレームワークである FastMCP を使用して MCP（Model Context Protocol）サーバーを構築するための、本番環境に対応した包括的なパターンを紹介します。完全なリファレンス実装、実際に動作する例、本番環境で実証されたベストプラクティスを収録しています。

Python で MCP サーバーを構築するには、FastMCP の使用を推奨します。低レベルの MCP SDK よりもシンプルで、迅速に開発でき、保守しやすいためです。

内容

このスキルには、次の内容が含まれています。

1. リファレンスドキュメント（reference/）- FastMCP 開発のあらゆる側面を網羅した 6 つの包括的なガイド
2. コード例（examples/）- 最小構成から完全なサーバーまで、実行可能な例
3. 完全なリファレンスプロジェクト（reference-project/）- 以下を含む本番環境向けの完全な実装
   • 本番環境に対応した 6 つのツール
   • 7 つのリソースインスタンス（4 種類）
   • 1 つの汎用プロンプト
   • 145 件のテストに合格
   • OAuth 連携
   • 完全なドキュメント

💡 ヒント： 迷った場合は、実際の実装例を確認するために reference-project を参照してください。

このスキルを使う場面

次のような場合に、このスキルを使用してください。

✅ FastMCP で MCP サーバーを構築する - Python ベースの MCP サーバー開発
✅ OAuth 認証を追加する - 特にリモートアクセス向けの Google OAuth
✅ 本番環境向けのパターンを実装する - ベストプラクティスに沿ったツール、リソース、プロンプト
✅ 包括的なテストを設定する - FastMCP Client を使用した、高速なインメモリテスト
✅ 大規模なプロジェクトを構成する - 適切な整理と関心の分離
✅ 本番環境にデプロイする - 認証、エラー処理、監視を含む

次の用途には、このスキルを使用しないでください。

• ❌ TypeScript／Node.js の MCP サーバー（代わりに mcp-builder スキルを使用してください）
• ❌ 低レベルの MCP プロトコル作業（MCP SDK を直接使用してください）
• ❌ FastMCP 以外の Python サーバー（このスキルは FastMCP 専用です）

公式ドキュメントの参照

重要： このスキルのリファレンス資料で扱っていない質問や問題に直面した場合は、次の方法を使用してください。

主な方法：WebSearch を使用する（推奨）

FastMCP のドキュメントを見つける最も信頼性の高い方法は、サイトを指定したクエリで WebSearch を使用することです。

WebSearch(
    query="site:gofastmcp.com [your specific topic]"
)

これにより、公式 FastMCP ドキュメントサイトが検索され、関連するページが表示されます。

代替方法：ページに直接アクセスする

ドキュメントの大まかな構成が分かっている場合は、特定のページを直接取得できます。

WebFetch(
    url="https://gofastmcp.com/[section]/[topic]",
    prompt="Your specific question about this topic"
)

主なドキュメントのセクション：

• /getting-started/ - インストール、クイックスタート、ようこそ
• /servers/ - ツール、リソース、プロンプト、コンテキスト、ロギング
• /deployment/ - サーバーの実行、HTTP デプロイ、設定
• /integrations/ - Auth0、AWS Cognito、Azure、GitHub、Google、WorkOS、OpenAI など
• /testing/ - テストガイドとベストプラクティス

ヒント： URL の末尾に .md を追加すると、任意のページに Markdown 形式でアクセスできます。

公式ドキュメントを参照する場面

次の場合は、公式ドキュメントを参照してください。

• このスキルのリファレンスで扱っていない機能や API に直面した場合
• 最新の更新や破壊的変更を確認する必要がある場合
• FastMCP の機能について、ユーザーから質問されて確信が持てない場合
• リファレンス資料にない高度なパターンを実装する場合
• バージョン固有の動作や非推奨事項がある場合
• Google OAuth 以外の認証プロバイダーについて確認が必要な場合
• 現在のベストプラクティスを確認したい場合

ワークフローの例

1. ユーザーが OpenAI との連携について質問した場合：

   WebSearch(query="site:gofastmcp.com openai integration")
   → Find https://gofastmcp.com/integrations/openai
   → Fetch that page for details
   

2. ユーザーが AWS Cognito 認証について質問した場合：

   WebSearch(query="site:gofastmcp.com aws cognito oauth")
   → Find relevant auth documentation
   → Implement based on official guidance
   

3. ユーザーがテストパターンについて質問した場合：

   WebSearch(query="site:gofastmcp.com testing")
   → Find testing documentation
   → Apply patterns from official docs
   

4. 利用できる内容を調べる場合：

   WebSearch(query="site:gofastmcp.com deployment options")
   WebSearch(query="site:gofastmcp.com authentication providers")
   → Browse results to see available topics
   

注： まずこのスキルのリファレンス資料を確認し、必要に応じて公式ドキュメントを参照してください。

---

ワークフロー - FastMCP サーバーの構築

フェーズ 1：計画とセットアップ

ステップ 1.1：FastMCP の概要を確認する

• fastmcp_overview.md を読み込みます
• FastMCP と MCP SDK の違いを理解します
• FastMCP が適切な選択肢であることを確認します（通常はそうです）

ステップ 1.2：要件を把握する

• サーバーにはどのようなツールが必要ですか？
• OAuth 認証は必要ですか？
• リソースやプロンプトは必要ですか？
• デプロイ先はどこですか？

ステップ 1.3：プロジェクト構成を確認する

• project_structure.md を読み込みます
• 推奨されるディレクトリ構成を理解します
• common.py パターン（DRY 原則）について学びます
• デュアルモードパターン（OAuth の有無）を理解します

ステップ 1.4：プロジェクトをセットアップする

プロジェクト構成を作成します：

mkdir my-mcp-server
cd my-mcp-server

# Create directories
mkdir -p app/tools app/resources app/prompts tests

# Create initial files
touch app/__init__.py
touch app/main.py
touch app/main_noauth.py
touch app/common.py
touch app/config.py
touch tests/__init__.py
touch pyproject.toml
touch .env.example
touch README.md

uv で初期化します：

# Install FastMCP
uv add fastmcp==2.13.0.1
uv add python-dotenv==1.2.1

# Add test dependencies
uv add --optional test pytest==8.4.2 pytest-asyncio==1.2.0 pytest-mock==3.15.1 httpx==0.28.1

---

フェーズ 2：コア機能の実装

ステップ 2.1：設定を実装する

project_structure.md のパターンに基づいて app/config.py を作成します：

• 環境変数の読み込み
• 検証機能を備えた設定クラス
• OAuth 設定（必要な場合）
• サーバーのメタデータ

ステップ 2.2：ツールを実装する

包括的なパターンについては、tool_patterns.md を読み込みます：

1. 必要なツールのパターンを特定します：

   • 基本的な同期ツール（ヘルスチェック、簡単なクエリ）
   • データ処理ツール（分析、変換）
   • Context を使用するツール（ログ記録、進捗状況）
   • ステートフルなツール（状態管理が必要な場合）
   • API 連携ツール（外部サービス）

2. app/tools/ にツールを作成します：

   • ツールごと、または論理的なグループごとにファイルを作成します
   • tool_patterns.md のパターンに従います
   • 適切なエラー処理を行います
   • 包括的な docstring を追加します

3. ツール構成の例：

# app/tools/my_tool.py

async def my_tool(param: str, ctx: Context | None = None) -> dict:
    """
    Tool description

    Args:
        param: Parameter description
        ctx: FastMCP context (auto-injected)

    Returns:
        dict: Result structure
    """
    try:
        if ctx:
            await ctx.info("Processing...")

        # Tool logic here
        result = process(param)

        if ctx:
            await ctx.info("Completed!")

        return {"status": "success", "data": result}

    except Exception as e:
        if ctx:
            await ctx.error(f"Failed: {e}")
        return {"status": "error", "error": str(e)}

ステップ 2.3：リソースを実装する（必要な場合）

すべてのリソースタイプについては、resource_patterns.md を読み込みます：

1. リソースタイプを選択します：

   • 静的リソース（ステータス、機能、ドキュメント）
   • 動的リソース（生成コンテンツ）
   • テンプレートリソース（パスパラメーター付き）
   • ワイルドカードリソース（複数セグメントのパス）

2. app/resources/ にリソースを作成します：

   • 静的リソースには static.py を使用します
   • 動的／テンプレート／ワイルドカード用に別ファイルを作成します

3. リソースの例：

# app/resources/welcome.py

def get_welcome_message() -> str:
    """Welcome message resource"""
    return "Welcome to my MCP server!"

ステップ 2.4：プロンプトを実装する（必要な場合）

再利用可能なプロンプトテンプレートを作成します：

# app/prompts/explain.py

def explain_concept(
    concept: str,
    audience_level: str = "intermediate",
) -> str:
    """Generate explanation prompt"""
    return f"Explain {concept} for {audience_level} audience..."

ステップ 2.5：共通登録を作成する

app/common.py ですべてのコンポーネントを登録します：

from fastmcp import FastMCP

# Import tools
from app.tools.my_tool import my_tool

# Import resources
from app.resources.welcome import get_welcome_message

# Import prompts
from app.prompts.explain import explain_concept


def register_all(mcp: FastMCP) -> None:
    """Register all components - DRY principle"""

    # Tools
    mcp.tool()(my_tool)

    # Resources
    mcp.resource("greeting://welcome")(get_welcome_message)

    # Prompts
    mcp.prompt()(explain_concept)

ステップ 2.6：サーバーのエントリーポイントを作成する

app/main_noauth.py（ローカル開発用）：

from fastmcp import FastMCP
from app.config import Config
from app.common import register_all

mcp = FastMCP(Config.SERVER_NAME)
register_all(mcp)

if __name__ == "__main__":
    mcp.run()

app/main.py（OAuth ありの場合。必要な場合）： OAuth の完全なセットアップについては、oauth_integration.md を読み込みます。

---

フェーズ 3：OAuth 連携（必要な場合）

認証付きのリモートアクセスが必要な場合のみ実施します。

ステップ 3.1：Google OAuth をセットアップする

oauth_integration.md に従います：

1. Google Cloud Console で OAuth クライアントを作成します
2. 環境変数（.env）を設定します
3. main.py に GoogleProvider を実装します
4. テスト用に ngrok をセットアップします
5. Claude Desktop Connectors を設定します

ステップ 3.2：OAuth フローをテストする

1. ngrok を起動します
2. base-url を指定してサーバーを起動します
3. Claude Desktop を接続します
4. 認証が機能することを確認します

---

フェーズ 4：テスト

ステップ 4.1：テスト構成をセットアップする

包括的なテストパターンについては、testing_guide.md を読み込みます。

tests/conftest.py を作成します：

import pytest
from fastmcp import Client
from app.main_noauth import mcp


@pytest.fixture
async def client():
    """Provide FastMCP client for testing"""
    async with Client(mcp) as c:
        yield c

ステップ 4.2：ツールのテストを作成する

# tests/test_tools.py

@pytest.mark.asyncio
async def test_my_tool(client):
    """Should execute my_tool successfully"""
    result = await client.call_tool("my_tool", {"param": "test"})
    assert result.data["status"] == "success"

ステップ 4.3：リソースのテストを作成する

# tests/test_resources.py

@pytest.mark.asyncio
async def test_welcome_resource(client):
    """Should read welcome resource"""
    content = await client.read_resource("greeting://welcome")
    assert "Welcome" in content

ステップ 4.4：統合テストを作成する

# tests/test_integration.py

@pytest.mark.asyncio
async def test_complete_workflow(client):
    """Should execute complete workflow"""
    # Test multiple components working together
    pass

ステップ 4.5：テストを実行する

# Run all tests
uv run pytest tests/ -v

# Run with coverage
uv run pytest tests/ --cov=app --cov-report=html

---

フェーズ 5：ドキュメント作成とデプロイ

ステップ 5.1：README を作成する

以下の内容を記載します。

• プロジェクトの説明
• 機能
• クイックスタートガイド
• OAuth の設定（該当する場合）
• 使用例
• テスト手順
• デプロイガイド

ステップ 5.2：デプロイの準備をする

1. 環境変数：

   • .env.example テンプレートを作成する
   • 必須の変数をすべて記載する
   • .env を git にコミットしない

2. テスト：

   • すべてのテストが成功することを確認する
   • OAuth フローをテストする（該当する場合）
   • 本番環境に近い環境でテストする

3. デプロイ：

   • プラットフォームを選択する（Railway、Fly.io、VPS）
   • HTTPS を設定する（OAuth に必須）
   • 環境変数を設定する
   • デプロイしてテストする

---

リファレンスドキュメント

開発中、必要に応じて以下を参照してください。

基本リファレンス

• fastmcp_overview.md - FastMCP の概要、使用する場面、主な機能
• project_structure.md - 推奨構成、ファイルの整理方法、パターン

実装ガイド

• tool_patterns.md - 完全な例付きの 6 種類のツールパターン
• resource_patterns.md - 4 種類のリソース（静的、動的、テンプレート、ワイルドカード）
• oauth_integration.md - Google OAuth の完全な設定ガイド
• testing_guide.md - FastMCP Client によるテスト、パターン、ベストプラクティス

サンプルコード

以下の完全なサンプルを実行または参照してください。

• minimal_server.py - 最もシンプルな FastMCP サーバー
• complete_server_structure.py - 機能をすべて備えた単一ファイルの例
• test_examples.py - 包括的なテスト例

---

クイックスタートの例

例 1：最小構成のサーバー

from fastmcp import FastMCP

mcp = FastMCP("my-server")

@mcp.tool()
def greet(name: str) -> str:
    """Greet someone"""
    return f"Hello, {name}!"

if __name__ == "__main__":
    mcp.run()

例 2：複数のコンポーネントを備えたサーバー

from fastmcp import FastMCP, Context

mcp = FastMCP("my-server")

# Tool
@mcp.tool()
async def process(text: str, ctx: Context | None = None) -> dict:
    if ctx:
        await ctx.info("Processing...")
    return {"result": text.upper()}

# Resource
@mcp.resource("greeting://hello")
def get_greeting() -> str:
    return "Hello from resource!"

# Prompt
@mcp.prompt()
def explain(topic: str) -> str:
    return f"Explain {topic} in detail"

if __name__ == "__main__":
    mcp.run()

例 3：OAuth を使用する場合

from fastmcp import FastMCP
from fastmcp.server.auth.providers.google import GoogleProvider
import os

auth = GoogleProvider(
    client_id=os.getenv("GOOGLE_CLIENT_ID"),
    client_secret=os.getenv("GOOGLE_CLIENT_SECRET"),
    base_url="https://your-server.com",
)

mcp = FastMCP("my-server", auth=auth)

# ... add tools, resources, prompts ...

if __name__ == "__main__":
    mcp.run(transport="http", host="0.0.0.0", port=8000)

---

ベストプラクティスのまとめ

1. ✅ FastMCP を使用する - ほとんどの用途で MCP SDK よりシンプルです
2. ✅ プロジェクト構成に従う - common.py パターン（DRY）を使用します
3. ✅ デュアルモードのサーバー - main.py（OAuth）+ main_noauth.py（ローカル）
4. ✅ 包括的にテストする - FastMCP Client を使用し、カバレッジ 80% 超を目指します
5. ✅ 明確なドキュメントを作成する - Docstring、README、使用例
6. ✅ エラーを処理する - 適切に失敗させ、わかりやすいエラーメッセージを表示します
7. ✅ Context を活用する - ロギングと進捗報告で UX を向上させます
8. ✅ セキュリティを確保する - 環境変数を使用し、シークレットをコミットしません

---

よくあるワークフロー

新しいツールを作成する

1. app/tools/my_tool.py を作成する
2. ツール関数を実装する
3. app/common.py の登録に追加する
4. tests/test_tools.py にテストを作成する
5. テストを実行する：uv run pytest tests/test_tools.py -v

OAuth を追加する

1. oauth_integration.md を確認する
2. Google OAuth 認証情報を設定する
3. app/config.py を OAuth 設定に合わせて更新する
4. GoogleProvider を使用するよう app/main.py を変更する
5. ngrok でテストする
6. Claude Desktop Connectors を設定する

デバッグ

1. ローカルテストをすばやく行うには main_noauth.py を使用する
2. Context でロギングを追加する：await ctx.debug(...)
3. 問題を切り分けるためのテストを作成する
4. common.py のツール／リソース登録を確認する
5. 環境変数が読み込まれていることを確認する

---

追加リソース

• FastMCP ドキュメント： https://gofastmcp.com/
• FastMCP GitHub： https://github.com/jlowin/fastmcp
• MCP 仕様： https://modelcontextprotocol.io/
• Google OAuth ガイド： https://developers.google.com/identity/protocols/oauth2

---

注意事項

• このスキルでは、低レベルの MCP SDK ではなく FastMCP に焦点を当てています
• すべての例で Python 3.11+ を使用しています
• OAuth の例では Google OAuth を使用しています（他のプロバイダーも使用可能です）
• テストには FastMCP Client を使用しています（メモリ内で実行され、高速です）
• デプロイの例は本番環境ですぐに使用できます

開発をお楽しみください！ 🚀