Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
142 changes: 142 additions & 0 deletions src/scenarios/client/elicitation-defaults.test.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,142 @@
/**
* Capability gating for `elicitation-sep1034-client-defaults` (issue #584).
*
* Elicitation is an optional client capability at 2025-11-25, split into
* `form` and `url` modes. A client that negotiates without form mode —
* either no `elicitation` or a URL-only declaration — must not be sent the
* form `elicitation/create` request; its checks are SKIPPED, not failed.
* A client that does declare form support, including the backwards-
* compatible bare `elicitation: {}`, is still scored.
*/
import { describe, test, expect, afterEach } from 'vitest';
import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
import type { ConformanceCheck, Scenario } from '../../types';
import { testScenarioContext } from '../../mock-server/testing';
import { getScenario } from '../index';

const SCENARIO_NAME = 'elicitation-sep1034-client-defaults';
const ELICITATION_CHECK_PREFIX = 'client-elicitation-sep1034-';

const DEFAULT_SLUGS = [
'client-elicitation-sep1034-string-default',
'client-elicitation-sep1034-integer-default',
'client-elicitation-sep1034-number-default',
'client-elicitation-sep1034-enum-default',
'client-elicitation-sep1034-boolean-default'
];

let scenario: Scenario | undefined;

afterEach(async () => {
await scenario?.stop();
scenario = undefined;
});

/**
* Drive `runClient` against the scenario in-process, the way the
* everything-client would be spawned against it, and return the checks.
*/
async function runAgainst(
runClient: (serverUrl: string) => Promise<void>
): Promise<ConformanceCheck[]> {
scenario = getScenario(SCENARIO_NAME);
if (!scenario) {
throw new Error(`Scenario not found: ${SCENARIO_NAME}`);
}
const urls = await scenario.start(testScenarioContext());
try {
await runClient(urls.serverUrl);
} finally {
await scenario.stop();
}
return scenario.getChecks();
}

async function runClientWithoutElicitation(serverUrl: string): Promise<void> {
const client = new Client(
{ name: 'no-elicitation-test-client', version: '1.0.0' },
{ capabilities: {} }
);
const transport = new StreamableHTTPClientTransport(new URL(serverUrl));
await client.connect(transport);
await client.callTool({
name: 'test_client_elicitation_defaults',
arguments: {}
});
await transport.close();
}

function makeElicitationRejectingClient(
elicitation: Record<string, unknown>
): (serverUrl: string) => Promise<void> {
// Declares the capability but registers no elicitation handler, so the
// SDK answers `elicitation/create` with a method-not-found error.
return async (serverUrl: string) => {
const client = new Client(
{ name: 'rejecting-elicitation-test-client', version: '1.0.0' },
{ capabilities: { elicitation } }
);
const transport = new StreamableHTTPClientTransport(new URL(serverUrl));
await client.connect(transport);
await client.callTool({
name: 'test_client_elicitation_defaults',
arguments: {}
});
await transport.close();
};
}

describe('elicitation-sep1034-client-defaults capability gating', () => {
test('client without the elicitation capability gets SKIPPED, not FAILURE', async () => {
const checks = await runAgainst(runClientWithoutElicitation);

const scored = checks.filter((c) =>
c.id.startsWith(ELICITATION_CHECK_PREFIX)
);
expect(scored.length).toBe(DEFAULT_SLUGS.length + 1);
expect(scored.every((c) => c.status === 'SKIPPED')).toBe(true);
expect(checks.every((c) => c.status !== 'FAILURE')).toBe(true);
});

test('client with only url-mode elicitation gets SKIPPED', async () => {
// `elicitation: {url: {}}` supports URL mode only; the scenario's form
// request is not applicable.
const checks = await runAgainst(
makeElicitationRejectingClient({ url: {} })
);

const scored = checks.filter((c) =>
c.id.startsWith(ELICITATION_CHECK_PREFIX)
);
expect(scored.length).toBe(DEFAULT_SLUGS.length + 1);
expect(scored.every((c) => c.status === 'SKIPPED')).toBe(true);
expect(checks.every((c) => c.status !== 'FAILURE')).toBe(true);
});

test.each([
{ elicitation: {}, label: 'backwards-compatible elicitation: {}' },
{ elicitation: { form: {} }, label: 'explicit form mode' }
])(
'client declaring $label still receives elicitation/create',
async ({ elicitation }) => {
const checks = await runAgainst(
makeElicitationRejectingClient(elicitation)
);

// The request must actually be delivered: the client declares the
// capability, so a refusal is a real FAILURE and nothing is SKIPPED.
const general = checks.find(
(c) => c.id === 'client-elicitation-sep1034-general'
);
expect(general?.status).toBe('FAILURE');
expect(general?.errorMessage).toContain('Elicitation failed');
expect(
checks.some(
(c) =>
c.id.startsWith(ELICITATION_CHECK_PREFIX) && c.status === 'SKIPPED'
)
).toBe(false);
}
);
});
143 changes: 141 additions & 2 deletions src/scenarios/client/elicitation-defaults.ts
Original file line number Diff line number Diff line change
Expand Up @@ -30,14 +30,72 @@ function isInitializeRequest(body: unknown): boolean {
return false;
}

/**
* Whether the negotiated client capabilities include form-mode elicitation.
*
* At 2025-11-25 `elicitation` already splits into `form` and `url` modes.
* A client declaring `elicitation: {url: {}}` only must not receive this
* scenario's `elicitation/create` form request. A bare `elicitation: {}` is
* backwards-compatible with form mode and is scored normally. Anything
* unreadable or non-object defaults to form-capable so behaviour is
* unchanged for clients that negotiated elicitation normally.
*/
function supportsFormElicitation(elicitation: unknown): boolean {
if (
elicitation === undefined ||
elicitation === null ||
elicitation === false
) {
return false;
}
if (typeof elicitation !== 'object') {
return true;
}
const modes = elicitation as Record<string, unknown>;
return !('url' in modes) || 'form' in modes;
}

