69 lines
5.2 KiB
Markdown
69 lines
5.2 KiB
Markdown
---
|
||
title: "MCP Builder Agent"
|
||
type: source
|
||
tags: ["agent-personality", "mcp", "tool-design", "ai-integration"]
|
||
date: 2026-04-20
|
||
last_updated: 2026-05-29
|
||
---
|
||
|
||
## Source File
|
||
- [[raw/Agent/agency-agents/specialized/specialized-mcp-builder.md]]
|
||
|
||
## 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: true` here so the agent knows to retry or ask the user, instead of hallucinating a response." — 错误处理设计哲学
|
||
> "Call it `search_orders_by_date` not `query` — 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 层
|
||
- 暂无其他已知冲突
|