mcp-creator

MCP Creator — FastMCP v3

使用 FastMCP v3（3.0.0rc2）构建可用于生产环境的 MCP 服务。本技能将指导你完成调研、搭建脚手架、实现、测试和部署。所有第一方输出均遵循本仓库的约定：mcp/<name>/ 目录、fastmcp.json 配置、准确的 uv 工作区成员、祈使语气、kebab-case 命名。mcp/servers/ 专用于机器本地安装的第三方 MCP；该目录已加入 gitignore。

目标： 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 句话：是什么、何时使用、何时不使用、返回什么
参数	每个参数都要指定类型、描述和约束，使用 Annotated[type, Field(...)]
注解	readOnlyHint、destructiveHint、idempotentHint、openWorldHint
错误情况	预期失败时要抛出的 ToolError 消息

1.4 设计资源和提示词

• 资源用于静态或变化缓慢的数据（配置、架构、状态）。通过 URI 寻址。
• 提示词用于可复用的消息模板，以引导大模型行为。
• 有关 URI 模式和提示词设计，请参阅 references/fastmcp-v3-api.md §6-7。

1.5 规划架构

确定组合策略：

• 单个服务 — 适用于大多数情况。一个包含所有工具的 FastMCP 实例。
• 组合服务 — 适用于大型 API。通过 mount() 挂载带有命名空间的领域服务。
• 基于 Provider — 动态注册工具。使用 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 |

---

Phase 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 服务。

---

Phase 3：实现

目标： 根据 Phase 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 客户端、数据库连接），添加可组合的生命周期：

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=...)]。
• 编写详细的文档字符串：说明工具的功能、适用时机、不适用时机以及返回内容。
• 对预期的失败使用 ToolError（客户端始终可见）。
• 为每个工具设置 annotations 字典 — 至少包含 readOnlyHint。
• 使用 ctx: Context | None = None，以便在没有 MCP 运行时的情况下进行测试。

8 种完整的工具模式（同步、异步 + Context、有状态、外部 API、数据处理、依赖注入、采样、信息征询）请参阅 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，并创建单独的有身份验证／无身份验证入口点。

---

Phase 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 服务验证（skill 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=...)
• 每个工具都有详尽的文档字符串（WHAT、WHEN、WHEN NOT、RETURNS）
• 每个工具都有 annotations（至少包含 readOnlyHint）
• 每个工具都使用 ToolError 处理预期故障
• 所有工具中都没有 print() 或写入 stdout 的操作
• 资源使用正确的 URI 方案和 MIME 类型
• 测试通过：uv run pytest -v
• MCP Inspector 能正确显示所有组件
• fastmcp.json 列出所有必需的依赖项
• pyproject.toml 包含正确的元数据和依赖项
• 没有已弃用的构造函数 kwargs（在 rc1 中移除）
• 自定义路由包含敏感操作所需的手动身份验证
• 生产部署已设置 mask_error_details=True

---

参考文件索引

在相关阶段按需加载这些文件。请勿一次性全部加载。

文件	内容	加载阶段
references/fastmcp-v3-api.md	完整的 v3 API 接口：构造函数、装饰器、Context、返回类型、资源、提示词、提供方、转换器、14 种中间件、后台任务、可见性、v2→v3 变更	阶段 3
references/tool-design.md	针对大模型优化的命名、描述、参数、注解、错误处理、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. 不得向 stdout 输出。 切勿在工具/资源/提示词中使用 print() 或向 stdout 写入内容。stdout 是 MCP 传输通道。请使用 ctx.info()、ctx.warning()、ctx.error() 记录日志。

2. 预期内的失败使用 ToolError。 面向用户的错误一律使用 raise ToolError("message")。在生产环境中，mask_error_details 会隐藏标准异常的详细信息。

3. 描述要详尽。 每个工具都需要 3–5 句的文档字符串。每个参数都需要 Field(description=...)。大模型无法使用自己不了解的工具。

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，查看包含服务、工具、资源、提示词、生命周期、测试和运行命令的完整快速参考及最简示例。

---

规范词汇

请始终一致地使用这些术语。不要自行创造同义词。

规范术语	含义	不要使用
工具	暴露给客户端的可调用 MCP 函数	“端点”、“操作”、“命令”
资源	暴露给客户端、通过 URI 寻址的只读数据	“资产”、“文件”、“数据源”
提示词	用于引导大模型行为的可复用消息模板	“指令”、“系统消息”
提供方	动态组件来源（例如 FileSystemProvider、OpenAPIProvider）	“插件”、“适配器”
转换	在挂载时修改组件的中间件	“过滤器”、“拦截器”
中间件	服务管道中用于处理请求／响应的钩子	“处理器”、“装饰器”
生命周期	用于管理共享服务资源的异步上下文管理器	“启动钩子”、“初始化”
挂载	使用命名空间前缀附加子服务	“注册”、“包含”
命名空间	挂载期间添加到组件名称前的前缀	“作用域”、“前缀”
Context	传递给工具、用于日志记录、状态管理和采样的运行时对象	“请求”、“会话”
ToolError	用于向用户显示错误消息的异常类	“raise Exception”
注解	工具元数据提示（readOnlyHint、destructiveHint 等）	“标签”、“标记”
传输	通信层：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。