> ## Documentation Index
> Fetch the complete documentation index at: https://mcp.transdocs.org/llms.txt
> Use this file to discover all available pages before exploring further.

# 日志记录

<div id="enable-section-numbers" />

<Info>**协议版本**: 草案</Info>

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

## 用户交互模型

实现方可以自由地通过任何适合其需求的接口模式来暴露日志功能——协议本身不强制要求任何特定的用户交互模型。

## 功能能力

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

```json theme={null}
{
  "capabilities": {
    "logging": {}
  }
}
```

## 日志级别

协议遵循 [RFC 5424](https://datatracker.ietf.org/doc/html/rfc5424#section-6.2.1) 中指定的标准 syslog 严重程度级别：

| 级别        | 描述       | 示例使用场景   |
| --------- | -------- | -------- |
| debug     | 详细的调试信息  | 函数进入/退出点 |
| info      | 常规信息性消息  | 操作进度更新   |
| notice    | 正常但重要的事件 | 配置更改     |
| warning   | 警告条件     | 已弃用功能的使用 |
| error     | 错误条件     | 操作失败     |
| critical  | 严重条件     | 系统组件故障   |
| alert     | 需要立即采取行动 | 检测到数据损坏  |
| emergency | 系统不可用    | 完全系统故障   |

## 协议消息

### 设置日志级别

要配置最低日志级别，客户端**可以**发送 `logging/setLevel` 请求：

**请求：**

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "logging/setLevel",
  "params": {
    "level": "info"
  }
}
```

### 日志消息通知

服务器使用 `notifications/message` 通知发送日志消息：

```json theme={null}
{
  "jsonrpc": "2.0",
  "method": "notifications/message",
  "params": {
    "level": "error",
    "logger": "数据库",
    "data": {
      "错误": "连接失败",
      "详情": {
        "主机": "localhost",
        "端口": 5432
      }
    }
  }
}
```

## 消息流程

```mermaid theme={null}
sequenceDiagram
    participant 客户端
    participant 服务器

    Note over 客户端,服务器: 配置日志
    客户端->>服务器: logging/setLevel (info)
    服务器-->>客户端: 空结果

    Note over 客户端,服务器: 服务器活动
    服务器--)客户端: notifications/message (info)
    服务器--)客户端: notifications/message (warning)
    服务器--)客户端: notifications/message (error)

    Note over 客户端,服务器: 级别更改
    客户端->>服务器: logging/setLevel (error)
    服务器-->>客户端: 空结果
    Note over 服务器: 仅发送 error 级别及以上
```

## 错误处理

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

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

## 实现注意事项

1. 服务器**应该**：
   * 限制日志消息的发送频率
   * 在数据字段中包含相关上下文
   * 使用一致的记录器名称
   * 移除敏感信息

2. 客户端**可以**：
   * 在用户界面中显示日志消息
   * 实现日志过滤/搜索
   * 以视觉方式显示严重程度
   * 持久化存储日志消息

## 安全性

1. 日志消息**不得**包含：
   * 凭据或密钥
   * 个人身份信息
   * 可能有助于攻击的内部系统细节

2. 实现方**应该**：
   * 限制消息发送频率
   * 验证所有数据字段
   * 控制日志访问权限
   * 监控敏感内容