const SEP1034_SPEC_REFERENCES = [
{
id: 'SEP-1034',
url: 'https://github.com/modelcontextprotocol/modelcontextprotocol/issues/1034'
}
];

const ELICITATION_NOT_DECLARED_MESSAGE =
'Client did not declare form-mode elicitation capability during initialize; check not applicable';

function skippedElicitationCheck(
id: string,
name: string,
description: string
): ConformanceCheck {
return {
id,
name,
description,
status: 'SKIPPED',
timestamp: new Date().toISOString(),
errorMessage: ELICITATION_NOT_DECLARED_MESSAGE,
specReferences: SEP1034_SPEC_REFERENCES
};
}

function createServer(checks: ConformanceCheck[]): {
app: express.Application;
cleanup: () => void;
elicitationDeclared: () => boolean;
} {
// Session management
const transports: { [sessionId: string]: StreamableHTTPServerTransport } = {};
const servers: { [sessionId: string]: Server } = {};

// Elicitation is an optional client capability; a client that did not
// declare form-mode elicitation is not applicable for this scenario
// rather than failing it. Read from the negotiated capabilities on the
// SDK server, which the transport settles per session at initialize.
let elicitationDeclared = true;

const createMcpServer = () => {
const server = new Server(
{
Expand All @@ -52,6 +110,9 @@ function createServer(checks: ConformanceCheck[]): {
);

server.setRequestHandler(ListToolsRequestSchema, async () => {
elicitationDeclared = supportsFormElicitation(
server.getClientCapabilities()?.elicitation
);
return {
tools: [
{
Expand All @@ -70,6 +131,54 @@ function createServer(checks: ConformanceCheck[]): {

server.setRequestHandler(CallToolRequestSchema, async (request) => {
if (request.params.name === 'test_client_elicitation_defaults') {
elicitationDeclared = supportsFormElicitation(
server.getClientCapabilities()?.elicitation
);
if (!elicitationDeclared) {
// The client negotiated without the optional elicitation
// capability, so it must not receive `elicitation/create` and the
// checks are not applicable rather than failed.
checks.push(
skippedElicitationCheck(
'client-elicitation-sep1034-general',
'ClientElicitationSEP1034General',
'Client handles elicitation with defaults'
),
skippedElicitationCheck(
'client-elicitation-sep1034-string-default',
'ClientElicitationSEP1034StringDefault',
'Client applies string default value for elicitation'
),
skippedElicitationCheck(
'client-elicitation-sep1034-integer-default',
'ClientElicitationSEP1034IntegerDefault',
'Client applies integer default value for elicitation'
),
skippedElicitationCheck(
'client-elicitation-sep1034-number-default',
'ClientElicitationSEP1034NumberDefault',
'Client applies number default value for elicitation'
),
skippedElicitationCheck(
'client-elicitation-sep1034-enum-default',
'ClientElicitationSEP1034EnumDefault',
'Client applies enum default value for elicitation'
),
skippedElicitationCheck(
'client-elicitation-sep1034-boolean-default',
'ClientElicitationSEP1034BooleanDefault',
'Client applies boolean default value for elicitation'
)
);
return {
content: [
{
type: 'text',
text: 'Elicitation capability not declared by client; checks skipped'
}
]
};
}
try {
// Request elicitation with all optional fields having defaults
// Using raw server.request() to verify client applies defaults before sending response
Expand Down Expand Up @@ -470,7 +579,7 @@ function createServer(checks: ConformanceCheck[]): {
}
};

return { app, cleanup };
return { app, cleanup, elicitationDeclared: () => elicitationDeclared };
}

export class ElicitationClientDefaultsScenario implements Scenario {
Expand All @@ -485,12 +594,14 @@ export class ElicitationClientDefaultsScenario implements Scenario {
private httpServer: any = null;
private checks: ConformanceCheck[] = [];
private cleanup: (() => void) | null = null;
private elicitationDeclared: () => boolean = () => true;

async start(_ctx: ScenarioContext): Promise<ScenarioUrls> {
this.checks = [];
const { app, cleanup } = createServer(this.checks);
const { app, cleanup, elicitationDeclared } = createServer(this.checks);
this.app = app;
this.cleanup = cleanup;
this.elicitationDeclared = elicitationDeclared;
this.httpServer = this.app.listen(0);
const port = this.httpServer.address().port;
return { serverUrl: `http://localhost:${port}/mcp` };
Expand All @@ -517,6 +628,34 @@ export class ElicitationClientDefaultsScenario implements Scenario {
'client-elicitation-sep1034-boolean-default'
];

if (!this.elicitationDeclared()) {
// The client never declared the optional elicitation capability: the
// general check plus any untriggered defaults are SKIPPED, not failed.
if (
!this.checks.find((c) => c.id === 'client-elicitation-sep1034-general')
) {
this.checks.push(
skippedElicitationCheck(
'client-elicitation-sep1034-general',
'ClientElicitationSEP1034General',
'Client handles elicitation with defaults'
)
);
}
for (const slug of expectedSlugs) {
if (!this.checks.find((c) => c.id === slug)) {
this.checks.push(
skippedElicitationCheck(
slug,
slug.replace(/-/g, ''),
`Server applies ${slug.split('-')[4]} default for elicitation`
)
);
}
}
return this.checks;
}

// Add failures for any checks that weren't triggered (tool not called)
for (const slug of expectedSlugs) {
if (!this.checks.find((c) => c.id === slug)) {
Expand Down
Loading