日志记录#

模型上下文协议（MCP）为服务器提供了一种标准化的方式，向客户端发送结构化日志消息。客户端可以通过设置最低日志级别来控制日志的详细程度，服务器发送包含严重性级别、可选日志记录器名称和任意 JSON 可序列化数据的通知。

用户交互模型#

实现可以自由选择适合其需求的任何界面模式来暴露日志记录功能——协议本身不强制要求特定的用户交互模型。

能力#

发送日志消息通知的服务器 必须 声明 logging 能力：

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

日志级别#

协议遵循 RFC 5424 中指定的标准 syslog 严重性级别：

协议消息#

设置日志级别#

要配置最低日志级别，客户端 可以 发送 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
    participant Server

    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: 仅发送 error 级别<br/>及以上

错误处理#

服务器 应该 为常见失败情况返回标准的 JSON-RPC 错误：

• 无效日志级别：-32602（无效参数）
• 配置错误：-32603（内部错误）

实现注意事项#

1. 服务器 应该：

   • 对日志消息进行速率限制
   • 在数据字段中包含相关上下文
   • 使用一致的日志记录器名称
   • 删除敏感信息

2. 客户端 可以：

   • 在用户界面中呈现日志消息
   • 实现日志过滤/搜索
   • 以视觉方式显示严重性
   • 持久化日志消息

安全#

1. 日志消息 不得 包含：

   • 凭据或密钥
   • 个人身份信息
   • 可协助攻击的内部系统细节

2. 实现 应该：

   • 对消息进行速率限制
   • 验证所有数据字段
   • 控制日志访问
   • 监控敏感内容