04 MCP Server 设计模式

04 MCP Server 设计模式

学习目标

• 理解 mcp-builder 技能中的四阶段开发工作流
• 掌握 Anthropic 定义的 MCP 工具命名规范和安全最佳实践
• 分析双响应格式（JSON + Markdown）的设计决策
• 学习传输选择（stdio vs Streamable HTTP）的判断标准

前置知识

本章涉及 MCP 协议的通用原理，建议先阅读：

• MCP 协议与生态
• 工具调用概念

下文假设你已理解上述概念，直接聚焦 mcp-builder 技能的具体实现。

---

项目实践

四阶段开发工作流

mcp-builder 技能将 MCP Server 的开发分为四个阶段：

工具命名规范

mcp-builder 定义了精确的命名规则：

Python：{service}_mcp（如 slack_mcp） TypeScript：{service}-mcp-server（如 slack-mcp-server）

工具级别命名：

• 格式：{service}_{action}_{resource}
• 示例：slack_send_message、github_create_issue
• 必须使用 snake_case，且必须包含服务前缀（避免多个 MCP 服务器之间的命名冲突）

双响应格式设计

所有数据返回工具都支持两种格式：

格式	用途	特点
JSON (response_format="json")	机器可读	包含所有字段和元数据，一致的字段名和类型
Markdown (response_format="markdown"，通常默认)	人类可读	使用标题、列表、格式化，时间戳转为可读格式

设计洞察：这个双格式决策来自对 Agent 使用模式的观察——有些客户端通过代码执行来组合基本工具（需要 JSON），有些客户端直接使用高层工作流工具（需要 Markdown）。

传输选择判断矩阵

判断标准	stdio	Streamable HTTP
部署	本地	远程
客户端	单客户端	多客户端
复杂度	低	中
实时性	否	是

Anthropic 的推荐：TypeScript 用 Streamable HTTP（远程服务器，无状态 JSON），Python 用 stdio（本地服务器）。

---

问题与规避

工具描述不精确导致误调用

问题：工具描述模糊或与实际功能不匹配，导致 Agent 调用错误的工具。

规避策略：mcp-builder 明确要求”工具描述必须精确且不含糊地描述功能，描述必须精确匹配实际功能”。

stdio 服务器日志污染

问题：stdio 服务器通过 stdout 通信，如果日志也写到 stdout 会破坏协议。

规避策略：stdio 服务器不应将日志写入 stdout（使用 stderr 进行日志记录）。

DNS Rebinding 攻击

问题：本地运行的 Streamable HTTP 服务器可能受到 DNS Rebinding 攻击。

规避策略：mcp-builder 的 mcp_best_practices.md 明确要求：

• 启用 DNS Rebinding 保护
• 验证 Origin 头
• 绑定到 127.0.0.1 而非 0.0.0.0

---

设计取舍

为什么选择 Zod（TypeScript）和 Pydantic（Python）？

优势：强类型 Schema 验证，清晰的错误消息，IDE 支持。 代价：增加依赖。 Anthropic 的选择：TypeScript 是推荐语言（“high-quality SDK support and good compatibility in many execution environments e.g. MCPB”）。

为什么包含评估创建作为第四阶段？

优势：确保每个 MCP Server 都有配套的评估问题，可以通过 10 个复杂、真实的问题来测试 Agent 是否能有效使用该服务器。 代价：增加开发时间。 Anthropic 的立场：评估是”comprehensive testing”的一部分——“功能性测试、集成测试、安全测试、性能测试、错误处理”缺一不可。

---

参考来源

• Anthropic Skills 仓库：skills/mcp-builder/SKILL.md
• MCP Best Practices：skills/mcp-builder/reference/mcp_best_practices.md
• MCP 官方文档：https://modelcontextprotocol.io/specification