Update nexus wiki content

wiki/sources/specialized-mcp-builder.md

@@ -3,6 +3,7 @@ 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
@@ -21,23 +22,29 @@ date: 2026-04-20
 - **无状态工具设计** → 每次调用独立，不依赖调用顺序，确保分布式环境稳定
 - **真实 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 端的参数模式定义和验证库，用于 MCP TypeScript 服务器
-- [[Pydantic Validation]]：Python 端的参数模式定义和验证库，用于 MCP Python (FastMCP) 服务器
+- [[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 等核心类
@@ -50,6 +57,12 @@ date: 2026-04-20
 - [[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
-- 暂无发现与其他 Wiki 页面的冲突
+- 与 [[lsp-index-engineer]] 存在张力：
+  - 冲突点：LSP 强调确定性分析（代码结构必须精确），而 MCP 服务器面对外部 API 时存在网络抖动、速率限制等不确定性
+  - 当前观点：MCP Builder 坚持无状态、幂等、Fail-Gracefully 设计，允许优雅降级
+  - 对方观点：LSP/Index Engineer 需要确定性结果，任何不确定的外部调用应被隔离和重试
+  - 协调方案：在 MCP 服务器层面实现重试和熔断机制，结果仍以结构化形式返回给 LSP 层
+- 暂无其他已知冲突