Skip to content

Commit fbbfd9f

Browse files
test(e2e): subscriptions/listen cells
Five requirement entries (ack-first stamping, per-stream filtering, capacity guard, listChanged auto-open on modern, the legacy-era steer) with self-hosted createMcpHandler bodies so handler.notify is in scope. The 2025-era steer cell runs on every legacy arm; the four 2026 cells run on entryModern only.
1 parent 2f64ff6 commit fbbfd9f

2 files changed

Lines changed: 180 additions & 0 deletions

File tree

‎test/e2e/requirements.ts‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2667,6 +2667,45 @@ export const REQUIREMENTS: Record<string, Requirement> = {
26672667
'The SDK provides a server-side legacy HTTP+SSE transport so existing SSE deployments can be hosted on SDK components alone.',
26682668
transports: ['sse'],
26692669
note: 'This asserts the availability of the server half of the legacy SSE transport (SSEServerTransport from @modelcontextprotocol/server-legacy/sse); the matrix transport arg is ignored, so it runs as a single sse-labelled cell.'
2670+
},
2671+
'subscriptions:listen:ack-first-stamped': {
2672+
source: 'https://modelcontextprotocol.io/specification/draft/basic/patterns/subscriptions#acknowledgment',
2673+
behavior:
2674+
"notifications/subscriptions/acknowledged is the first message on a subscriptions/listen stream and carries the listen request's JSON-RPC id verbatim under the io.modelcontextprotocol/subscriptionId _meta key, plus the honored subset of the requested filter.",
2675+
addedInSpecVersion: '2026-07-28',
2676+
transports: ['entryModern'],
2677+
note: 'Hosted by the test body via createMcpHandler so it can publish via handler.notify.'
2678+
},
2679+
'subscriptions:listen:per-stream-filter': {
2680+
source: 'https://modelcontextprotocol.io/specification/draft/basic/patterns/subscriptions#notification-filter',
2681+
behavior:
2682+
'A subscriptions/listen stream receives only the notification types its filter explicitly requested; an un-requested type is provably never delivered. Change notifications dispatch to the existing setNotificationHandler registrations.',
2683+
addedInSpecVersion: '2026-07-28',
2684+
transports: ['entryModern'],
2685+
note: 'Hosted by the test body via createMcpHandler so it can publish via handler.notify.'
2686+
},
2687+
'subscriptions:listen:capacity-guard': {
2688+
source: 'sdk',
2689+
behavior:
2690+
"A subscriptions/listen request is refused with -32603 'Subscription limit reached' (in-band on HTTP 200, before the ack) when the configured maxSubscriptions is reached.",
2691+
addedInSpecVersion: '2026-07-28',
2692+
transports: ['entryModern'],
2693+
note: 'Hosted by the test body via createMcpHandler with maxSubscriptions: 1.'
2694+
},
2695+
'typescript:subscriptions:listChanged-auto-open-modern': {
2696+
source: 'sdk',
2697+
behavior:
2698+
'ClientOptions.listChanged auto-opens a subscriptions/listen stream on a modern connection (filter derived from which sub-options were set), so the configured handlers fire on every published change. The auto-opened subscription is exposed for close.',
2699+
addedInSpecVersion: '2026-07-28',
2700+
transports: ['entryModern'],
2701+
note: 'Hosted by the test body via createMcpHandler so it can publish via handler.notify.'
2702+
},
2703+
'typescript:subscriptions:listen:legacy-era-steer': {
2704+
source: 'sdk',
2705+
behavior:
2706+
'On a 2025-era connection, Client.listen() throws a typed MethodNotSupportedByProtocolVersion error steering to resources/subscribe and ClientOptions.listChanged before any wire write (no transparent shim).',
2707+
removedInSpecVersion: '2026-07-28',
2708+
note: 'Runs on the 2025-era arms; the entryModern arm is bound out by the removedInSpecVersion.'
26702709
}
26712710
} satisfies Record<string, Requirement>;
26722711

