Fastmcp Builder

FastMCP生成器-克劳德代码技能

使用FastMCP Python框架构建生产就绪的MCP（模型上下文协议）服务器的全面克劳德代码技能。该技能提供了完整的参考实现、工作示例和经过验证的模式，用于使用工具、资源、提示、OAuth身份验证和全面测试创建健壮的MCP服务器。

什么是FastMCP？

FastMCP 是用于构建MCP服务器的官方高级Python框架。它比低级MCP SDK更简单、开发更快、更易于维护。该技能专门侧重于基于FastMCP的开发。

包含什么

此技能包含构建生产就绪的FastMCP服务器所需的一切：

1.参考文件(reference/)

六个全面的指南涵盖了FastMCP开发的各个方面：

• fastmcp-overview.md -介绍，何时使用FastMCP，关键功能
• project_structure.md -推荐的结构、文件组织、DRY模式
• tool_patterns.md -6种工具模式及其完整示例
• resource_patterns.md -4种资源类型（静态、动态、模板、通配符）
• oauth_integration.md -完整的Google OAuth设置指南
• testing_guide.md -FastMCP客户端测试、模式、最佳实践

2.代码示例(examples/)

从最小服务器到完整服务器的可运行示例：

• minimal_server.py -绝对最简单的FastMCP服务器（28行）
• complete_server_structure.py -具有所有模式的全功能单文件示例
• test_example.py -综合测试示例

3.完成参考项目(reference-project/)

展示最佳实践的完整生产实施：

• 6个生产就绪工具 -各种模式（同步、异步、有状态、有上下文）
• 7个资源实例 -4种类型（静态、动态、模板、通配符）
• 1个通用提示 -可重复使用的提示模板
• 145项测试通过 -全面的测试覆盖率
• OAuth集成 -完成Google OAuth设置
• 双模架构 - main.py （使用OAuth）+ main_noauth.py （本地测试）
• 干燥原理 -用途 common.py 用于组件注册

何时使用此技能

在需要时使用此技能：

• 使用FastMCP构建MCP服务器（基于Python的开发）
• 添加OAuth身份验证（特别是用于远程访问的Google OAuth）
• 实施生产模式（工具、资源、最佳实践提示）
• 设置全面的测试（使用FastMCP客户端进行快速内存测试）
• 构建更大的项目（适当的组织和关注点的分离）
• 部署到生产环境（具有身份验证、错误处理、监控）

不要将此技能用于：

• TypeScript/Node.js MCP服务器（使用MCP构建器技能代替）
• 底层MCP协议工作（直接使用MCP SDK）
• 非FastMCP Python服务器（这是特定于FastMCP的）

安装

选项1：通过插件市场安装（推荐）

1. 注册此市场 克劳德代码：

   /plugin marketplace add husniadil/fastmcp-builder

1. 浏览并安装：

- 选择“浏览并安装插件” - 选择“fastmcp构建器技能” - 选择“fastmcp构建器” - 点击“立即安装”

1. 或直接安装：

   /plugin install fastmcp-builder@fastmcp-builder-skill

选项2：手动安装

克隆或下载此存储库到您的Claude Code技能目录：

cd ~/.claude/skills
git clone https://github.com/husniadil/fastmcp-builder.git

使用技能

安装后，只需在您的请求中引用技能：

Use the fastmcp-builder skill to create a new MCP server with OAuth authentication

快速开始

简单的例子

创建一个最小的FastMCP服务器：

from fastmcp import FastMCP

mcp = FastMCP("my-server")

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

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

尝试包含的示例

导航到技能目录并运行示例：

# Navigate to skill directory
cd ~/.claude/plugins/marketplaces/fastmcp-builder-skill

# Try the minimal server
python examples/minimal_server.py

# Try the complete server structure
python examples/complete_server_structure.py

# Run with HTTP mode
python examples/complete_server_structure.py --http

构建您的第一台服务器

第一阶段：规划和设置

1. 查看FastMCP概述 -负载 reference/fastmcp_overview.md
2. 了解需求 -你需要什么工具、资源、提示？
3. 审查项目结构 -负载 reference/project_structure.md
4. 建立项目 -创建目录结构并安装依赖项

mkdir my-mcp-server && cd my-mcp-server
mkdir -p app/tools app/resources app/prompts tests
uv add fastmcp==2.13.0.1 python-dotenv==1.2.1
uv add --optional test pytest==8.4.2 pytest-asyncio==1.2.0 pytest-mock==3.15.1 httpx==0.28.1

第二阶段：核心实施

1. 机具配置 (app/config.py)-环境变量、设置
2. 实施工具 (app/tools/)-遵循以下模式 reference/tool_patterns.md
3. 实施资源 (app/resources/)-遵循以下模式 reference/resource_patterns.md
4. 实施提示 (app/prompts/)-可重复使用的提示模板
5. 创建通用注册 (app/common.py)-组件注册的干燥原则
6. 创建服务器入口点 - main_noauth.py （本地）+ main.py （OAuth）

第3阶段：OAuth集成（可选）

跟随 reference/oauth_integration.md 用于：

1. 设置Google OAuth凭据
2. 实施GoogleProvider
3. 使用ngrok进行测试
4. 配置Claude桌面

第4阶段：测试

跟随 reference/testing_guide.md 用于：

