fix: send an empty-string pagination cursor verbatim on every list adapter (#2220)

An MCP cursor is an opaque string: the spec constrains neither its content
nor its length, so `""` is a `nextCursor` a server may legitimately return
and the client is required to send back verbatim.

`listPrompts`, `listResources`, `listResourceTemplates` and
`listRequestorTasks` built their request params with `cursor ? { cursor } : {}`,
a truthiness check that cannot distinguish "no cursor" from "the cursor is
the empty string". Against a server that paginates with `""` they dropped it
and re-requested page one — a list that silently stops at the first page, or
a walk that loops on it forever. Nothing surfaced an error, because the
request was well-formed; it just asked the wrong question. `listTools` (and
the later `listSkills`) already used `cursor !== undefined`; this brings the
other four into line.

`getReplayableParams` in `protocolReplay.ts` existed partly to mirror the
asymmetry — its `method === "tools/list" || params.cursor !== ""` special
case collapses to `typeof params.cursor === "string"` now that the adapters
agree, and its long comment is updated rather than left describing a state
that no longer exists.

Coverage:

- `inspectorClient-list-cursor.test.ts` asserts the outbound params of all
  five adapters — `""` carried, an absent cursor sending no `cursor` key,
  a non-empty cursor forwarded unchanged. `listTools` is the control.
- `test-servers/configs/empty-cursor-http.json` (`emptyStringCursor`) hands
  out `""` as the cursor for page two, the shape no other fixture produces,
  and `empty-cursor.test.ts` walks all three of its lists end to end.
- Removing the fix from any one adapter fails exactly its two cases.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EN2UfrkQZvtrviMtqURRm4
Signed-off-by: cliffhall <cliff@futurescale.com>
This commit is contained in:
cliffhall 2026-09-06 13:24:27 -04:00
commit 9b35e530fc

View file

@ -0,0 +1,157 @@
import { describe, it, expect, vi } from "vitest";
import { InspectorClient } from "@inspector/core/mcp/inspectorClient.js";
/**
* Unit coverage for the pagination cursor every list adapter — `tools/list`,
* `prompts/list`, `resources/list`, `resources/templates/list`, `tasks/list` —
* puts on the wire (#2220).
*
* An MCP cursor is an **opaque string**: the spec places no constraint on its
* content, so `""` is a `nextCursor` a server may legitimately hand back and
* the client is required to send verbatim. Four adapters used to build their
* params with a truthiness check, which cannot distinguish "no cursor" from
* "the cursor is the empty string" — so they dropped `""` and silently
* re-requested page one. Nothing surfaced an error, because the request was
* well-formed; it just asked the wrong question.
*
* The outbound params are therefore the whole assertion here: what each case
* pins is that `""` survives and that a genuinely absent cursor still sends no
* `cursor` key at all. The SDK client is stubbed rather than connected — the
* decision under test is made entirely in `InspectorClient`.
*/
describe("InspectorClient list cursor handling (#2220)", () => {
/**
* The one SDK call these tests care about. Named rather than inlined so the
* `vi.fn` stub can be typed by it — that is what puts the request shape on
* `request.mock.calls`, so each assertion reads `params` without a cast.
*/
type SdkRequest = (
req: { method: string; params: Record<string, unknown> },
schema: unknown,
) => Promise<unknown>;
interface ClientInternals {
client: { request: SdkRequest } | null;
}
/**
* A structural view onto the private `client` field so a test can stub the
* SDK client without connecting.
*
* The double cast is justified rather than incidental: `InspectorClient`
* declares `client` `private`, so no single `as` relates it to a type that
* exposes it, and there is no public setter — the public path is `connect()`,
* which needs a transport, a live server and a handshake. It is safe because
* the shape asserted is exactly the shape the class declares, so a rename or
* a type change breaks these tests at the first use rather than silently
* passing. The same seam is used by `inspectorClient-skills.test.ts`.
*/
function internals(client: InspectorClient): ClientInternals {
return client as unknown as ClientInternals;
}
function makeClient(): InspectorClient {
return new InspectorClient(
{ type: "stdio", command: "noop", args: [] },
// `environment.transport` is only used on connect(); these tests never
// connect, they stub the SDK client directly.
{ environment: { transport: () => ({}) as never } },
);
}
/**
* Stub the SDK client so `request` resolves with a fixed result.
*
* Typed by {@link SdkRequest} rather than inferred, so `request.mock.calls`
* carries the request shape.
*/
function stubRequest(client: InspectorClient, result: unknown) {
const request = vi.fn<SdkRequest>(async () => result);
internals(client).client = { request };
return request;
}
/**
* The five adapters, each with the method it emits and an empty result of the
* right shape. `listTools` was always correct and is included as the control:
* if the guard it has always used ever regressed, these cases go red too.
*/
const ADAPTERS: {
name: string;
method: string;
result: Record<string, unknown>;
call: (client: InspectorClient, cursor?: string) => Promise<unknown>;
}[] = [
{
name: "listTools",
method: "tools/list",
result: { tools: [] },
call: (client, cursor) => client.listTools(cursor),
},
{
name: "listPrompts",
method: "prompts/list",
result: { prompts: [] },
call: (client, cursor) => client.listPrompts(cursor),
},
{
name: "listResources",
method: "resources/list",
result: { resources: [] },
call: (client, cursor) => client.listResources(cursor),
},
{
name: "listResourceTemplates",
method: "resources/templates/list",
result: { resourceTemplates: [] },
call: (client, cursor) => client.listResourceTemplates(cursor),
},
{
name: "listRequestorTasks",
method: "tasks/list",
result: { tasks: [] },
call: (client, cursor) => client.listRequestorTasks(cursor),
},
];
it.each(ADAPTERS)(
"$name sends an empty-string cursor verbatim",
async ({ method, result, call }) => {
const client = makeClient();
const request = stubRequest(client, result);
await call(client, "");
const sent = request.mock.calls[0][0];
expect(sent.method).toBe(method);
expect(sent.params.cursor).toBe("");
},
);
it.each(ADAPTERS)(
"$name sends no cursor key when there is no cursor",
async ({ method, result, call }) => {
const client = makeClient();
const request = stubRequest(client, result);
await call(client);
const sent = request.mock.calls[0][0];
expect(sent.method).toBe(method);
expect(sent.params).not.toHaveProperty("cursor");
},
);
it.each(ADAPTERS)(
"$name forwards a non-empty cursor unchanged",
async ({ result, call }) => {
const client = makeClient();
const request = stubRequest(client, result);
await call(client, "page-2");
const sent = request.mock.calls[0][0];
expect(sent.params.cursor).toBe("page-2");
},
);
});