Hacktoberfest 2026：メンテナが10月に向けて印を付けた、オープンで初心者向けの issue。 Hacktoberfest の issue を見る

Client.listTools() silently drops pages when a server repeats a cursor

クローズ
  • 何か問題がありますか？
#2,735 コメント 2 件 リアクション 0 件 担当者 0 名 GitHub で見る

メンテナーはふだん 1 日以内に返信

まだ誰も着手していません。

評価

難易度
3/5
見積もり時間
1〜2日
初心者へのやさしさ
74/100
issue の種類
バグ
明瞭さ
明確に書かれている
活発さ
活発
技術スタック
typescript
領域
api

調査の方向性

listTools()、listPrompts()、listResources()、listResourceTemplates() で使用される _listAllPages エントリーポイントから始め、listMaxPages と ListPaginationExceeded がページネーションをどのように制限する想定なのかを確認します。空のカーソルが繰り返される、提供された再現手順を使って、リクエストのシーケンスと集約された結果を検証します。繰り返しまたは循環するカーソルが完全なリストとして黙って報告されず、ページネーション制限による失敗が引き続き可視であれば完了です。

索引モデルが issue の本文から書いたものです。

説明

v2
Version

@modelcontextprotocol/client 2.0.0

Summary

When a server returns the same opaque cursor for more than one page, the auto-aggregating listTools() / listPrompts() / listResources() / listResourceTemplates() path stops early and reports the result as complete. The caller cannot tell that pages are missing.

In _listAllPages:

let cursor = acc.nextCursor;
const seen = new Set();
let pages = 1;
while (cursor !== void 0 && !seen.has(cursor)) {
  ...
}
delete acc.nextCursor;

Two things combine here. The loop exits when a cursor repeats, and then nextCursor is deleted from the aggregate, so the truncated list is indistinguishable from a complete one. No error is thrown and nothing is logged.

Why this is a problem

The 2026-07-28 pagination rules say cursors are opaque:

Don't make any determination based on cursor value other than whether a non-null value was provided (e.g. an empty string is a valid cursor and thus MUST NOT be treated as the end of results)

Comparing two cursors for equality is a determination based on their value. Nothing in the spec requires successive pages to carry different tokens, so a server that keeps its pagination position server side and returns one constant handle for every page is behaving legally, and the client drops everything after page two.

The empty string makes this concrete. It is the spec's own example of a valid cursor, and it is a natural choice for a server whose token carries no information, but a server that returns nextCursor: "" twice gets truncated.

A cursor cycle such as A, B, A truncates the same way.

Repro
import { Client } from "@modelcontextprotocol/client";

const PAGES = [
  { name: "alpha", nextCursor: "" },
  { name: "beta", nextCursor: "" },
  { name: "gamma" }, // last page, no nextCursor
];

let index = 0;
const received = [];

const transport = {
  async start() {},
  async close() {},
  async send(message) {
    if (message.id === undefined || message.id === null) return;
    const reply = (result) =>
      queueMicrotask(() =>
        transport.onmessage?.({ jsonrpc: "2.0", id: message.id, result })
      );

    if (message.method === "initialize") {
      return reply({
        protocolVersion: message.params.protocolVersion,
        capabilities: { tools: {} },
        serverInfo: { name: "repeated-cursor", version: "1.0.0" },
      });
    }
    if (message.method === "tools/list") {
      const cursor = message.params?.cursor;
      received.push(cursor);
      if (cursor === undefined) index = 0;
      const page = PAGES[Math.min(index, PAGES.length - 1)];
      index += 1;
      return reply({
        tools: [{ name: page.name, inputSchema: { type: "object" } }],
        ...(page.nextCursor === undefined ? {} : { nextCursor: page.nextCursor }),
      });
    }
    return reply({});
  },
};

const client = new Client({ name: "repro", version: "1.0.0" });
await client.connect(transport);

const result = await client.listTools();
console.log("requests:  ", JSON.stringify(received));
console.log("tools:     ", result.tools.map((t) => t.name).join(", "));
console.log("nextCursor:", JSON.stringify(result.nextCursor));

Actual:

requests:   [null,""]
tools:      alpha, beta
nextCursor: undefined

Expected: alpha, beta, gamma. The server was still offering a cursor after beta, and the third request is never sent.

Suggested fix

Drop the seen set and let listMaxPages bound the walk. The cap already covers the case the dedupe is aimed at, its own docs describe it as "a defence against a server whose nextCursor never converges", and it does that without reading cursor values. It also fails loudly with ListPaginationExceeded instead of returning a short list that looks complete. A server that wants to spin the client can return distinct cursors forever anyway, so the dedupe only catches the one shape that may well be legitimate.

If the dedupe is worth keeping for some reason, throwing on a repeat rather than returning a truncated aggregate would at least make the truncation visible.

Happy to send a PR if you would like one.

Context

Found while fixing our own client so it treats an empty-string nextCursor as a real cursor. Our code is correct now, but the aggregate walk is below us, so the tool list still comes back short for this kind of server.

主要言語
TypeScript
スター
13.6k
フォーク
2.3k
平均マージ
1日 2時間
マージ済み PR（30日）
51

環境構築

はじめの一歩

  1. issue を最後まで読み、次にプロジェクトのコントリビューションガイドを読みます。
  2. 着手することを issue にコメントします — 二人が同じ作業をするのを防げます。
  3. リポジトリをフォークし、ブランチを切って変更します。
  4. issue 番号を参照したプルリクエストを送ります。

modelcontextprotocol/typescript-sdk のほかの issue

modelcontextprotocol/typescript-sdk の issue をすべて見る

似ている issue

TypeScript の issue をもっと見る

新しい issue をメールで受け取る

初心者向けの GitHub issue を短くまとめたダイジェスト。