Skip to content

fix(mcp): follow tool catalog pagination cursors - #936

Open
rudycelekli wants to merge 2 commits into
Tencent:mainfrom
rudycelekli:fix/mcp-tool-catalog-pagination
Open

rudycelekli wants to merge 2 commits into
Tencent:mainfrom
rudycelekli:fix/mcp-tool-catalog-pagination

Conversation

@rudycelekli

@rudycelekli rudycelekli commented Nov 16, 2026 •

Copy link
Copy Markdown

What changed

Follow nextCursor when listing an MCP tool catalog. Stop on a repeated cursor, and cap the catalog at 100 pages so a server returning endlessly fresh cursors cannot grow memory and issue requests forever. A terminal 100th page remains valid; limit/cursor errors return no partial catalog.

Validation

  • Real HTTP two-page catalog with an opaque cursor passes.
  • Repeated-cursor regression stops after exactly two catalog requests.
  • Fresh-cursor regression fails against the previous head (the bounded test server observes request 101); the fix stops after exactly 100 requests with mcp tools/list exceeded 100 pages.
  • A catalog ending on page 100 succeeds with all 100 tools.
  • All internal/mcpclient package tests, package vet, gofmt and git diff --check pass.

Related changes

Rebased onto main 6f606cf. The rebased session-header fix in #935 and this PR merge automatically in both orders, with identical resulting Git trees. Combined package tests/vet pass. An isolated additional strict-server check verified the negotiated headers on both catalog pages, ID-free initialization notification, opaque cursor round-trip and cancellation during page two. No manual production conflict resolution was needed.

Full platform/frontend build, browser acceptance and the complete platform Go checks were not run for this revision; maintainer-triggered platform CI remains required. Tests use only synthetic loopback HTTP endpoints. Codex assisted with implementation and validation.

@Yanami-2K Yanami-2K left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

跟随 nextCursor 分页是必要的修复,两页目录的测试也成立。但描述里说的 "fail on a repeated cursor so a malformed catalog cannot loop forever" 只做到了一半:

  1. internal/mcpclient/client.go ListToolsContext 的 for 循环:seen 只拦截重复游标。服务端每次都返回一个新游标(实现有 bug 或恶意网关)时,循环不会结束,tools 会一直增长。ListTools() 走的是 context.Background(),没有截止时间兜底。建议加一个页数上限(比如 maxToolPages = 100),超过时返回明确错误,例如 mcp tools/list exceeded %d pages。
  2. seen[next] 这个新增的错误分支没有测试。请在 pagination_test.go 里加一个用例:服务端一直返回同一个游标,断言返回 "repeated its pagination cursor" 错误、且请求次数有限;第 1 条加上页数上限后,也补一个持续返回新游标的用例。

另外,client.go 的 diff 在 listToolsPage 结尾处被截断,我没看到最后的 return 语句。#935 也修改了 ListToolsContext 里构造请求的那段代码(加了 setSessionHeaders),两边一定会有文本冲突,合入顺序上需要协调。

@rudycelekli
rudycelekli force-pushed the fix/mcp-tool-catalog-pagination branch from 34571dc to b6c5934 Compare November 20, 2026 02:40
@rudycelekli

Copy link
Copy Markdown
Author

Addressed both pagination gaps. ListToolsContext now stops after 100 pages even when every cursor is fresh, returns an explicit error, and does not expose a partial catalog. The new HTTP tests cover the repeated-cursor branch (exactly two requests), endlessly fresh cursors (exactly 100 requests), and successful completion on the 100th page. The fresh-cursor case fails on the previous PR head and passes with the bound. All mcpclient tests and package vet pass.

I also rebased this PR and coordinated it with the rebased #935. Actual merges succeed automatically in both orders and produce identical Git trees; the negotiated headers land inside listToolsPage. Combined package tests/vet and a strict two-page stateful endpoint/cancellation check pass. The final return from listToolsPage remains present. Full platform CI has not been run locally and still needs the maintainer gate; the body states that limit.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants