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

# 分页

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

Model Context Protocol (MCP) 支持对可能返回大型结果集的列表操作进行分页。分页允许服务器以较小的数据块分批生成结果，而不是一次性返回全部结果。

当连接到互联网上的外部服务时，分页尤其重要；对于本地集成，它也有助于避免大数据集带来的性能问题。

## 分页模型

MCP 中的分页使用基于不透明游标的方式，而不是编号页。

* **cursor** 是一个不透明字符串令牌，表示结果集中的某个位置
* **页面大小** 由服务器决定，客户端 **MUST NOT** 假定固定页面大小

## 响应格式

当服务器发送包含以下内容的**响应**时，分页开始：

* 当前页结果
* 如果存在更多结果，则包含可选的 `nextCursor` 字段

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": "123",
  "result": {
    "resources": [...],
    "nextCursor": "eyJwYWdlIjogM30="
  }
}
```

## 请求格式

收到游标后，客户端可以通过发出包含该游标的请求来\_继续\_分页：

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": "124",
  "method": "resources/list",
  "params": {
    "cursor": "eyJwYWdlIjogMn0="
  }
}
```

## 分页流程

```mermaid theme={null}
sequenceDiagram
    participant Client
    participant Server

    Client->>Server: List Request (no cursor)
    loop Pagination Loop
      Server-->>Client: Page of results + nextCursor
      Client->>Server: List Request (with cursor)
    end
```

## 支持分页的操作

以下 MCP 操作支持分页：

* `resources/list` - 列出可用资源
* `resources/templates/list` - 列出资源模板
* `prompts/list` - 列出可用提示
* `tools/list` - 列出可用工具

## 实现指南

1. 服务器 **SHOULD**：
   * 提供稳定游标
   * 妥善处理无效游标

2. 客户端 **SHOULD**：
   * 将缺失的 `nextCursor` 视为结果结束
   * 同时支持分页和非分页流程

3. 客户端 **MUST** 将游标视为不透明令牌：
   * 不要假定游标格式
   * 不要尝试解析或修改游标
   * 除判断是否提供了非 null 值之外，不要基于游标值作出任何判断（例如，空字符串是有效游标，因此 **MUST NOT** 被视为结果结束）

## 错误处理

无效游标 **SHOULD** 导致代码为 -32602（Invalid params）的错误。