5.2 KiB
5.2 KiB
title, type, tags, date, last_updated
| title | type | tags | date | last_updated | ||||
|---|---|---|---|---|---|---|---|---|
| MCP Builder Agent | source |
|
2026-04-20 | 2026-05-29 |
Source File
Summary（用中文描述）
- 核心主题：AI Agent 的 MCP（Model Context Protocol）服务器开发专家——设计、构建、测试和部署 MCP 服务器，为 AI Agent 提供自定义工具、资源和提示词能力
- 问题域：如何让 AI Agent 能够可靠地调用外部工具和 API，同时保持开发者体验（Developer Experience）
- 方法/机制：遵循 MCP SDK 规范（TypeScript/Zod、Python/Pydantic），设计 Agent 友好的工具接口，提供 Resources（资源）、Tools（工具）、Prompts（提示词模板）三种扩展方式，通过真实 Agent 测试验证可用性
- 结论/价值：工具命名和描述是 Agent 能否正确选用的关键；每个工具调用必须独立无状态；错误必须返回结构化消息而非堆栈跟踪
Key Claims（用中文描述）
- 描述性工具命名 → Agent 能从名称推断用途，正确选用率 >90%
- 类型化参数验证（Zod/Pydantic） → 边界层拦截非法输入，防止外部 API 污染
- 结构化错误返回（isError: true） → Agent 知道何时重试或请求用户，而非虚构响应
- 无状态工具设计 → 每次调用独立，不依赖调用顺序，确保分布式环境稳定
- 真实 Agent 测试循环 → 通过完整调用链路验证，而非仅靠单元测试
- 环境变量密钥管理 → API Key 和 Token 从环境变量读取，绝不硬编码
- 单一职责工具原则 →
get_user和update_user是两个工具，不是一个工具加 mode 参数 - 可组合服务器架构 → 拆分为单一用途服务器，通过资源共享上下文，通过代理服务器聚合多后端
Key Quotes
"If an agent can't figure out how to use your tool from the name and description alone, it's not ready to ship." — MCP Builder 核心理念 "A tool that passes unit tests but confuses the agent is broken." — 测试理念，强调必须验证 Agent 的完整调用路径 "We return
isError: truehere so the agent knows to retry or ask the user, instead of hallucinating a response." — 错误处理设计哲学 "Call itsearch_orders_by_datenotquery— the agent needs to know what this does from the name alone." — 命名原则
Key Concepts
- Model Context Protocol (MCP)：Anthropic 提出的 AI Agent 与外部工具/数据源交互的标准化协议
- MCP Server：基于 MCP 协议的服务端实现，暴露 Tools/Resources/Prompts 给 Agent
- Tool Interface Design：为 Agent 设计友好工具接口的实践，关注命名、描述、参数类型和返回结构
- Zod Validation：TypeScript schema 声明和验证库，用于 MCP TypeScript 服务器参数验证
- Pydantic Validation：Python 数据验证库，用于 MCP Python (FastMCP) 服务器参数验证
- Stdio Transport：MCP 标准传输方式，适用于本地 CLI 集成和桌面 Agent
- SSE Transport：Server-Sent Events 传输方式，适用于基于 Web 的 Agent 接口和远程访问
- Streamable HTTP：可扩展云部署的 HTTP 流式传输，支持无状态请求处理
- Stateless Tool Design：无状态工具设计原则，确保每次调用独立、幂等、可分布式运行
- Structured Error Response：返回
isError: true结构化错误消息，而非堆栈跟踪 - Dynamic Tool Registration：服务器启动时从 API Schema 或数据库表动态发现可用工具
- OpenAPI-to-MCP Tool Generation：将现有 REST API 包装为 MCP 工具的自动生成
- Composable Server Architecture：将大型集成拆分为专注单一用途的服务器，通过代理聚合多后端
Key Entities
- @modelcontextprotocol/sdk：Anthropic 官方 MCP TypeScript SDK，提供 McpServer、StdioServerTransport 等核心类
- FastMCP：Python MCP 服务器框架，基于 Pydantic 的类型验证
- Zod：TypeScript schema 声明和验证库，MCP TypeScript SDK 内置支持
- Pydantic：Python 数据验证库，FastMCP 的核心依赖
Connections
- MCP Builder Agent ← implements ← Model Context Protocol (MCP)
- MCP Builder Agent ← uses ← @modelcontextprotocol/sdk
- MCP Builder Agent ← uses ← FastMCP
- LSP/Index Engineer Agent Personality ← shares_tool_design_philosophy_with ← MCP Builder Agent
- Specialized Developer Advocate ← extends ← MCP Builder Agent（MCP 服务器的对外推广和最佳实践传播）
Contradictions
- 与 lsp-index-engineer 存在张力：
- 冲突点：LSP 强调确定性分析（代码结构必须精确），而 MCP 服务器面对外部 API 时存在网络抖动、速率限制等不确定性
- 当前观点：MCP Builder 坚持无状态、幂等、Fail-Gracefully 设计，允许优雅降级
- 对方观点：LSP/Index Engineer 需要确定性结果，任何不确定的外部调用应被隔离和重试
- 协调方案：在 MCP 服务器层面实现重试和熔断机制，结果仍以结构化形式返回给 LSP 层
- 暂无其他已知冲突