1. 设置测试结构(tests/conftest.py)
2. 编写工具测试
3. 编写资源测试
4. 编写集成测试
5. 运行测试： uv run pytest tests/ -v

第5阶段：文件编制和部署

1. 编写全面的自述文件
2. 创建.env.example.模板
3. 测试OAuth流
4. 部署到生产环境（Railway、Fly.io、VPS）

项目结构

FastMCP项目的推荐结构：

my-mcp-server/
├── app/
│   ├── __init__.py
│   ├── config.py           # Configuration & environment variables
│   ├── common.py           # Shared component registration (DRY)
│   ├── main.py             # Server with OAuth
│   ├── main_noauth.py      # Server without OAuth (local testing)
│   ├── tools/              # Tool implementations
│   │   ├── __init__.py
│   │   ├── my_tool.py
│   │   └── ...
│   ├── resources/          # Resource implementations
│   │   ├── __init__.py
│   │   ├── static.py
│   │   └── ...
│   └── prompts/            # Prompt templates
│       ├── __init__.py
│       └── explain.py
├── tests/
│   ├── __init__.py
│   ├── conftest.py         # Test fixtures
│   ├── test_tools.py
│   ├── test_resources.py
│   └── test_integration.py
├── pyproject.toml          # Project dependencies
├── .env.example            # Environment variable template
├── .env                    # Actual environment variables (gitignored)
└── README.md

工具样式

该技能包括6种经过验证的工具模式：

1. 基本同步工具 -简单的同步功能（健康检查、查询）
2. 数据处理工具 -文本分析、转换
3. 带有上下文的工具 -日志记录、进度跟踪、更好的用户体验
4. 状态工具 -计数器、会话管理
5. API集成工具 -外部服务电话
6. 高级异步工具 -复杂的工作流程，并行处理

看 reference/tool_patterns.md 查看完整示例。

资源模式

此技能包括4种资源类型：

1. 静态资源 -固定内容（状态、功能、文档）
2. 动态资源 -生成内容（当前时间、计算数据）
3. 模板资源 -路径参数(user://{user_id})
4. 通配符资源 -多段路径(docs://{path*})

看 reference/resource_patterns.md 查看完整示例。

OAuth集成

添加Google OAuth身份验证的完整指南：

• 设置谷歌云控制台
• 实施GoogleProvider
• 使用ngrok进行测试
• 配置Claude桌面连接器
• 生产部署注意事项

看 reference/oauth_integration.md 完整的指南。

测试

使用FastMCP客户端的全面测试指南：

• 快速的内存测试（无需启动服务器）
• 工具测试模式
• 资源测试模式
• 集成测试模式
• 实现>80%的测试覆盖率

看 reference/testing_guide.md 查看完整示例。

最佳实践

1. 使用FastMCP -在大多数用例中比MCP SDK更简单
2. 遵循项目结构 -使用 common.py 模式（干燥原理）
3. 双模服务器 - main.py （OAuth）+ main_noauth.py （本地）
4. 全面测试 -使用FastMCP客户端，目标覆盖率>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. 审查 reference/oauth_integration.md
2. 设置Google OAuth凭据
3. 更新 app/config.py 使用OAuth设置
4. 修改 app/main.py 使用GoogleProvider
5. 使用ngrok进行测试
6. 配置Claude桌面连接器

调试

1. 使用 main_noauth.py 用于更快的本地测试
2. 使用上下文添加日志记录： await ctx.debug(...)
3. 编写测试以隔离问题
4. 检查中的工具/资源注册 common.py
5. 验证加载的环境变量

参考项目详细信息

这 reference-project/ 目录包含完整的生产实现：

• 姓名： mcp-auth-demo
• 版本： 1.0.0
• 工具： 6（ping、计数器、process_text、analyze_text、get_forecast、request_info）
• 资源： 4种类型的7个实例
• 提示： 1个通用提示模板
• 测验： 145项全面覆盖的测试通过
• 特征： OAuth、双模架构、DRY原则、全面的错误处理

在构建自己的服务器时，请将此作为参考。

其他资源

• FastMCP文档： https://gofastmcp.com/
• FastMCP GitHub： https://github.com/jlowin/fastmcp
• MCP规范： https://modelcontextprotocol.io/
• 谷歌OAuth指南： https://developers.google.com/identity/protocols/oauth2
• Claude代码技能： https://docs.claude.com/en/docs/claude-code/skills.md

需求

• Python 3.11+
• FastMCP 2.13.0.1
• python dotenv 1.2.1

用于测试：

• pytest 8.4.2
• pytest异步1.2.0
• pytest模拟3.15.1
• httpx 0.28.1

贡献

这是克劳德代码技能。贡献：

1. 使用参考项目测试更改
2. 确保所有示例都成功运行
3. 根据需要更新文档
4. 为新模式添加测试

许可证

麻省理工学院许可证-版权所有2025 Husni Adil Makmur

此技能按原样提供，用于Claude Code。看 许可证 文件以获取详细信息。

FastMCP框架本身是单独许可的-请参阅 FastMCP存储库 了解详情。

备注

• 此技能侧重于 FastMCP，而不是低级MCP SDK
• 所有示例均使用 Python 3.11+
• OAuth示例使用 谷歌OAuth （其他供应商可能）
• 测试用途 FastMCP客户端 （内存中，快速）
• 部署示例已准备好投入生产

快乐建筑！