[Bug][mcp-resources][0.2.1-alpha.2] list_mcp_resources never returns nextCursor and fails on servers with more than 64 pages

[heaven999b]

中文摘要：list_mcp_resources / list_mcp_resource_templates 不带 cursor 时走 SDK 全量聚合，nextCursor 被删掉、超过 64 页直接报 "pagination did not terminate"；修复为每次调用只请求一页并原样返回服务器的 nextCursor。

Summary

The shared model tools list_mcp_resources and list_mcp_resource_templates cannot page through an MCP server's resources:

• Called without cursor (the only way the model can start), the tool returns the SDK's merged listing of every page with nextCursor removed. The model therefore never receives a cursor, and the documented cursor argument has nothing to continue from.
• When a well-behaved server's pagination terminates after more than 64 pages, the call fails with resources/list: exceeded listMaxPages (64); server pagination did not terminate, even though the server's pagination did terminate. The model has no cursor to resume from, so the listing is unreachable.

This contradicts the package contract: mcp-resources README L38 says "An explicit cursor requests that page; pass a returned nextCursor unchanged", and L104 says "continuation cursors remain visible".

Environment

• dsh 0.2.1-alpha.2, source checkout at d743267388 (current master)
• @modelcontextprotocol/client 2.0.0 (the pinned SDK)
• macOS 14.4.1 arm64, Node v24.11.1
• Reproduces in a fresh session with any MCP server that paginates resources/list or resources/templates/list.

Reproduction

