3.8 KiB
3.8 KiB
title, type, tags, date
| title | type | tags | date | ||||
|---|---|---|---|---|---|---|---|
| MCP Builder Agent | source |
|
2026-04-20 |
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 从环境变量读取，绝不硬编码
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." — 错误处理设计哲学
Key Concepts
- Model Context Protocol (MCP)：Anthropic 提出的 AI Agent 与外部工具/数据源交互的标准化协议
- MCP Server：基于 MCP 协议的服务端实现，暴露 Tools/Resources/Prompts 给 Agent
- Tool Interface Design：为 Agent 设计友好工具接口的实践，关注命名、描述、参数类型和返回结构
- Zod Validation：TypeScript 端的参数模式定义和验证库，用于 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结构化错误消息，而非堆栈跟踪
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
Contradictions
- 暂无发现与其他 Wiki 页面的冲突