Skip to content

Commit 84c2824

Browse files
iqdoctorValeriy_Pavlovich
iqdoctor
and
Valeriy_Pavlovich
authored
# feat(filesystem): add ToolAnnotations hints to filesystem tools (#3045)
**Files touched** - [src/filesystem/index.ts](../blob/HEAD/src/filesystem/index.ts) — add `annotations` metadata to each tool definition - [src/filesystem/README.md](../blob/HEAD/src/filesystem/README.md) — document ToolAnnotations mapping for all filesystem tools ## Description This change adds MCP `ToolAnnotations` (`readOnlyHint`, `idempotentHint`, `destructiveHint`) to all filesystem tools and documents the mapping in the filesystem README. MCP clients can now accurately distinguish read‑only vs. write tools, understand which operations are safe to retry, and highlight potentially destructive actions. ## Server Details - **Server**: filesystem - **Area**: tools (metadata returned via `listTools` / `ListToolsRequest`) and server docs ## Motivation and Context Previously, the filesystem server did not expose ToolAnnotations, so many clients (e.g. ChatGPT Apps) conservatively treated filesystem tools as generic write operations. This led to: - READ operations being surfaced with WRITE badges and confirmation prompts. - No way for clients to know which write tools are idempotent or potentially destructive. This PR aligns the implementation with `servers#2988` and updates the README to clearly document the semantics of each tool. Read‑only operations no longer need to be treated as writes, and destructive/idempotent behavior is explicit for UI and retry logic. ## How Has This Been Tested? - `npm run build --workspace @modelcontextprotocol/server-filesystem` - `npm test --workspaces --if-present` ## Breaking Changes None. ## Types of changes - [ ] Bug fix (non-breaking change which fixes an issue) - [x] New feature (non-breaking change which adds functionality) - [ ] Breaking change (fix or feature that would cause existing functionality to change) - [x] Documentation update ## Checklist - [x] I have read the [MCP Protocol Documentation](https://modelcontextprotocol.io) - [x] My changes follows MCP security best practices - [x] I have updated the server's README accordingly - [x] I have tested this with an LLM client - [x] My code follows the repository's style guidelines - [x] New and existing tests pass locally - [x] I have added appropriate error handling - [ ] I have documented all environment variables and configuration options ## Additional context None. Co-authored-by: Valeriy_Pavlovich <[email protected]>
1 parent 33e029f commit 84c2824

File tree

2 files changed

+57
-14
lines changed

2 files changed

+57
-14
lines changed

‎src/filesystem/README.md‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -175,6 +175,35 @@ The server's directory access control follows this flow:
175175
- Returns:
176176
- Directories that this server can read/write from
177177

