分页 (Pagination)

# 分页 (Pagination) > 控制服务器如何向客户端返回大型组件列表。 当服务器暴露大量工具、资源或提示词时，在单个响应中全部返回可能不切实际。MCP 支持列表操作的分页，允许服务器以可管理的块返回结果，客户端可以增量获取这些结果。 ## 服务器配置 默认情况下，为了向后兼容，FastMCP 服务器会在单个响应中返回所有组件。要启用分页，请在创建服务器时设置 `list_page_size` 参数。该值决定了所有列表操作中每页返回的最大项目数。 python from fastmcp import FastMCP # 启用分页，每页 50 个项目 server = FastMCP("ComponentRegistry", list_page_size=50) # 注册工具 (实际上，这些可能来自数据库或配置) @server.tool def search(query: str) -> str: return f"Results for: {query}" @server.tool def analyze(data: str) -> dict: return {"status": "analyzed", "data": data} # ... 更多工具、资源、提示词 当配置了 `list_page_size` 时，`tools/list`、`resources/list`、`resources/templates/list` 和 `prompts/list` 端点都会对其响应进行分页。每个响应在存在更多结果时都会包含一个 `nextCursor` 字段，客户端使用该字段获取后续页面。 ### 游标格式 根据 MCP 规范，游标是不透明的 base64 编码字符串。客户端应将其视为黑盒，在请求之间原样传递。游标编码了结果集中的偏移量，但这属于可能更改的实现细节。 ## 客户端行为 FastMCP 客户端透明地处理分页。诸如 `list_tools()`、`list_resources()`、`list_resource_templates()` 和 `list_prompts()` 之类的便捷方法会自动获取所有页面并返回完整列表。现有代码无需修改即可继续工作。 python from fastmcp import Client async with Client(server) as client: # 返回所有 200 个工具，自动获取页面 tools = await client.list_tools() print(f"Total tools: {len(tools)}") # 200 ### 手动分页 对于需要增量处理结果的场景（内存受限环境、进度报告或提前终止），请使用带有显式游标处理的 `_mcp` 变体。 python from fastmcp import Client async with Client(server) as client: # 获取第一页 result = await client.list