规范
规范（草案）
服务器功能
实用工具
日志

日志

ℹ️
协议版本: 草案

模型上下文协议（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: 只发送错误级别
及以上

错误处理

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

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

实施考虑

  1. 服务器应该：

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

  2. 客户端可以：

    • 在 UI 中呈现日志消息
    • 实现日志过滤/搜索
    • 视觉上显示严重性
    • 持久化日志消息

安全

  1. 日志消息不得包含：

    • 凭据或密钥
    • 个人识别信息
    • 可能帮助攻击的内部系统详细信息

  2. 实现应该：

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