creating-mcp-servers

创建 MCP 服务

使用 FastMCP v2 构建可用于生产环境的 MCP 服务，通过渐进式披露模式实现最佳上下文效率。

核心能力

1. 应用核心模式 - 确保一致性的四项要求
2. 实现渐进式披露 - 通过网关模式将令牌用量减少 85-93%
3. 优化工具描述 - 通过恰当的模式将令牌用量减少 65-70%
4. 打包服务 - 将其打包为 MCPB 文件并进行验证
5. 经过验证的网关模式 - 三种完整实现（技能、API、查询）

架构决策

1-3 simple tools?
  → Standard FastMCP with optimized tools
  Load: references/MANDATORY_PATTERNS.md

5+ related capabilities?
  → Gateway pattern (progressive disclosure)
  Load: references/PROGRESSIVE_DISCLOSURE.md
  Load: references/GATEWAY_PATTERNS.md

Optimize existing server?
  → Apply mandatory patterns
  Load: references/MANDATORY_PATTERNS.md

Package for distribution?
  → MCPB bundler
  Load: references/MCPB_BUNDLING.md
  Execute: scripts/create_mcpb.py

Need FastMCP documentation?
  → Search references/LLMS_TXT.md for relevant URLs
  → Use web_fetch on gofastmcp.com URLs

强制模式（摘要）

每种实现都应满足以下四项要求：

1. uv（绝不使用 pip） - uv pip install fastmcp
2. 优化工具描述 - 注释、Annotated、简洁的文档字符串
3. 权威文档 - 通过 LLMS_TXT.md 索引从 gofastmcp.com 获取
4. 应用所有模式 - 每种实现都满足验证清单

详情请参阅 references/MANDATORY_PATTERNS.md

文档检索工作流

获取 FastMCP 文档：

1. Read references/LLMS_TXT.md - complete URL index
2. Search for relevant topic keywords
3. Use web_fetch on matched URLs (append .md for markdown)
4. Apply patterns from fetched documentation

**示例：**身份验证模式 → 在 LLMS_TXT.md 中搜索“authentication” → web_fetch https://gofastmcp.com/servers/auth/authentication.md

渐进式披露模式

适用于具备 5 项或更多能力的服务：

三级加载：

1. 元数据（每项能力约 20 个令牌）- 始终加载
2. 内容（约 500 个令牌）- 按需加载
3. 执行（0 个令牌）- 无需加载即可执行

可将基线用量减少 85-93%。请参阅 references/PROGRESSIVE_DISCLOSURE.md

实现阶段

阶段 1：调研

读取 LLMS_TXT.md → 查找相关 URL → web_fetch 文档

阶段 2：实现

根据架构决策加载适用的参考资料。应用所有四种模式。

阶段 3：打包（可选）

cd /home/claude
zip -r server-name.mcpb manifest.json server.py README.md
cp server-name.mcpb /mnt/user-data/outputs/

清单格式请参阅 references/MCPB_BUNDLING.md。

参考资料库

文档索引（首先加载以了解 FastMCP）：

• LLMS_TXT.md - FastMCP v2 文档的完整 URL 列表

核心模式：

• MANDATORY_PATTERNS.md - 四项核心要求
• PROGRESSIVE_DISCLOSURE.md - 适用于 5 项或更多能力的架构

实现：

• GATEWAY_PATTERNS.md - 三种可用于生产环境的实现
• MCPB_BUNDLING.md - 打包与分发

脚本：

• scripts/create_mcpb.py - 将 MCP 服务打包为 .mcpb 文件

验证清单

完成任何 FastMCP 实现之前：

✓ Uses uv (not pip)
✓ FastMCP docs fetched from LLMS_TXT.md URLs (not web_search)
✓ Tool annotations (readOnlyHint, title, openWorldHint)
✓ Annotated parameters with Field
✓ Single-sentence docstrings
✓ 65-70% token reduction vs verbose
✓ Server instructions concise (<100 chars)

对于网关实现，还需验证：

✓ 85%+ baseline context reduction
✓ Discover returns metadata only
✓ Load fetches content on demand
✓ Execute runs without context cost

工具描述模式

之前（180 个令牌）：

@mcp.tool()
async def search_items(query: str):
    """Search for items in the database.
    This tool allows comprehensive searching..."""

之后（55 个令牌）：

@mcp.tool(
    annotations={"title": "Search", "readOnlyHint": True, "openWorldHint": False}
)
async def search_items(
    query: Annotated[str, Field(description="Search text")],
    ctx: Context = None
):
    """Search items. Fast full-text search across all fields."""

常见陷阱

❌ 使用 mcpb pack CLI（会导致崩溃，直接使用 zip）
❌ 使用 pip 而非 uv
❌ 使用 web_search 搜索 FastMCP 文档（应对 LLMS_TXT.md 中的 URL 使用 web_fetch）
❌ 工具描述冗长
❌ 缺少工具注释
❌ 仅有 1-3 个工具时使用网关（开销超过收益）
❌ 在单个网关中混合无关能力