Lines changed: 141 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,141 @@
1+
/**
2+
* `subscriptions/listen` (SEP-1865, protocol revision 2026-07-28) through the
3+
* public surface: ack-first, subscription-id stamping, per-stream filtering,
4+
* the listChanged auto-open bridge, and the F-12 legacy steer.
5+
*
6+
* The 2026-era cells host `createMcpHandler` themselves (the test publishes
7+
* via `handler.notify.*`); the legacy cell runs on the standard arms.
8+
*/
9+
import { Client, SdkError, SdkErrorCode, StreamableHTTPClientTransport } from '@modelcontextprotocol/client';
10+
import { createMcpHandler, McpServer, SUBSCRIPTION_ID_META_KEY } from '@modelcontextprotocol/server';
11+
import { expect } from 'vitest';
12+
import { z } from 'zod/v4';
13+
14+
import { modernEnvelopeMeta, wire } from '../helpers/index.js';
15+
import { verifies } from '../helpers/verifies.js';
16+
import type { TestArgs } from '../types.js';
17+
18+
function makeServer() {
19+
const server = new McpServer({ name: 'subs-e2e', version: '1' });
20+
server.registerTool('greet', { inputSchema: z.object({}) }, async () => ({ content: [] }));
21+
return server;
22+
}
23+
24+
async function hostListen() {
25+
const handler = createMcpHandler(() => makeServer(), { legacy: 'reject', keepAliveMs: 0 });
26+
const url = new URL('http://in-process/mcp');
27+
const fetch = (u: URL | string, init?: RequestInit) => handler.fetch(new Request(u, init));
28+
const client = new Client({ name: 'subs-e2e-client', version: '1' }, { versionNegotiation: { mode: 'auto' } });
29+
await client.connect(new StreamableHTTPClientTransport(url, { fetch }));
30+
expect(client.getNegotiatedProtocolVersion()).toBe('2026-07-28');
31+
return {
32+
client,
33+
handler,
34+
fetch,
35+
url,
36+
[Symbol.asyncDispose]: () => Promise.all([client.close(), handler.close()]).then(() => {})
37+
};
38+
}
39+
40+
verifies('subscriptions:listen:ack-first-stamped', async () => {
41+
const handler = createMcpHandler(() => makeServer(), { legacy: 'reject', keepAliveMs: 0 });
42+
const response = await handler.fetch(
43+
new Request('http://in-process/mcp', {
44+
method: 'POST',
45+
headers: { 'Content-Type': 'application/json', Accept: 'application/json, text/event-stream' },
46+
body: JSON.stringify({
47+
jsonrpc: '2.0',
48+
id: 'sub-1',
49+
method: 'subscriptions/listen',
50+
params: { _meta: modernEnvelopeMeta(), notifications: { toolsListChanged: true } }
51+
})
52+
})
53+
);
54+
expect(response.headers.get('Content-Type')).toBe('text/event-stream');
55+
const reader = response.body!.getReader();
56+
const { value } = await reader.read();
57+
const frame = new TextDecoder().decode(value);
58+
const ack = JSON.parse(frame.slice(frame.indexOf('data: ') + 6, frame.indexOf('\n\n'))) as {
59+
method: string;
60+
params: { _meta: Record<string, unknown>; notifications: unknown };
61+
};
62+
expect(ack.method).toBe('notifications/subscriptions/acknowledged');
63+
expect(ack.params._meta[SUBSCRIPTION_ID_META_KEY]).toBe('sub-1');
64+
expect(ack.params.notifications).toEqual({ toolsListChanged: true });
65+
await reader.cancel();
66+
await handler.close();
67+
});
68+
69+
verifies('subscriptions:listen:per-stream-filter', async () => {
70+
await using h = await hostListen();
71+
const seen: string[] = [];
72+
h.client.setNotificationHandler('notifications/tools/list_changed', () => void seen.push('tools'));
73+
h.client.setNotificationHandler('notifications/prompts/list_changed', () => void seen.push('prompts'));
74+
const sub = await h.client.listen({ toolsListChanged: true });
75+
h.handler.notify.promptsChanged();
76+
h.handler.notify.toolsChanged();
77+
await new Promise(r => setTimeout(r, 30));
78+
// The un-requested type was provably never delivered.
79+
expect(seen).toEqual(['tools']);
80+
await sub.close();
81+
});
82+
83+
verifies('typescript:subscriptions:listChanged-auto-open-modern', async () => {
84+
const handler = createMcpHandler(() => makeServer(), { legacy: 'reject', keepAliveMs: 0 });
85+
const fetch = (u: URL | string, init?: RequestInit) => handler.fetch(new Request(u, init));
86+
let count = 0;
87+
let done!: () => void;
88+
const finished = new Promise<void>(r => {
89+
done = r;
90+
});
91+
const client = new Client(
92+
{ name: 'subs-e2e-client', version: '1' },
93+
{
94+
versionNegotiation: { mode: 'auto' },
95+
listChanged: { tools: { autoRefresh: false, onChanged: () => (++count >= 1 ? done() : undefined) } }
96+
}
97+
);
98+
await client.connect(new StreamableHTTPClientTransport(new URL('http://in-process/mcp'), { fetch }));
99+
expect(client.autoOpenedSubscription?.honoredFilter).toEqual({ toolsListChanged: true });
100+
handler.notify.toolsChanged();
101+
await finished;
102+
expect(count).toBe(1);
103+
await client.autoOpenedSubscription!.close();
104+
await client.close();
105+
await handler.close();
106+
});
107+
108+
verifies('typescript:subscriptions:listen:legacy-era-steer', async ({ transport }: TestArgs) => {
109+
const client = new Client({ name: 'c', version: '0' });
110+
await using _ = await wire(transport, makeServer, client);
111+
const error = await client.listen({ toolsListChanged: true }).catch(e => e as SdkError);
112+
expect(error).toBeInstanceOf(SdkError);
113+
expect((error as SdkError).code).toBe(SdkErrorCode.MethodNotSupportedByProtocolVersion);
114+
expect((error as SdkError).message).toContain('resources/subscribe');
115+
});
116+
117+
verifies('subscriptions:listen:capacity-guard', async () => {
118+
const handler = createMcpHandler(() => makeServer(), { legacy: 'reject', keepAliveMs: 0, maxSubscriptions: 1 });
119+
const post = (id: number) =>
120+
handler.fetch(
121+
new Request('http://in-process/mcp', {
122+
method: 'POST',
123+
headers: { 'Content-Type': 'application/json', Accept: 'application/json, text/event-stream' },
124+
body: JSON.stringify({
125+
jsonrpc: '2.0',
126+
id,
127+
method: 'subscriptions/listen',
128+
params: { _meta: modernEnvelopeMeta(), notifications: {} }
129+
})
130+
})
131+
);
132+
const first = await post(1);
133+
expect(first.headers.get('Content-Type')).toBe('text/event-stream');
134+
const second = await post(2);
135+
expect(second.headers.get('Content-Type')).toContain('application/json');
136+
const body = (await second.json()) as { error: { code: number; message: string } };
137+
expect(body.error.code).toBe(-32_603);
138+
expect(body.error.message).toBe('Subscription limit reached');
139+
await first.body!.cancel();
140+
await handler.close();
141+
});

0 commit comments

Comments
 (0)