# MCP 创建者 — FastMCP v3 使用 FastMCP v3 (3.0.0rc2) 构建生产就绪的 MCP 服务器。该技能指导研究、搭建、实施、测试和部署。所有输出都遵循此存储库的约定：`mcp//` 目录、`fastmcp.json` 配置、`uv` 工作区成员、命令式语音、短横线命名。 **目标：** FastMCP v3 rc2 — 提供程序/转换架构、14 个内置中间件、OAuth 2.1、服务器组合、组件版本控制、结构化输出、后台任务、启发、采样。 **输入：** `$ARGUMENTS` — 服务、API 或包装为 MCP 服务器的功能。 ** ** ## 调度将 `$ARGUMENTS` 路由到适当的模式： $ARGUMENTS 模式 |模式|开始于 ---|---|--- 服务/API 名称（例如“GitHub”、“Stripe”）| **新服务器** |第一阶段现有服务器的路径（例如`mcp/myserver/`）| **延长** |第三阶段 OpenAPI 规范 URL 或文件路径 | **转换 OpenAPI** |第 2 阶段（脚手架）然后加载 `references/server-composition.md` §6 要转换的 FastAPI 应用程序 | **转换 FastAPI** |第 2 阶段（脚手架）然后加载 `references/server-composition.md` §7 错误消息或“调试”+描述| **调试** |加载 `references/common-errors.md`，匹配症状 “学习”或概念性问题| **学习** |加载相关参考文件，解释空 | **图库/帮助概述** |显示可用模式和示例调用 ** ** ## 查阅实时文档在实施之前，请获取当前的 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 ` 用于特定主题。如果实时文档与捆绑的参考资料相矛盾，**实时文档获胜**。始终首先获取实时文档 - API 详细信息在 rc2 和稳定版本之间变化。 ** ** ## 第一阶段：研究与计划 **目标：** 了解目标服务并设计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`、`destroyerHint`、`idempotencyHint`、`openWorldHint` 错误案例 |预期失败时会引发哪些“ToolError”消息 ### 1.4 设计资源和提示 * **资源** 用于静态/缓慢变化的数据（配置、模式、状态）。 URI 寻址。 * **提示**用于指导 LLM 行为的可重用消息模板。 * 有关 URI 模式和提示设计，请参阅 `references/fastmcp-v3-api.md` §6-7。 ### 1.5 规划架构决定组合策略： * **单服务器** — 大多数情况。一个包含所有工具的“FastMCP”实例。 * **组合服务器** — 大型 API。通过带有命名空间的“mount()”安装域服务器。 * **基于提供商** — 动态工具注册。 `FileSystemProvider` 或自定义 `Provider`。 * **OpenAPI 转换** — 根据 OpenAPI 规范自动生成工具。 `OpenAPIProvider` 或 `FastMCP.from_openapi()`。有关模式，请参阅“references/server-composition.md”。 ### 1.6 可交付成果在继续之前生成工具/资源/提示库存表： |组件|类型 |名称 |描述（简短）| |------------|------|------|--------------------| |工具|工具|搜索问题 |通过查询搜索 GitHub 问题 | |资源 |资源|配置://设置|当前服务器配置| |提示|提示|总结_公关 |总结拉取请求以供审核 | ** ** ## 第二阶段：脚手架 **目标：** 创建项目目录、测试并配置依赖项。 ### 2.1 创建项目结构运行 `wagents new mcp ` 到脚手架： mcp/<名称>/ ├── server.py # FastMCP入口点 ├── pyproject.toml # uv 项目配置 ├── fastmcp.json # FastMCP CLI 配置 └── 测试/ ├── conftest.py # 客户端装置，模拟上下文 └── test_server.py # 自动化测试套件定制脚手架： * 在 `server.py` 中设置服务器名称：`mcp = FastMCP("name")`。 * 在 `pyproject.toml` 中设置包名称：`name = "mcp-"`。 * 更新`pyproject.toml`中的描述。 * 将特定于服务的依赖项添加到“pyproject.toml”和“fastmcp.json”。 ### 2.2 添加测试配置添加到`pyproject.toml`： [工具.pytest.ini_选项] asyncio_mode =“自动” [依赖组] dev = [“pytest>=8”，“pytest-asyncio>=0.25”] 创建 `tests/conftest.py` — 请参阅 `references/testing.md` §4 了解完整模板。 ### 2.3 配置和验证 * 确保根 `pyproject.toml` 具有 `[tool.uv.workspace] Members = ["mcp/*"]`。 * 运行 `cd mcp/ && uvsync` 以安装依赖项。 * 验证：`uv run python -c "from server import mcp; print(mcp.name)"`。注意：“wagents validate”仅验证技能/代理，而不是 MCP 服务器。使用上面的导入检查进行 MCP 服务器验证。 ** ** ## 第三阶段：实施 **目标：** 从第一阶段库存中构建所有工具、资源和提示。 **加载：** `references/fastmcp-v3-api.md`（完整 API 表面）、`references/tool-design.md`（模式） ### 3.1 服务器设置从 fastmcp 导入 FastMCP，上下文 mcp = FastMCP( “服务器名称”， instructions="该服务器提供的内容以及何时使用它的说明。", ）对于共享资源（HTTP 客户端、数据库连接），添加可组合生命周期：从 fastmcp.server.lifespan 导入寿命 @寿命异步 def http_lifespan(服务器): 导入httpx 与 httpx.AsyncClient() 异步作为客户端：产量{“http”：客户端} mcp = FastMCP("服务器名称", lifespan=http_lifespan) # 在工具中访问：ctx.lifespan_context["http"] 将寿命与`|`结合起来：`mcp = FastMCP("name", lifespan=db_lifespan | cache_lifespan)` ### 3.2 实施工具对于清单中的每个工具，请遵循以下模式：从输入导入注释 from pydantic import 字段从 fastmcp 导入上下文从 fastmcp.exceptions 导入 ToolError @mcp.工具（注释={ “readOnlyHint”：正确， “openWorldHint”：正确， }, ）异步 def search_items( 查询：注释[str，Field（description =“搜索词以查找项目。”，min_length = 1）]， limit: Annotated[int, Field(description="返回的最大结果数。", ge=1, le=100)] = 10, ctx：上下文 |无=无， ) -> 字典： """搜索与查询匹配的项目。当您需要按关键字查找项目时，请使用此工具。返回一个列表将项目与其 ID 和标题相匹配。使用限制参数控制结果计数。不搜索已归档的项目。返回包含“项目”列表和“总数”的字典。 ”“” 如果ctx： wait ctx.info(f"搜索：{query}") 尝试：结果=等待do_search（查询，限制）返回{“items”：结果，“total”：len（结果）} 除了 ServiceError 为 e： raise ToolError(f"搜索失败：{e}") **每个工具的关键规则：** * 每个参数上都有“注释[类型，字段（描述=...）]”。 * 详细文档字符串：什么、何时使用、何时不使用、返回什么。 * `ToolError` 表示预期的失败（客户端始终可见）。 * 每个工具上的“annotations”字典——至少是“readOnlyHint”。 * `ctx：上下文 | None = None` 用于无需 MCP 运行时的可测试性。请参阅 `references/tool-design.md` §9 了解 8 种完整的工具模式（同步、异步+上下文、有状态、外部 API、数据处理、依赖项注入、采样、启发）。 ### 3.3 实施资源导入 json @mcp.resource("config://settings", mime_type="application/json") 异步 def get_settings() -> str: """当前服务器配置。""" 返回 json.dumps(设置) @mcp.resource(“用户://{user_id}/个人资料”) 异步 def get_user_profile(user_id: str) -> str: """按 ID 列出的用户个人资料。""" 返回 json.dumps(等待 fetch_profile(user_id)) 有关 URI 模板、查询参数、通配符和基于类的资源，请参阅“references/fastmcp-v3-api.md”第 6 节。 ### 3.4 执行提示从 fastmcp.prompts 导入消息 @mcp.提示 defsummary_pr(pr_number: int,detail_level: str = "brief") -> list[Message]: """生成一个提示来总结拉取请求。""" 返回[消息( 角色=“用户”， content=f"在 {detail_level} 详细级别汇总 PR #{pr_number}。", )] ### 3.5 成分（如果适用）对于大型服务器，拆分为域模块并组合。请参阅“references/server-composition.md”。从 fastmcp 导入 FastMCP 从 .issues 导入 issues_server 从 .repos 导入 repos_server mcp = FastMCP("github") mcp.mount(issues_server, 命名空间=“问题”) mcp.mount(repos_server, 命名空间=“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` 具有共享工具、单独的身份验证/无身份验证入口点。 ** ** ## 第 4 阶段：测试 **目标：** 通过确定性测试验证所有组件是否正常工作。 **加载：** `references/testing.md`（模式，18 项清单） ### 4.1 编写测试使用内存中的“Client”——没有网络，没有子进程：导入pytest 从 fastmcp 导入客户端从服务器导入 mcp @pytest.fixture 异步定义客户端（）：与客户端 (mcp) 异步为 c: 产量c 异步def test_search_items（客户端）：结果 = 等待 client.call_tool("search_items", {"query": "test"}) 断言 result.data 不是 None 断言不是 result.is_error 异步def test_list_tools（客户端）：工具 = 等待 client.list_tools() 名称 = [t.工具中 t 的名称] 在名称中断言“search_items” ### 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（基于浏览器） fastmcp 开发检查器 mcp//server.py # CLI 测试 fastmcp 列表 mcp/<名称>/server.py fastmcp 调用 mcp//server.py search_items '{"query": "test"}' ### 4.4 运行测试 cd mcp/<名称> && uv 运行 pytest -v ** ** ## 第 5 阶段：部署和配置 **目标：** 使服务器可供 MCP 客户端使用。 **加载：** `references/deployment.md`（传输、客户端配置、Docker） ### 5.1 选择交通场景|交通 |命令 ---|---|--- 本地/克劳德桌面|工作室| `fastmcp 运行 server.py` 远程/多客户端|流式 HTTP | `fastmcp 运行 server.py --transport http --port 8000` 发展|督察| `fastmcp 开发检查器 server.py` ### 5.2 生成客户端配置添加到客户端配置（Claude Desktop、Claude Code、Cursor）： { “mcp服务器”：{ “服务器名称”：{ “命令”：“紫外线”， “args”：[“运行”，“--目录”，“/path/to/mcp/<名称>”，“fastmcp”，“运行”，“server.py”] } } } 有关每个客户端的完整配置，请参阅“references/deployment.md”第 7 节。 ### 5.3 验证 MCP 服务器验证（wagents 验证不检查 MCP 服务器）： # 导入检查 uv run python -c "从服务器导入 mcp; print(mcp.name)" # 列出已注册的组件 fastmcp 列表 mcp/<名称>/server.py # 交互式检查 fastmcp 开发检查器 mcp//server.py ### 5.4 质量检查表在声明服务器完成之前： * 每个工具的所有参数都有 `Annotated` \+ `Field(description=...)` * 每个工具都有详细的文档字符串（WHAT、WHEN、WHEN NOT、RETURNS） * 每个工具都有“注释”（至少有“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 表面：构造函数、装饰器、上下文、返回类型、资源、提示、提供者、转换、14 个中间件、后台任务、可见性、v2→v3 更改 |第三阶段 `references/tool-design.md` | LLM 优化的命名、描述、参数、注释、错误处理、8 种工具模式、结构化输出、响应模式、反模式 |第一、三期 `references/server-composition.md` | mount()、import_server()、代理、FileSystemProvider、OpenAPI（OpenAPIProvider + from_openapi）、FastAPI 转换、自定义提供程序、转换、网关模式、DRY 注册 |第一、三期 `参考文献/testing.md` |内存客户端、pytest 设置、conftest.py 模板、8 个测试类别、MCP Inspector、CLI 测试、18 项清单 |第四阶段 `references/auth-and-security.md` | OAuth 2.1、JWTVerifier、每个组件身份验证、自定义身份验证检查、基于会话的可见性、自定义路由身份验证绕过、SSRF 预防、双模式模式、15 条安全规则 |第三阶段 `references/deployment.md` |传输、FastMCP CLI、ASGI、自定义路由、客户端配置、fastmcp.json 架构、Docker、后台任务工作人员、生产清单 |第五阶段 `references/resources-and-prompts.md` |资源（静态、动态、二进制）、提示（单/多消息）、资源与工具指导、测试模式 |第三阶段 `references/common-errors.md` | 34 个错误：症状 → 原因 → v3 更新的修复、快速修复查找表 |调试模式 `references/quick-reference.md` |最小示例：服务器、工具、资源、提示、生命周期、测试、运行 |快速启动 ** ** ## 关键规则这些都是没有商量余地的。违反其中任何一项都会导致 MCP 服务器损坏。 1. **没有标准输出。** 切勿在工具/资源/提示中使用 `print()` 或写入标准输出。标准输出是 MCP 传输。使用 `ctx.info()`、`ctx.warning()`、`ctx.error()` 进行日志记录。 2. **针对预期失败的 ToolError。** 对于面向用户的错误，始终“引发 ToolError("message")”。标准异常在生产中被“mask_error_details”屏蔽。 3. **详细描述。** 每个工具都需要一个 3-5 句话的文档字符串。每个参数都需要`Field(description=...)`。法学硕士不能使用他们不理解的工具。 4. **每个工具上的注释。** 设置`readOnlyHint`，`demulatoryHint`，`idempothint`，`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 寻址只读数据 | “资产”、“文件”、“数据源” **提示** |可重复使用的消息模板指导 LLM 行为 | “指令”、“系统消息” **提供商** |动态组件源（例如，`FileSystemProvider`、`OpenAPIProvider`）| “插件”、“适配器” **转变** |在挂载时修改组件的中间件 | “过滤器”、“拦截器” **中间件** |服务器管道中的请求/响应处理挂钩 | “处理者”、“装饰者” **寿命** |共享服务器资源的异步上下文管理器 | “启动钩子”，“init” **安装** |附加带有命名空间前缀的子服务器 | “注册”、“包含” **命名空间** |挂载期间添加到组件名称的前缀 | “范围”、“前缀” **背景** |传递给用于日志记录、状态、采样的工具的运行时对象“请求”、“会话” **工具错误** |用户可见错误消息的异常类 | “引发异常” **注释** |工具元数据提示（`readOnlyHint`、`destroyerHint` 等）| “标签”、“标签” **交通** |通信层：stdio 或 Streamable HTTP | “协议”、“通道”

MCP创建者

包含技能