fastmcp-builder

FastMCP 构建器——生产级 MCP 服务开发

概述

本技能提供使用 FastMCP（官方高级 Python 框架）构建 MCP（Model Context Protocol）服务的全面、可用于生产环境的模式。其中包含完整的参考实现、可运行的示例，以及经过生产环境验证的最佳实践。

FastMCP 是使用 Python 构建 MCP 服务的推荐方式——与底层 MCP SDK 相比，它更简单、开发速度更快，也更易于维护。

包含内容

本技能包含：

1. 参考文档（reference/）——6 篇全面指南，涵盖 FastMCP 开发的各个方面
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（推荐）

使用 WebSearch 并针对特定网站进行查询，是查找 FastMCP 文档最可靠的方式：

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 中的模式
   • 使用恰当的错误处理
   • 添加全面的文档字符串

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_integration.md 查看完整的 OAuth 设置。

---

阶段 3：OAuth 集成（如需要）

仅当你需要通过身份验证进行远程访问时。

步骤 3.1：设置 Google OAuth

按照 oauth_integration.md 操作：

1. 在 Google Cloud Console 中创建 OAuth Client
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. ✅ 清晰的文档 - 文档字符串、README、使用示例
6. ✅ 错误处理 - 优雅地处理失败，并提供有用的错误消息
7. ✅ 使用上下文 - 使用日志记录和进度信息，提升用户体验
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. 使用 OAuth 设置更新 app/config.py
4. 修改 app/main.py，使用 GoogleProvider
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

---

备注

• 此技能聚焦于 FastMCP，而非底层 MCP SDK
• 所有示例均使用 Python 3.11+
• OAuth 示例使用 Google OAuth（也可使用其他提供方）
• 测试使用 FastMCP Client（内存运行，速度快）
• 部署示例可用于生产环境

祝构建愉快！🚀