Add this case to packages/mcp/mcp-client/tests/protocol.spec.ts (it reuses that file's connect() helper, which wires a real McpServer to the connection supervisor and mounts dsh-mcp-resources):

it('lists one page per call and returns each continuation cursor', async () => {
  const pages = 65 // one more than the SDK's default listMaxPages
  const server = new McpServer({ name: 'paged', version: '1' })
  server.registerResource('memo', 'memo://readme', {}, async () => ({ contents: [] }))
  server.server.setRequestHandler('resources/list', async (request) => {
    const page = request.params?.cursor === undefined ? 1 : Number(request.params.cursor)
    return {
      resources: [{ name: `r${page}`, uri: `memo://${page}` }],
      ...page < pages ? { nextCursor: String(page + 1) } : {},
    }
  })
  const ctx = await connect(server, { resources: true })
  const result = await ctx.tools.execute({
    name: 'list_mcp_resources', arguments: { server: 'fixture' },
    callId: ToolCallId('list'), signal: new AbortController().signal,
  })
  expect(result).toMatchObject({ isError: false, value: { nextCursor: '2' } })
})

pnpm exec vitest run packages/mcp/mcp-client/tests/protocol.spec.ts

On d743267388 the call fails with:

resources/list: exceeded listMaxPages (64); server pagination did not terminate

With pages = 3 the call succeeds, but returns all 30 resources merged with no nextCursor; the server sees cursors [undefined, '2', '3'] from a single tool call.

Root cause

connection.ts L371-L379 forwards a cursor-less request to Client.listResources(undefined) / Client.listResourceTemplates(undefined):

case 'resources/list':
  return await generation.listResources(
    request.cursor === undefined ? undefined : { cursor: request.cursor }, options,
  ) as JsonValue

In @modelcontextprotocol/client 2.0.0, a list*() call without cursor is the auto-aggregate path (Client._listAllPages): it requests every page, appends them into page 1, executes delete acc.nextCursor, and throws SdkErrorCode.ListPaginationExceeded once it has fetched listMaxPages pages (DEFAULT_LIST_MAX_PAGES = 64). Only an explicit { cursor } takes the SDK's single-page path. That aggregation is right for tool discovery, which needs the complete list (the 64-page cap is the #5905 guard), but the model-facing resource tools need one page plus its cursor.

Fix

Branch: heaven999b/deepseek-harness@fix/mcp-resources-pagination (compare with master) (one commit, fix(mcp): list one resource page per model call).

• packages/mcp/mcp-client/src/connection.ts: both listing methods send exactly one resources/list or resources/templates/list request through Client.request(), forwarding the caller's cursor, and return the server's page unchanged, including nextCursor. A server that does not advertise the resources capability still gets { resources: [] } / { resourceTemplates: [] }, matching the SDK list methods. That keeps the existing "resource tools stay available for a tools-only server" behavior. resources/read and tool discovery are unchanged.
• packages/mcp/mcp-client/tests/protocol.spec.ts: a regression test against a real SDK server with 65 pages for both tools. The first call issues one request and returns page 1 with nextCursor: '2'; following each cursor reaches the last page.
• packages/mcp/mcp-resources/README.md / README.zh.md (+ i18n record): document one page per call, and drop the "pagination follows the MCP SDK" wording.

Verification

• New test fails on d743267388 with resources/list: exceeded listMaxPages (64); server pagination did not terminate and passes with the fix.
• vitest run packages/mcp/mcp-client/tests packages/mcp/mcp-resources/tests --coverage --coverage.include='packages/mcp/mcp-client/src/**/*.ts' --coverage.include='packages/mcp/mcp-resources/src/**/*.ts': 10 files, 147 tests passed; every src file at 100% statements/branches/functions/lines.
• tsc -b packages/mcp/mcp-client/tsconfig.json and tsc -b tsconfig.host.json (includes the specs): clean.
• Staged oxlint and translation-pairing hooks pass. verify-md-wrap passes.
• The shipped mcp-resources snapshot fixture server returns a single page, so its recorded tool results are byte-identical under both code paths. A keyless replay was not run locally because it needs built lib/ artifacts.

Related

• [Bug] A misbehaving MCP server can hang the app forever while listing its tools #5905: origin of the SDK listMaxPages cap for tool discovery. That path is unchanged.
• [Bug][MCP] Repeated nextCursor can make tools/list synchronization loop indefinitely #3660 / [可用性问题] MCP tools/list 返回重复游标时会导致同步无限循环 #2285: repeated-cursor handling for tool discovery.
• MCP 客户端只投影 tools，不建模 resources —— resource-only 的上下文在 DSH 里读不到 #6535: request that led to the shared resource tools.

[PerryLink]

分叉点、SDK 行为、64 页上限我都从 npm tarball 逐行核过了，都成立。但你的 Summary 把两件事并列成两个 bug，其中一件严格来说不是 bug —— 这条会被 maintainer 挑，建议先改准。

1. 分叉点确实在 connection.ts

packages/mcp/mcp-client/src/connection.ts:372-375：

case 'resources/list': return await generation.listResources(request.cursor === undefined ? undefined : { cursor: request.cursor }, options) as JsonValue

（options = { signal: exec.signal, timeout: config.toolCallTimeoutMs }，:370）:376-379 是同样形状的 listResourceTemplates。

⇒ 不传 cursor 与传 cursor 走的是 SDK 里两条完全不同的实现，你这条读对了。工具侧 packages/mcp/mcp-resources/src/tools.ts:15-18 的参数与 :38-40/:47-49 的转发也对得上。

2. ⚠️ 需要改准的地方：小服务器不算错

SDK @modelcontextprotocol/client@2.0.0（pnpm-lock.yaml:10238-10240 锁 2.0.0，我已下载 tarball 核对）：

• dist/index.mjs:3590-3601 → 无 cursor 时走 this._listAllPages("resources/list", …, (acc, page) => acc.resources.push(...page.resources))；显式 { cursor } 才走单页 this.request(...)
• :3657-3677 → delete acc.nextCursor 与 if (pages >= this._listMaxPages) throw new SdkError(SdkErrorCode.ListPaginationExceeded, …)
• :2904 → const DEFAULT_LIST_MAX_PAGES = 64;

⇒ 所以准确的说法是：

无 cursor 时 SDK 已经把全部页合并返回了，因此"拿不到游标"本身不构成故障（对无 cursor 调用来说，游标并不必要）；
真正的硬失败是 >64 页 —— 此时连合并都拿不到（直接抛错），而模型手里又没有游标可以从第 64 页之后续读，彻底不可用。

你 Repro 段其实写了这个（"With pages = 3 … returns all 30 resources merged with no nextCursor"），但 Summary 把两者并列，读起来像"分页能力丢失"。建议 Summary 改成"大服务器硬失败；小服务器只是丢失增量续读能力并浪费 token" —— 这样诉求更聚焦，也更难被反驳。

3. 契约自相矛盾这条成立，可以放心引用

• packages/mcp/mcp-resources/README.md:38（你引的逐字命中）："Without a cursor, the MCP SDK collects the server's pages. An explicit cursor requests that page; pass a returned nextCursor unchanged."
• packages/mcp/mcp-resources/README.md:104（你引的逐字命中）："Server-provided text, metadata, and continuation cursors remain visible."

⇒ 后一句对有 cursor 的调用为真、对无 cursor 的调用为假。这是你这篇报告里最有力的一条论据（文档自相矛盾），建议提到显眼位置。

另外输出路径确认：packages/mcp/mcp-resources/src/render.ts:16-23 对 canonical value 做 JSON.stringify ⇒ canonical 里没有 nextCursor，模型就永远看不到。

4. ⭐ 仓库内已有证据把这个上限钉死了

这一点比只引 SDK 更有说服力 —— dsh 自己的 e2e 夹具：

• apps/cli/tests/profiles/headless/tests/expected/mcp-pagination/stderr-cause.txt:1 → SdkError: tools/list: exceeded listMaxPages (64); server pagination did not terminate
• apps/cli/tests/profiles/headless/tests/mcp-pagination.expected.e2e.ts:36 → const cause = stderr.split('\n').find(line => line.includes('exceeded listMaxPages'))
• 夹具服务器 packages/mcp/mcp-client/tests/fixtures/pagination-limit-server.ts:12 → return { tools: [], nextCursor: String(++requests) }

⇒ 说明维护者知道这个上限存在（至少在 tools/list 上测过），但没有把 resources/list 的聚合行为纳入同一考量。建议引用这组夹具 —— 它把"这是已知机制、只是没覆盖资源路径"讲清楚了。

你说 tools.ts:123 的 await client.listTools(undefined, { cacheMode: 'refresh' }) 也走聚合、因此工具发现同样受 64 页约束 —— 这一点也对。

5. 修复只需碰 connection.ts 一处

两个 list 方法改成直接发一次 Client.request({ method: 'resources/list' | 'resources/templates/list', params: cursor === undefined ? {} : { cursor } }) 并原样返回（含 nextCursor）；服务器未声明 resources 能力时仍返回空列表（对应 SDK :3591-3593/:3616-3618 的语义，保住"tools-only 服务器上资源工具仍可用"）。resources/read 与工具发现不动。

⚠️ 必须向 maintainer 提示的副作用：改后 list_mcp_resources 的返回体积从"全部页"变成"一页"，对既有小服务器是可感知的行为变化（省 token，但模型需多轮调用才能列全）。这属于契约变更，PR 描述里要点明。

README 也需同步：:38 那句改后即失效；:104 那句改后才真正成立。

6. 一条我没能核实、建议你别写的

你把 64 页上限的来历归于 Discussion #5905。我没有抓取该帖，无法核实这个归因 —— 建议报告里去掉它，或标为"未核实"。可核实的是上面第 2、4 节那些代码与夹具事实，够用了。

另外你提到的分支（heaven999b:fix/...）我也未核实，所以这条回答只针对 origin/master 上的缺陷与最小修复。

7. 版本与 workaround

git rev-list --count d743267388..origin/master = 0 ⇒ 你标的就是当前 origin/master，不存在过期问题。

Workaround（无需改码）：模型侧显式传 cursor —— 但它必须先有一个游标，所以现实中只能靠服务器端把 resources/list 的页大小调大（或干脆不分页）来绕过 64 页上限；或改用 read_mcp_resource 走已知 URI。