Hacktoberfest 2026: los issues que los mantenedores marcaron para octubre, abiertos y aptos para principiantes. Explorar issues de Hacktoberfest

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

Cerrado
  • ¿Algo no está bien?
#2,735 2 comentarios 0 reacciones 0 asignados Ver en GitHub

Los mantenedores suelen responder en 1 día

Nadie ha tomado este issue todavía.

Evaluación

Dificultad
3/5
Tiempo estimado
1-2 días
Aptitud para principiantes
74/100
Tipo de issue
Error
Claridad
Bien especificado
Estado de actividad
Activo
Stack tecnológico
typescript
Área
api

Línea de trabajo

Comienza en el punto de entrada _listAllPages utilizado por listTools(), listPrompts(), listResources() y listResourceTemplates(), y luego inspecciona cómo se supone que listMaxPages y ListPaginationExceeded deben limitar la paginación. Usa la reproducción proporcionada con un cursor vacío repetido para verificar la secuencia de solicitudes y los resultados agregados. Se considera terminado cuando un cursor repetido o cíclico no se informa silenciosamente como una lista completa y los fallos por el límite de paginación siguen siendo visibles.

Escrito por el modelo de indexación a partir del texto del issue.

Descripción

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.

Lenguaje dominante
TypeScript
Estrellas
13.6k
Forks
2.5k
Merge medio
1 d 2 h
PR fusionados (30 d)
51

Preparar el entorno

Primeros pasos

  1. Lee el issue completo y luego la guía de contribución del proyecto.
  2. Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
  3. Haz un fork del repositorio y trabaja en una rama.
  4. Abre un pull request que haga referencia al número del issue.

Más de modelcontextprotocol/typescript-sdk

Todos los issues de modelcontextprotocol/typescript-sdk

Issues similares

Más issues de TypeScript

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.