Skip to content

Commit 1a7b9f9

Browse files
cliffhallclaude
andcommitted
feat(filesystem): set idempotentHint and destructiveHint on the read-only tools
The ten read-only tools set only readOnlyHint and openWorldHint, so a client reading idempotentHint or destructiveHint fell back to the spec's defaults (not idempotent, destructive). Set both explicitly (true, false), pin them in the tools/list table test, and add protocol-level invariants every tool must keep: all four hints present, a read-only tool idempotent and not destructive, none open-world. The README's annotation table now shows them, and lists read_file. Closes #3402 Co-Authored-By: Claude Opus 5.5 <[email protected]> Signed-off-by: cliffhall <[email protected]>
1 parent 446be48 commit 1a7b9f9

5 files changed

Lines changed: 169 additions & 23 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-filesystem": patch
3+
---
4+
5+
Every read-only tool (`read_file`, `read_text_file`, `read_media_file`, `read_multiple_files`, `list_directory`, `list_directory_with_sizes`, `directory_tree`, `search_files`, `get_file_info` and `list_allowed_directories`) now also sets `idempotentHint: true` and `destructiveHint: false`, so all four tool annotation hints are explicit on every tool and a client never falls back to the spec's defaults (destructive, not idempotent).

‎src/filesystem/README.md‎

Lines changed: 11 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -250,21 +250,22 @@ The mapping for filesystem tools is:
250250

251251
| Tool | readOnlyHint | idempotentHint | destructiveHint | Notes |
252252
|-----------------------------|--------------|----------------|-----------------|--------------------------------------------------|
253-
| `read_text_file` | `true` | – | – | Pure read |
254-
| `read_media_file` | `true` | – | – | Pure read |
255-
| `read_multiple_files` | `true` | – | – | Pure read |
256-
| `list_directory` | `true` | – | – | Pure read |
257-
| `list_directory_with_sizes` | `true` | – | – | Pure read |
258-
| `directory_tree` | `true` | – | – | Pure read |
259-
| `search_files` | `true` | – | – | Pure read |
260-
| `get_file_info` | `true` | – | – | Pure read |
261-
| `list_allowed_directories` | `true` | – | – | Pure read |
253+
| `read_file` | `true` | `true` | `false` | Deprecated alias of `read_text_file` |
254+
| `read_text_file` | `true` | `true` | `false` | Pure read |
255+
| `read_media_file` | `true` | `true` | `false` | Pure read |
256+
| `read_multiple_files` | `true` | `true` | `false` | Pure read |
257+
| `list_directory` | `true` | `true` | `false` | Pure read |
258+
| `list_directory_with_sizes` | `true` | `true` | `false` | Pure read |
259+
| `directory_tree` | `true` | `true` | `false` | Pure read |
260+
| `search_files` | `true` | `true` | `false` | Pure read |
261+
| `get_file_info` | `true` | `true` | `false` | Pure read |
262+
| `list_allowed_directories` | `true` | `true` | `false` | Pure read |
262263
| `create_directory` | `false` | `true` | `false` | Re‑creating the same dir is a no‑op |
263264
| `write_file` | `false` | `true` | `true` | Overwrites existing files |
264265
| `edit_file` | `false` | `false` | `true` | Re‑applying edits can fail or double‑apply |
265266
| `move_file` | `false` | `false` | `true` | Deletes source file |
266267

267-
> Note: `idempotentHint` and `destructiveHint` are meaningful only when `readOnlyHint` is `false`, as defined by the MCP spec. Every tool also sets `openWorldHint: false` — this server only accesses the local filesystem within its allowed directories, never an open or external world.
268+
> Note: the MCP spec gives `idempotentHint` and `destructiveHint` meaning only when `readOnlyHint` is `false`, but every tool sets them anyway, so a client that reads them without checking `readOnlyHint` first still sees the truth: a read can be repeated safely and changes nothing. Every tool also sets `openWorldHint: false` — this server only accesses the local filesystem within its allowed directories, never an open or external world.
268269
269270
## Requirements
270271

‎src/filesystem/__tests__/server-tools.test.ts‎

Lines changed: 9 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -94,14 +94,20 @@ describe("server identity and tool list", () => {
9494
expect(tools.map((t) => t.name)).toEqual(TOOL_NAMES);
9595
});
9696

