規範
規範（草案）
服務器功能
實用工具
日誌

日誌

協議版本: 草案

模型上下文協議（MCP）為服務器提供了一種標準化的方式向客戶端發送結構化日誌消息。客戶端可以通過設置最低日誌級別來控制日誌詳細程度，服務器發送包含嚴重性級別、可選的記錄器名稱和任意 JSON 可序列化數據的通知。

用戶交互模型

實現可以通過任何適合其需求的界面模式公開日誌記錄——協議本身不強制任何特定的用戶交互模型。

能力

發出日誌消息通知的服務器必須聲明 logging 能力：

{
  "capabilities": {
    "logging": {}
  }
}

日誌級別

該協議遵循 RFC 5424 中指定的標準 syslog 嚴重性級別：

級別描述用例示例
debug詳細的調試信息函數進入/退出點
info一般信息性消息操作進度更新
notice正常但重要的事件配置更改
warning警告條件已棄用功能使用
error錯誤條件操作失敗
critical嚴重條件系統組件故障
alert必須立即採取行動檢測到數據損壞
emergency系統不可用完全系統故障

協議消息

設置日誌級別

要配置最低日誌級別，客戶端可以發送 logging/setLevel 請求：

請求：

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "logging/setLevel",
  "params": {
    "level": "info"
  }
}

日誌消息通知

服務器使用 notifications/message 通知發送日誌消息：

{
  "jsonrpc": "2.0",
  "method": "notifications/message",
  "params": {
    "level": "error",
    "logger": "database",
    "data": {
      "error": "連接失敗",
      "details": {
        "host": "localhost",
        "port": 5432
      }
    }
  }
}

消息流 

  sequenceDiagram
    participant Client as 客戶端
    participant Server as 服務器

    Note over Client,Server: 配置日誌
    Client->>Server: logging/setLevel (info)
    Server-->>Client: 空結果

    Note over Client,Server: 服務器活動
    Server--)Client: notifications/message (info)
    Server--)Client: notifications/message (warning)
    Server--)Client: notifications/message (error)

    Note over Client,Server: 級別變更
    Client->>Server: logging/setLevel (error)
    Server-->>Client: 空結果
    Note over Server: 只發送錯誤級別<br/>及以上

錯誤處理

服務器應該為常見故障情況返回標準 JSON-RPC 錯誤：

  • 無效日誌級別：-32602（無效參數）
  • 配置錯誤：-32603（內部錯誤）

實施考慮

  1. 服務器應該：

    • 限制日誌消息速率
    • 在數據字段中包含相關上下文
    • 使用一致的記錄器名稱
    • 移除敏感信息

  2. 客戶端可以：

    • 在 UI 中呈現日誌消息
    • 實現日誌過濾/搜索
    • 視覺上顯示嚴重性
    • 持久化日誌消息

安全

  1. 日誌消息不得包含：

    • 憑據或密鑰
    • 個人識別信息
    • 可能幫助攻擊的內部系統詳細信息

  2. 實現應該：

    • 限制消息速率
    • 驗證所有數據字段
    • 控制日誌訪問
    • 監控敏感內容
分頁補全