MCP 模块代码标准

为什么代码标准很重要

我们交付的每个连接器都长得一样。这不是巧合——这是纪律。当第二个集成到来时，智能体的能力更容易测试、审计和替换，因为每个 MCP 模块都遵循相同的结构、命名和错误契约。

本文档定义了 IdeaBosque 编排主干中所有 MCP 模块的标准。涵盖目录布局、工具注册、输入输出 schema、错误处理、速率限制、审计日志和 PII 边界处理。

目录结构

每个 MCP 模块都位于 app/mcp_modules/ 下自己的目录中，布局一致：

app/mcp_modules/<slug>/
  __init__.py
  module.py          # 工具注册 + handler
  schemas.py         # 输入输出 Pydantic 模型
  tests/
    test_module.py
  README.md

工具注册

每个模块通过标准接口注册其工具。编排主干通过扫描 register_tools() 入口点来发现工具——无需手动接线。

def register_tools(registrar):
    """注册本模块提供的所有工具。"""
    registrar.tool(
        name="search_catalog",
        description="按 SKU 或名称搜索供应商目录",
        input_schema=SearchCatalogInput,
        output_schema=SearchCatalogOutput,
        rate_limit=120,  # 每分钟调用数
    )

错误处理

模块必须抛出类型化异常，而不是裸字符串。主干捕获 MCPToolError 子类并将其转换为智能体可推理的结构化响应：

• MCPAuthError — 凭据缺失或过期
• MCPRateLimitError — 触及上游速率限制
• MCPTimeoutError — 上游调用超过配置的超时
• MCPValidationError — 输入未通过 schema 校验
• MCPUpstreamError — 上游返回错误状态

速率限制

每个工具在注册调用中声明自己的速率限制。主干按智能体、按工具、按窗口执行这些限制。当达到限制时，智能体收到一个带 Retry-After 头的 429 响应——它不会崩溃或盲目重试。

审计日志

每次工具调用都记录：时间戳、智能体 ID、工具名、输入哈希（不是原始输入——PII 边界）、输出状态、时长和上游系统。日志以结构化 JSON 写入并推送到可观测性管道。

"每次工具调用都被记录且可审计"不是我们后来才加的功能。它是标准要求的第一件事。

PII 边界处理

模块必须声明哪些输入字段包含 PII。主干在记录前对这些字段做哈希，绝不把原始 PII 发到审计管道。PII 字段在 schema 中标记：

class SearchCatalogInput(BaseModel):
    sku: str
    customer_name: str = Field(..., pii=True)
    region: str

当设置 pii=True 时，审计日志器把值替换为 SHA-256 哈希。工具 handler 仍然接收原始值——PII 处理在日志边界强制执行，不在业务逻辑内部。