Skip to content

Commit 6bed4c5

Browse files
cliffhallclaude
andcommitted
fix(everything): gate trigger-elicitation-request on form-mode elicitation
trigger-elicitation-request sends a form-mode elicitation, but it was registered whenever the client declared `elicitation` at all, so a client that declared only URL mode saw the tool and every call failed. Register it only when the client declared `elicitation.form`, or an `elicitation` object with neither mode (form mode, per the spec's backwards-compatibility rule), the same test the SDK client applies (#4985). Flip the KNOWN BUG pins for #4792 and #4985 to the correct behavior, update the instructions' gated-tools table and features.md for the form requirement, and adapt the tests ported from #4835 to the file's static imports and typed mocks. Co-Authored-By: Claude Opus 5.5 <[email protected]> Signed-off-by: cliffhall <[email protected]>
1 parent da7f05d commit 6bed4c5

7 files changed

Lines changed: 94 additions & 68 deletions

File tree

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
"@modelcontextprotocol/server-everything": patch
3+
---
4+
5+
Server instructions no longer tell every client to use tools that are registered only for clients declaring a capability; they list those tools and the capability each needs (#4792, ported from #4835). `trigger-elicitation-request` is now registered only for clients that support form-mode elicitation, so a client that declared only URL-mode elicitation no longer sees a tool it cannot answer (#4985).

‎src/everything/__tests__/registrations.test.ts‎

Lines changed: 32 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -58,7 +58,7 @@ describe("Registration Index Files", () => {
5858
server: {
5959
getClientCapabilities: vi.fn(() => ({
6060
roots: {},
61-
elicitation: { url: {} },
61+
elicitation: { form: {}, url: {} },
6262
sampling: {},
6363
})),
6464
},
@@ -149,7 +149,7 @@ describe("Registration Index Files", () => {
149149
});
150150
});
151151

152-
describe('instructions vs. capability-gated tools', () => {
152+
describe("instructions vs. capability-gated tools", () => {
153153
// The instructions are read once in the server factory and handed to the
154154
// McpServer constructor, before `oninitialized` runs and client capabilities
155155
// are known. They are therefore the same string for every client, while the
@@ -161,7 +161,7 @@ describe("Registration Index Files", () => {
161161
const allCapabilities = {
162162
roots: {},
163163
sampling: {},
164-
elicitation: { url: {} },
164+
elicitation: { form: {}, url: {} },
165165
tasks: {
166166
requests: {
167167
sampling: { createMessage: {} },
@@ -170,8 +170,7 @@ describe("Registration Index Files", () => {
170170
},
171171
};
172172

173-
const registeredWith = async (capabilities: object): Promise<string[]> => {
174-
const { registerConditionalTools } = await import('../tools/index.js');
173+
const registeredWith = (capabilities: object): string[] => {
175174
const mockServer = {
176175
registerTool: vi.fn(),
177176
server: {
@@ -186,60 +185,65 @@ describe("Registration Index Files", () => {
186185

187186
registerConditionalTools(mockServer);
188187

189-
const viaRegisterTool = (mockServer.registerTool as any).mock.calls.map(
190-
(call: any[]) => call[0]
191-
);
192-
const viaRegisterToolTask = (
193-
mockServer.experimental.tasks.registerToolTask as any
194-
).mock.calls.map((call: any[]) => call[0]);
188+
const viaRegisterTool = vi
189+
.mocked(mockServer.registerTool)
190+
.mock.calls.map((call) => call[0]);
191+
const viaRegisterToolTask = vi
192+
.mocked(mockServer.experimental.tasks.registerToolTask)
193+
.mock.calls.map((call) => call[0]);
195194
return [...viaRegisterTool, ...viaRegisterToolTask];
196195
};
197196

198197
// A tool is capability-gated if declaring the capabilities makes it appear.
199198
// Deriving it as a difference rather than hard-coding a list means a tool
200199
// that stops being gated drops out of these assertions on its own.
201-
const gatedTools = async (): Promise<string[]> => {
202-
const withAll = await registeredWith(allCapabilities);
203-
const withNone = await registeredWith({});
200+
const gatedTools = (): string[] => {
201+
const withAll = registeredWith(allCapabilities);
202+
const withNone = registeredWith({});
204203
return withAll.filter((name) => !withNone.includes(name)).sort();
205204
};
206205

207206
// The rows of the "Capability-Gated Tools" table, by tool name.
208207
const documentedTools = (instructions: string): string[] => {
209208
const section = instructions
210209
.split(/^## /m)
211-
.find((part) => part.startsWith('Capability-Gated Tools'));
212-
expect(section, 'instructions.md has no "Capability-Gated Tools" section').toBeDefined();
213-
return [...section!.matchAll(/^\|\s*`([a-z0-9-]+)`\s*\|/gm)]
210+
.find((part) => part.startsWith("Capability-Gated Tools"));
211+
expect(
212+
section,
213+
'instructions.md has no "Capability-Gated Tools" section',
214+
).toBeDefined();
215+
return [...(section ?? "").matchAll(/^\|\s*`([a-z0-9-]+)`\s*\|/gm)]
214216
.map((match) => match[1])
215217
.sort();
216218
};
217219

218-
it('documents exactly the tools that client capabilities gate', async () => {
219-
const { readInstructions } = await import('../resources/index.js');
220-
220+
it("documents exactly the tools that client capabilities gate", () => {
221221
// A tool registered only when a capability is declared is absent from
222222
// tools/list for every other client, so an agent told to use it has
223223
// nothing to call. The instructions must name the same set the gates do.
224-
expect(documentedTools(readInstructions())).toEqual(await gatedTools());
224+
expect(documentedTools(readInstructions())).toEqual(gatedTools());
225225
});
226226

227-
it('never tells an agent to use a capability-gated tool unconditionally', async () => {
228-
const { readInstructions } = await import('../resources/index.js');
227+
it("never tells an agent to use a capability-gated tool unconditionally", () => {
229228
const instructions = readInstructions();
230-
const gated = await gatedTools();
229+
const gated = gatedTools();
231230

232231
// Lines in the gated section are already qualified by the section itself.
233232
const sections = instructions.split(/^## /m);
234233
const otherLines = sections
235-
.filter((part) => !part.startsWith('Capability-Gated Tools'))
236-
.flatMap((part) => part.split('\n'));
234+
.filter((part) => !part.startsWith("Capability-Gated Tools"))
235+
.flatMap((part) => part.split("\n"));
237236

238237
const unconditional = otherLines.filter(
239-
(line) => gated.some((name) => line.includes(`\`${name}\``)) && !/\bif\b/i.test(line)
238+
(line) =>
239+
gated.some((name) => line.includes(`\`${name}\``)) &&
240+
!/\bif\b/i.test(line),
240241
);
241242

242-
expect(unconditional, 'mention a gated tool without saying it may be absent').toEqual([]);
243+
expect(
244+
unconditional,
245+
"mention a gated tool without saying it may be absent",
246+
).toEqual([]);
243247
});
244248
});
245249

‎src/everything/__tests__/sampling-elicitation.test.ts‎

Lines changed: 11 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -388,27 +388,18 @@ describe("trigger-elicitation-request", () => {
388388
expect(texts[0]).toBe("⚠️ User cancelled the elicitation dialog.");
389389
});
390390

391-
// KNOWN BUG #4985: trigger-elicitation-request is listed for a URL-only elicitation client, whose call then fails; the fix changes this assertion.
392-
it("is listed for a URL-only client, which then cannot answer its form request", async () => {
393-
// Characterization: the tool is gated on `elicitation` alone, so a
394-
// client that declared only URL mode sees it and the call fails.
395-
const { s } = await connectElicitation(() => ({ action: "cancel" }), {
396-
elicitation: { url: {} },
397-
});
391+
it("is not listed for a URL-only client, which cannot answer a form request (#4985)", async () => {
392+
const { s, asked } = await connectElicitation(
393+
() => ({ action: "cancel" }),
394+
{ elicitation: { url: {} } },
395+
);
398396
session = s;
399-
const result = await s.client.callTool({
400-
name: "trigger-elicitation-request",
401-
arguments: {},
402-
});
403-
expect(result).toEqual({
404-
isError: true,
405-
content: [
406-
{
407-
type: "text",
408-
text: "MCP error -32602: MCP error -32602: Client does not support form-mode elicitation requests",
409-
},
410-
],
411-
});
397+
const { tools } = await s.client.listTools();
398+
expect(tools.map((t) => t.name)).not.toContain(
399+
"trigger-elicitation-request",
400+
);
401+
expect(tools.map((t) => t.name)).toContain("trigger-url-elicitation");
402+
expect(asked).toEqual([]);
412403
});
413404
});
414405

‎src/everything/__tests__/surface.test.ts‎

Lines changed: 33 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -63,24 +63,41 @@ describe("initialize", () => {
6363
);
6464
});
6565

66-
// KNOWN BUG #4792: pins current (wrong) behavior; the fix changes this assertion.
67-
it("names capability-gated tools in its instructions even for a client that cannot see them (#4792)", async () => {
68-
// Characterization of #4792: the instructions are static, so a client
69-
// that declares no sampling, elicitation or roots capability is told
70-
// about tools that are not in its tools/list. The fix changes this test.
66+
it("qualifies every capability-gated tool it names, for a client that cannot see them (#4792)", async () => {
67+
// The instructions are fixed before client capabilities are known, so a
68+
// client that declares no sampling, elicitation or roots capability still
69+
// receives them. Each gated tool it names may appear only in the
70+
// "Capability-Gated Tools" section or on a line that makes it conditional.
7171
session = await connect();
7272
const instructions = session.client.getInstructions() ?? "";
7373
const { tools } = await session.client.listTools();
7474
const names = tools.map((t) => t.name);
75-
76-
for (const gated of [
77-
"trigger-sampling-request",
78-
"trigger-elicitation-request",
75+
const gated = [
7976
"get-roots-list",
80-
]) {
81-
expect(instructions).toContain(`\`${gated}\``);
82-
expect(names).not.toContain(gated);
77+
"trigger-elicitation-request",
78+
"trigger-elicitation-request-async",
79+
"trigger-sampling-request",
80+
"trigger-sampling-request-async",
81+
"trigger-url-elicitation",
82+
];
83+
84+
const sections = instructions.split(/^## /m);
85+
const gatedSection =
86+
sections.find((part) => part.startsWith("Capability-Gated Tools")) ?? "";
87+
const unconditional = sections
88+
.filter((part) => part !== gatedSection)
89+
.flatMap((part) => part.split("\n"))
90+
.filter(
91+
(line) =>
92+
gated.some((tool) => line.includes(`\`${tool}\``)) &&
93+
!/\bif\b/i.test(line),
94+
);
95+
96+
for (const tool of gated) {
97+
expect(names).not.toContain(tool);
98+
expect(gatedSection).toContain(`\`${tool}\``);
8399
}
100+
expect(unconditional).toEqual([]);
84101
});
85102
});
86103

@@ -111,8 +128,11 @@ describe("tools/list", () => {
111128
[{ roots: {} }, ["get-roots-list"]],
112129
[{ sampling: {} }, ["trigger-sampling-request"]],
113130
[{ elicitation: {} }, ["trigger-elicitation-request"]],
131+
[{ elicitation: { form: {} } }, ["trigger-elicitation-request"]],
132+
// A URL-only client cannot answer the form request (#4985).
133+
[{ elicitation: { url: {} } }, ["trigger-url-elicitation"]],
114134
[
115-
{ elicitation: { url: {} } },
135+
{ elicitation: { form: {}, url: {} } },
116136
["trigger-elicitation-request", "trigger-url-elicitation"],
117137
],
118138
[

‎src/everything/docs/features.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,7 @@
2222
- `trigger-long-running-operation` (tools/trigger-long-running-operation.ts): Simulates a multi-step operation over a given `duration` and number of `steps`; reports progress via `notifications/progress` when a `progressToken` is provided by the client.
2323
- `toggle-simulated-logging` (tools/toggle-simulated-logging.ts): Starts or stops simulated, random‑leveled logging for the invoking session. Respects the client’s selected minimum logging level.
2424
- `toggle-subscriber-updates` (tools/toggle-subscriber-updates.ts): Starts or stops simulated resource update notifications for URIs the invoking session has subscribed to.
25-
- `trigger-elicitation-request` (tools/trigger-elicitation-request.ts): Issues an `elicitation/create` request using form-mode fields (strings, numbers, booleans, enums, and format validation) and returns the resulting action/content.
25+
- `trigger-elicitation-request` (tools/trigger-elicitation-request.ts): Issues an `elicitation/create` request using form-mode fields (strings, numbers, booleans, enums, and format validation) and returns the resulting action/content. Requires client form-mode elicitation: `elicitation.form`, or an `elicitation` object that declares neither mode.
2626
- `trigger-url-elicitation` (tools/trigger-url-elicitation.ts): Issues an `elicitation/create` request in URL mode (`mode: "url"`) with an `elicitationId`, or throws MCP error `-32042` (`UrlElicitationRequiredError`) when `errorPath=true`. On the error path the prerequisite elicitation it returns points at a different URL than the failing request (`https://modelcontextprotocol.io`); when the client satisfies it and retries the same call, the retry ignores `errorPath` and proceeds via the request path, so the client does not loop on the same error. The retry marker is one-shot per `(session, url, elicitationId)`: it is cleared on the recognized retry, so re-running the error path with identical arguments without an intervening prerequisite is treated as a retry and proceeds. Requires client capability `elicitation.url`.
2727
- `trigger-sampling-request` (tools/trigger-sampling-request.ts): Issues a `sampling/createMessage` request to the client/LLM using provided `prompt` and optional generation controls; returns the LLM's response payload.
2828
- `simulate-research-query` (tools/simulate-research-query.ts): Demonstrates MCP Tasks (SEP-1686) with a simulated multi-stage research operation. Accepts `topic` and `ambiguous` parameters. Returns a task that progresses through stages with status updates. If `ambiguous` is true and client supports elicitation, sends an elicitation request directly to gather clarification before completing.

‎src/everything/docs/instructions.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -26,7 +26,7 @@ present-and-failing, so do not attempt to call it.
2626
| ----------------------------------- | ------------------------------------------------------ |
2727
| `get-roots-list` | `roots` |
2828
| `trigger-sampling-request` | `sampling` |
29-
| `trigger-elicitation-request` | `elicitation` |
29+
| `trigger-elicitation-request` | `elicitation.form` (or `elicitation` with no mode) |
3030
| `trigger-url-elicitation` | `elicitation.url` |
3131
| `trigger-sampling-request-async` | `sampling` and `tasks.requests.sampling.createMessage` |
3232
| `trigger-elicitation-request-async` | `elicitation` and `tasks.requests.elicitation.create` |

‎src/everything/tools/trigger-elicitation-request.ts‎

Lines changed: 11 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,11 @@ const config = {
2121
/**
2222
* Registers the 'trigger-elicitation-request' tool.
2323
*
24-
* If the client does not support the elicitation capability, the tool is not registered.
24+
* The tool sends a form-mode request, so it is registered only when the client
25+
* supports form-mode elicitation: it declared `elicitation.form`, or an
26+
* `elicitation` object with neither `form` nor `url`, which the spec treats as
27+
* form mode for backwards compatibility. A client that declared only
28+
* `elicitation.url` does not get it (#4985).
2529
*
2630
* The registered tool sends an elicitation request for the user to provide information
2731
* based on a pre-defined schema of fields including text inputs, booleans, numbers,
@@ -37,13 +41,15 @@ const config = {
3741
* @param {McpServer} server - TThe McpServer instance where the tool will be registered.
3842
*/
3943
export const registerTriggerElicitationRequestTool = (server: McpServer) => {
40-
// Does the client support elicitation?
44+
// Does the client support form-mode elicitation?
4145
const clientCapabilities = server.server.getClientCapabilities() || {};
42-
const clientSupportsElicitation: boolean =
43-
clientCapabilities.elicitation !== undefined;
46+
const elicitation = clientCapabilities.elicitation;
47+
const clientSupportsFormElicitation: boolean =
48+
elicitation !== undefined &&
49+
(elicitation.form !== undefined || elicitation.url === undefined);
4450

4551
// If so, register tool
46-
if (clientSupportsElicitation) {
52+
if (clientSupportsFormElicitation) {
4753
server.registerTool(
4854
name,
4955
config,

0 commit comments

Comments
 (0)