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 處理在日誌邊界強制執行，不在業務邏輯內部。