Skip to content

Commit 2515a0b

Browse files
committed
fix(everything): keep server instructions in step with capability-gated tools
The instructions string is read once in the server factory and handed to the McpServer constructor, before oninitialized runs and client capabilities are known, so every client receives the same text. Six of the server's tools are registered only when the client declared a matching capability, and the instructions referred to three of them -- two as unconditional imperatives. A client that declares no capabilities gets 13 tools in tools/list and none of the six, so an agent following the instructions calls a tool that is not in its catalog. Document the gated set and the capability each one needs, qualify the remaining references, and add two tests that derive the gated set from registerConditionalTools so the document cannot drift from it again.
1 parent d73f99e commit 2515a0b

2 files changed

Lines changed: 115 additions & 4 deletions

File tree

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

Lines changed: 94 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -126,6 +126,100 @@ describe('Registration Index Files', () => {
126126
});
127127
});
128128

129+
describe('instructions vs. capability-gated tools', () => {
130+
// The instructions are read once in the server factory and handed to the
131+
// McpServer constructor, before `oninitialized` runs and client capabilities
132+
// are known. They are therefore the same string for every client, while the
133+
// tools registered by registerConditionalTools are not. These tests pin the
134+
// two together.
135+
136+
// Every capability the conditional tools gate on, so the "all capabilities"
137+
// registration below is the full set.
138+
const allCapabilities = {
139+
roots: {},
140+
sampling: {},
141+
elicitation: { url: {} },
142+
tasks: {
143+
requests: {
144+
sampling: { createMessage: {} },
145+
elicitation: { create: {} },
146+
},
147+
},
148+
};
149+
150+
const registeredWith = async (capabilities: object): Promise<string[]> => {
151+
const { registerConditionalTools } = await import('../tools/index.js');
152+
const mockServer = {
153+
registerTool: vi.fn(),
154+
server: {
155+
getClientCapabilities: vi.fn(() => capabilities),
156+
},
157+
experimental: {
158+
tasks: {
159+
registerToolTask: vi.fn(),
160+
},
161+
},
162+
} as unknown as McpServer;
163+
164+
registerConditionalTools(mockServer);
165+
166+
const viaRegisterTool = (mockServer.registerTool as any).mock.calls.map(
167+
(call: any[]) => call[0]
168+
);
169+
const viaRegisterToolTask = (
170+
mockServer.experimental.tasks.registerToolTask as any
171+
).mock.calls.map((call: any[]) => call[0]);
172+
return [...viaRegisterTool, ...viaRegisterToolTask];
173+
};
174+
175+
// A tool is capability-gated if declaring the capabilities makes it appear.
176+
// Deriving it as a difference rather than hard-coding a list means a tool
177+
// that stops being gated drops out of these assertions on its own.
178+
const gatedTools = async (): Promise<string[]> => {
179+
const withAll = await registeredWith(allCapabilities);
180+
const withNone = await registeredWith({});
181+
return withAll.filter((name) => !withNone.includes(name)).sort();
182+
};
183+
184+
// The rows of the "Capability-Gated Tools" table, by tool name.
185+
const documentedTools = (instructions: string): string[] => {
186+
const section = instructions
187+
.split(/^## /m)
188+
.find((part) => part.startsWith('Capability-Gated Tools'));
189+
expect(section, 'instructions.md has no "Capability-Gated Tools" section').toBeDefined();
190+
return [...section!.matchAll(/^\|\s*`([a-z0-9-]+)`\s*\|/gm)]
191+
.map((match) => match[1])
192+
.sort();
193+
};
194+
195+
it('documents exactly the tools that client capabilities gate', async () => {
196+
const { readInstructions } = await import('../resources/index.js');
197+
198+
// A tool registered only when a capability is declared is absent from
199+
// tools/list for every other client, so an agent told to use it has
200+
// nothing to call. The instructions must name the same set the gates do.
201+
expect(documentedTools(readInstructions())).toEqual(await gatedTools());
202+
});
203+
204+
it('never tells an agent to use a capability-gated tool unconditionally', async () => {
205+
const { readInstructions } = await import('../resources/index.js');
206+
const instructions = readInstructions();
207+
const gated = await gatedTools();
208+
209+
// Lines in the gated section are already qualified by the section itself.
210+
const sections = instructions.split(/^## /m);
211+
const otherLines = sections
212+
.filter((part) => !part.startsWith('Capability-Gated Tools'))
213+
.flatMap((part) => part.split('\n'));
214+
215+
const unconditional = otherLines.filter(
216+
(line) => gated.some((name) => line.includes(`\`${name}\``)) && !/\bif\b/i.test(line)
217+
);
218+
219+
expect(unconditional, 'mention a gated tool without saying it may be absent').toEqual([]);
220+
});
221+
});
222+
129223
describe('resources/index.ts', () => {
130224
it('should register resource templates', async () => {
131225
const { registerResources } = await import('../resources/index.js');

‎src/everything/docs/instructions.md‎

Lines changed: 21 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@ Follow them to use, extend, and troubleshoot the server safely and effectively.
55

66
## Cross-Feature Relationships
77

8-
- Use `get-roots-list` to see client workspace roots before file operations
8+
- If `get-roots-list` is in your tool list, use it to see client workspace roots before file operations
99
- `gzip-file-as-resource` creates session-scoped resources accessible only during the current session
1010
- Enable `toggle-simulated-logging` before debugging to see server log messages
1111
- Enable `toggle-subscriber-updates` to receive periodic resource update notifications
@@ -14,14 +14,31 @@ Follow them to use, extend, and troubleshoot the server safely and effectively.
1414

1515
- `gzip-file-as-resource`: Max fetch size controlled by `GZIP_MAX_FETCH_SIZE` (default 10MB), timeout by `GZIP_MAX_FETCH_TIME_MILLIS` (default 30s), allowed domains by `GZIP_ALLOWED_DOMAINS`
1616
- Session resources are ephemeral and lost when the session ends
17-
- Sampling requests (`trigger-sampling-request`) require client sampling capability
18-
- Elicitation requests (`trigger-elicitation-request`) require client elicitation capability
17+
- Some tools are only registered for clients that declared the matching capability; see Capability-Gated Tools below
18+
19+
## Capability-Gated Tools
20+
21+
These tools are registered after initialization, and only if your client declared the matching
22+
capability. If it did not, the tool is absent from `tools/list` for this session rather than
23+
present-and-failing, so do not attempt to call it.
24+
25+
| Tool | Required client capability |
26+
| ----------------------------------- | ------------------------------------------------------ |
27+
| `get-roots-list` | `roots` |
28+
| `trigger-sampling-request` | `sampling` |
29+
| `trigger-elicitation-request` | `elicitation` |
30+
| `trigger-url-elicitation` | `elicitation.url` |
31+
| `trigger-sampling-request-async` | `sampling` and `tasks.requests.sampling.createMessage` |
32+
| `trigger-elicitation-request-async` | `elicitation` and `tasks.requests.elicitation.create` |
33+
34+
Every other tool in this document is registered for every client. Treat `tools/list` as
35+
authoritative: it reflects the capabilities you declared.
1936

2037
## Operational Patterns
2138

2239
- For long operations, use `trigger-long-running-operation` which sends progress notifications
2340
- Prefer reading resources before calling mutating tools
24-
- Check `get-roots-list` output to understand the client's workspace context
41+
- If `get-roots-list` is in your tool list, check its output to understand the client's workspace context
2542

2643
## Easter Egg
2744

0 commit comments

Comments
 (0)