178+
### Tool annotations (MCP hints)
179+
180+
This server sets [MCP ToolAnnotations](https://modelcontextprotocol.io/specification/2025-03-26/server/tools#toolannotations)
181+
on each tool so clients can:
182+
183+
- Distinguish **read‑only** tools from write‑capable tools.
184+
- Understand which write operations are **idempotent** (safe to retry with the same arguments).
185+
- Highlight operations that may be **destructive** (overwriting or heavily mutating data).
186+
187+
The mapping for filesystem tools is:
188+
189+
| Tool | readOnlyHint | idempotentHint | destructiveHint | Notes |
190+
|-----------------------------|--------------|----------------|-----------------|--------------------------------------------------|
191+
| `read_text_file` | `true` | – | – | Pure read |
192+
| `read_media_file` | `true` | – | – | Pure read |
193+
| `read_multiple_files` | `true` | – | – | Pure read |
194+
| `list_directory` | `true` | – | – | Pure read |
195+
| `list_directory_with_sizes` | `true` | – | – | Pure read |
196+
| `directory_tree` | `true` | – | – | Pure read |
197+
| `search_files` | `true` | – | – | Pure read |
198+
| `get_file_info` | `true` | – | – | Pure read |
199+
| `list_allowed_directories` | `true` | – | – | Pure read |
200+
| `create_directory` | `false` | `true` | `false` | Re‑creating the same dir is a no‑op |
201+
| `write_file` | `false` | `true` | `true` | Overwrites existing files |
202+
| `edit_file` | `false` | `false` | `true` | Re‑applying edits can fail or double‑apply |
203+
| `move_file` | `false` | `false` | `false` | Move/rename only; repeat usually errors |
204+
205+
> Note: `idempotentHint` and `destructiveHint` are meaningful only when `readOnlyHint` is `false`, as defined by the MCP spec.
206+
178207
## Usage with Claude Desktop
179208
Add this to your `claude_desktop_config.json`:
180209

‎src/filesystem/index.ts‎

Lines changed: 28 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -197,7 +197,8 @@ server.registerTool(
197197
title: "Read File (Deprecated)",
198198
description: "Read the complete contents of a file as text. DEPRECATED: Use read_text_file instead.",
199199
inputSchema: ReadTextFileArgsSchema.shape,
200-
outputSchema: { content: z.string() }
200+
outputSchema: { content: z.string() },
201+
annotations: { readOnlyHint: true }
201202
},
202203
readTextFileHandler
203204
);
@@ -219,7 +220,8 @@ server.registerTool(
219220
tail: z.number().optional().describe("If provided, returns only the last N lines of the file"),
220221
head: z.number().optional().describe("If provided, returns only the first N lines of the file")
221222
},
222-
outputSchema: { content: z.string() }
223+
outputSchema: { content: z.string() },
224+
annotations: { readOnlyHint: true }
223225
},
224226
readTextFileHandler
225227
);
@@ -240,7 +242,8 @@ server.registerTool(
240242
data: z.string(),
241243
mimeType: z.string()
242244
}))
243-
}
245+
},
246+
annotations: { readOnlyHint: true }
244247
},
245248
async (args: z.infer<typeof ReadMediaFileArgsSchema>) => {
246249
const validPath = await validatePath(args.path);
@@ -290,7 +293,8 @@ server.registerTool(
290293
.min(1)
291294
.describe("Array of file paths to read. Each path must be a string pointing to a valid file within allowed directories.")
292295
},
293-
outputSchema: { content: z.string() }
296+
outputSchema: { content: z.string() },
297+
annotations: { readOnlyHint: true }
294298
},
295299
async (args: z.infer<typeof ReadMultipleFilesArgsSchema>) => {
296300
const results = await Promise.all(
@@ -325,7 +329,8 @@ server.registerTool(
325329
path: z.string(),
326330
content: z.string()
327331
},
328-
outputSchema: { content: z.string() }
332+
outputSchema: { content: z.string() },
333+
annotations: { readOnlyHint: false, idempotentHint: true, destructiveHint: true }
329334
},
330335
async (args: z.infer<typeof WriteFileArgsSchema>) => {
331336
const validPath = await validatePath(args.path);
@@ -354,7 +359,8 @@ server.registerTool(
354359
})),
355360
dryRun: z.boolean().default(false).describe("Preview changes using git-style diff format")
356361
},
357-
outputSchema: { content: z.string() }
362+
outputSchema: { content: z.string() },
363+
annotations: { readOnlyHint: false, idempotentHint: false, destructiveHint: true }
358364
},
359365
async (args: z.infer<typeof EditFileArgsSchema>) => {
360366
const validPath = await validatePath(args.path);
@@ -378,7 +384,8 @@ server.registerTool(
378384
inputSchema: {
379385
path: z.string()
380386
},
381-
outputSchema: { content: z.string() }
387+
outputSchema: { content: z.string() },
388+
annotations: { readOnlyHint: false, idempotentHint: true, destructiveHint: false }
382389
},
383390
async (args: z.infer<typeof CreateDirectoryArgsSchema>) => {
384391
const validPath = await validatePath(args.path);
@@ -403,7 +410,8 @@ server.registerTool(
403410
inputSchema: {
404411
path: z.string()
405412
},
406-
outputSchema: { content: z.string() }
413+
outputSchema: { content: z.string() },
414+
annotations: { readOnlyHint: true }
407415
},
408416
async (args: z.infer<typeof ListDirectoryArgsSchema>) => {
409417
const validPath = await validatePath(args.path);
@@ -431,7 +439,8 @@ server.registerTool(
431439
path: z.string(),
432440
sortBy: z.enum(["name", "size"]).optional().default("name").describe("Sort entries by name or size")
433441
},
434-
outputSchema: { content: z.string() }
442+
outputSchema: { content: z.string() },
443+
annotations: { readOnlyHint: true }
435444
},
436445
async (args: z.infer<typeof ListDirectoryWithSizesArgsSchema>) => {
437446
const validPath = await validatePath(args.path);
@@ -509,7 +518,8 @@ server.registerTool(
509518
path: z.string(),
510519
excludePatterns: z.array(z.string()).optional().default([])
511520
},
512-
outputSchema: { content: z.string() }
521+
outputSchema: { content: z.string() },
522+
annotations: { readOnlyHint: true }
513523
},
514524
async (args: z.infer<typeof DirectoryTreeArgsSchema>) => {
515525
interface TreeEntry {
@@ -578,7 +588,8 @@ server.registerTool(
578588
source: z.string(),
579589
destination: z.string()
580590
},
581-
outputSchema: { content: z.string() }
591+
outputSchema: { content: z.string() },
592+
annotations: { readOnlyHint: false, idempotentHint: false, destructiveHint: false }
582593
},
583594
async (args: z.infer<typeof MoveFileArgsSchema>) => {
584595
const validSourcePath = await validatePath(args.source);
@@ -608,7 +619,8 @@ server.registerTool(
608619
pattern: z.string(),
609620
excludePatterns: z.array(z.string()).optional().default([])
610621
},
611-
outputSchema: { content: z.string() }
622+
outputSchema: { content: z.string() },
623+
annotations: { readOnlyHint: true }
612624
},
613625
async (args: z.infer<typeof SearchFilesArgsSchema>) => {
614626
const validPath = await validatePath(args.path);
@@ -633,7 +645,8 @@ server.registerTool(
633645
inputSchema: {
634646
path: z.string()
635647
},
636-
outputSchema: { content: z.string() }
648+
outputSchema: { content: z.string() },
649+
annotations: { readOnlyHint: true }
637650
},
638651
async (args: z.infer<typeof GetFileInfoArgsSchema>) => {
639652
const validPath = await validatePath(args.path);
@@ -658,7 +671,8 @@ server.registerTool(
658671
"Use this to understand which directories and their nested paths are available " +
659672
"before trying to access files.",
660673
inputSchema: {},
661-
outputSchema: { content: z.string() }
674+
outputSchema: { content: z.string() },
675+
annotations: { readOnlyHint: true }
662676
},
663677
async () => {
664678
const text = `Allowed directories:\n${allowedDirectories.join('\n')}`;

0 commit comments

Comments
 (0)