56 lines
3.8 KiB
Markdown
56 lines
3.8 KiB
Markdown
---
|
||
title: "MCP Builder Agent"
|
||
type: source
|
||
tags: ["agent-personality", "mcp", "tool-design", "ai-integration"]
|
||
date: 2026-04-20
|
||
---
|
||
|
||
## 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 从环境变量读取，绝不硬编码
|
||
|
||
## 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." — 错误处理设计哲学
|
||
|
||
## 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 页面的冲突
|