97-
// #3402: the read-only tools carry no idempotentHint or destructiveHint.
98-
// When that issue is fixed, this table is the test to change.
97+
// #3402: every tool sets all four hints explicitly, the read-only ones
98+
// included (idempotent, never destructive), so a client never falls back
99+
// to the spec's defaults (destructive, not idempotent, open world).
99100
it("pins each tool's title and annotations (#3402)", async () => {
100101
const { tools } = await client.listTools();
101102
const table = Object.fromEntries(
102103
tools.map((t) => [t.name, { title: t.title, ...t.annotations }]),
103104
);
104-
const readOnly = { readOnlyHint: true, openWorldHint: false };
105+
const readOnly = {
106+
readOnlyHint: true,
107+
idempotentHint: true,
108+
destructiveHint: false,
109+
openWorldHint: false,
110+
};
105111
expect(table).toEqual({
106112
read_file: { title: "Read File (Deprecated)", ...readOnly },
107113
read_text_file: { title: "Read Text File", ...readOnly },
Lines changed: 84 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,84 @@
1+
// Protocol-level invariants on the tool annotations every filesystem tool
2+
// advertises in tools/list (#3402). server-tools.test.ts pins each tool's exact
3+
// hints; this file holds the rules any tool, existing or added later, must
4+
// keep: all four hints set explicitly (the spec's defaults for a missing hint
5+
// are the pessimistic ones, so leaving one out misdescribes the tool), a
6+
// read-only tool idempotent and never destructive, and no tool open-world,
7+
// since every tool is confined to the allowed directories.
8+
9+
import fs from "fs/promises";
10+
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
11+
import type { Tool } from "@modelcontextprotocol/client";
12+
import {
13+
connect,
14+
makeTempDir,
15+
quietStderr,
16+
type Connected,
17+
} from "./helpers.js";
18+
19+
let dir: string;
20+
let conn: Connected;
21+
let tools: Tool[];
22+
23+
beforeEach(async () => {
24+
// The server logs its roots decision to stderr on every connect.
25+
quietStderr();
26+
dir = await makeTempDir("mcp-fs-annotations-");
27+
conn = await connect([dir]);
28+
({ tools } = await conn.client.listTools());
29+
});
30+
31+
afterEach(async () => {
32+
vi.restoreAllMocks();
33+
await conn.close();
34+
await fs.rm(dir, { recursive: true, force: true });
35+
});
36+
37+
describe("tool annotations (#3402)", () => {
38+
it("sets all four hints, as booleans, on every tool", () => {
39+
expect(tools.length).toBeGreaterThan(0);
40+
for (const tool of tools) {
41+
const a = tool.annotations;
42+
expect(
43+
{
44+
readOnlyHint: typeof a?.readOnlyHint,
45+
idempotentHint: typeof a?.idempotentHint,
46+
destructiveHint: typeof a?.destructiveHint,
47+
openWorldHint: typeof a?.openWorldHint,
48+
},
49+
tool.name,
50+
).toEqual({
51+
readOnlyHint: "boolean",
52+
idempotentHint: "boolean",
53+
destructiveHint: "boolean",
54+
openWorldHint: "boolean",
55+
});
56+
}
57+
});
58+
59+
it("marks every read-only tool idempotent and not destructive", () => {
60+
const readOnly = tools.filter((t) => t.annotations?.readOnlyHint === true);
61+
expect(readOnly.length).toBeGreaterThan(0);
62+
for (const tool of readOnly) {
63+
expect(tool.annotations, tool.name).toMatchObject({
64+
idempotentHint: true,
65+
destructiveHint: false,
66+
});
67+
}
68+
});
69+
70+
it("marks no tool open-world", () => {
71+
for (const tool of tools) {
72+
expect(tool.annotations?.openWorldHint, tool.name).toBe(false);
73+
}
74+
});
75+
76+
it("keeps the edits that compound non-idempotent", () => {
77+
// Re-running edit_file or move_file with the same arguments does not
78+
// leave the same state (the edit no longer matches; the source is gone),
79+
// so neither may be advertised as safe to retry.
80+
const byName = new Map(tools.map((t) => [t.name, t.annotations]));
81+
expect(byName.get("edit_file")?.idempotentHint).toBe(false);
82+
expect(byName.get("move_file")?.idempotentHint).toBe(false);
83+
});
84+
});

‎src/filesystem/server.ts‎

Lines changed: 60 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -288,7 +288,12 @@ export function createServer(
288288
"Read the complete contents of a file as text. DEPRECATED: Use read_text_file instead.",
289289
inputSchema: jsonSchema2020(ReadTextFileArgsSchema.shape),
290290
outputSchema: jsonSchema2020({ content: z.string() }),
291-
annotations: { readOnlyHint: true, openWorldHint: false },
291+
annotations: {
292+
readOnlyHint: true,
293+
idempotentHint: true,
294+
destructiveHint: false,
295+
openWorldHint: false,
296+
},
292297
},
293298
readTextFileHandler,
294299
);
@@ -317,7 +322,12 @@ export function createServer(
317322
.describe("If provided, returns only the first N lines of the file"),
318323
}),
319324
outputSchema: jsonSchema2020({ content: z.string() }),
320-
annotations: { readOnlyHint: true, openWorldHint: false },
325+
annotations: {
326+
readOnlyHint: true,
327+
idempotentHint: true,
328+
destructiveHint: false,
329+
openWorldHint: false,
330+
},
321331
},
322332
readTextFileHandler,
323333
);
@@ -351,7 +361,12 @@ export function createServer(
351361
]),
352362
),
353363
}),
354-
annotations: { readOnlyHint: true, openWorldHint: false },
364+
annotations: {
365+
readOnlyHint: true,
366+
idempotentHint: true,
367+
destructiveHint: false,
368+
openWorldHint: false,
369+
},
355370
},
356371
async (args: z.infer<typeof ReadMediaFileArgsSchema>) => {
357372
const validPath = await validatePath(args.path, allowedDirectories);
@@ -407,7 +422,12 @@ export function createServer(
407422
"the entire operation. Only works within allowed directories.",
408423
inputSchema: jsonSchema2020(ReadMultipleFilesArgsSchema.shape),
409424
outputSchema: jsonSchema2020({ content: z.string() }),
410-
annotations: { readOnlyHint: true, openWorldHint: false },
425+
annotations: {
426+
readOnlyHint: true,
427+
idempotentHint: true,
428+
destructiveHint: false,
429+
openWorldHint: false,
430+
},
411431
},
412432
async (args: z.infer<typeof ReadMultipleFilesArgsSchema>) => {
413433
const results = await Promise.all(
@@ -526,7 +546,12 @@ export function createServer(
526546
"finding specific files within a directory. Only works within allowed directories.",
527547
inputSchema: jsonSchema2020(ListDirectoryArgsSchema.shape),
528548
outputSchema: jsonSchema2020({ content: z.string() }),
529-
annotations: { readOnlyHint: true, openWorldHint: false },
549+
annotations: {
550+
readOnlyHint: true,
551+
idempotentHint: true,
552+
destructiveHint: false,
553+
openWorldHint: false,
554+
},
530555
},
531556
async (args: z.infer<typeof ListDirectoryArgsSchema>) => {
532557
const validPath = await validatePath(args.path, allowedDirectories);
@@ -555,7 +580,12 @@ export function createServer(
555580
"finding specific files within a directory. Only works within allowed directories.",
556581
inputSchema: jsonSchema2020(ListDirectoryWithSizesArgsSchema.shape),
557582
outputSchema: jsonSchema2020({ content: z.string() }),
558-
annotations: { readOnlyHint: true, openWorldHint: false },
583+
annotations: {
584+
readOnlyHint: true,
585+
idempotentHint: true,
586+
destructiveHint: false,
587+
openWorldHint: false,
588+
},
559589
},
560590
async (args: z.infer<typeof ListDirectoryWithSizesArgsSchema>) => {
561591
const validPath = await validatePath(args.path, allowedDirectories);
@@ -642,7 +672,12 @@ export function createServer(
642672
"The output is formatted with 2-space indentation for readability. Only works within allowed directories.",
643673
inputSchema: jsonSchema2020(DirectoryTreeArgsSchema.shape),
644674
outputSchema: jsonSchema2020({ content: z.string() }),
645-
annotations: { readOnlyHint: true, openWorldHint: false },
675+
annotations: {
676+
readOnlyHint: true,
677+
idempotentHint: true,
678+
destructiveHint: false,
679+
openWorldHint: false,
680+
},
646681
},
647682
async (args: z.infer<typeof DirectoryTreeArgsSchema>) => {
648683
interface TreeEntry {
@@ -759,7 +794,12 @@ export function createServer(
759794
"Only searches within allowed directories.",
760795
inputSchema: jsonSchema2020(SearchFilesArgsSchema.shape),
761796
outputSchema: jsonSchema2020({ content: z.string() }),
762-
annotations: { readOnlyHint: true, openWorldHint: false },
797+
annotations: {
798+
readOnlyHint: true,
799+
idempotentHint: true,
800+
destructiveHint: false,
801+
openWorldHint: false,
802+
},
763803
},
764804
async (args: z.infer<typeof SearchFilesArgsSchema>) => {
765805
const validPath = await validatePath(args.path, allowedDirectories);
@@ -788,7 +828,12 @@ export function createServer(
788828
"without reading the actual content. Only works within allowed directories.",
789829
inputSchema: jsonSchema2020(GetFileInfoArgsSchema.shape),
790830
outputSchema: jsonSchema2020({ content: z.string() }),
791-
annotations: { readOnlyHint: true, openWorldHint: false },
831+
annotations: {
832+
readOnlyHint: true,
833+
idempotentHint: true,
834+
destructiveHint: false,
835+
openWorldHint: false,
836+
},
792837
},
793838
async (args: z.infer<typeof GetFileInfoArgsSchema>) => {
794839
const validPath = await validatePath(args.path, allowedDirectories);
@@ -814,7 +859,12 @@ export function createServer(
814859
"before trying to access files.",
815860
inputSchema: jsonSchema2020({}),
816861
outputSchema: jsonSchema2020({ content: z.string() }),
817-
annotations: { readOnlyHint: true, openWorldHint: false },
862+
annotations: {
863+
readOnlyHint: true,
864+
idempotentHint: true,
865+
destructiveHint: false,
866+
openWorldHint: false,
867+
},
818868
},
819869
async () => {
820870
const text = `Allowed directories:\n${allowedDirectories.join("\n")}`;

0 commit comments

Comments
 (0)