Skip to content

Commit f3e5d36

Browse files
cliffhallclaude
andcommitted
fix(filesystem): bound realpath/readdir waits and recursive walks
search_files, directory_tree and path validation could hang for minutes on lazily materialized provider folders (macOS CloudStorage, iCloud Drive). Each realpath and recursive readdir now waits at most 15 s and fails the request with a clear error; a timed-out realpath refuses the path. Both walks stop with an error after 100,000 entries, and search_files applies excludePatterns before validating an entry, so an excluded subtree is never touched. Prior art: #4212 by JonoGitty. Co-Authored-By: Claude Opus 5.5 <[email protected]> Signed-off-by: cliffhall <[email protected]>
1 parent 84b412b commit f3e5d36

5 files changed

Lines changed: 397 additions & 15 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+
`search_files`, `directory_tree` and path validation no longer hang on slow provider-backed folders (macOS CloudStorage, iCloud Drive, slow network mounts). Each `realpath` and recursive `readdir` now waits at most 15 seconds and then fails the request with an error naming the path; a path whose realpath times out is refused. `search_files` and `directory_tree` stop with an error after visiting 100,000 entries. `search_files` now applies `excludePatterns` before resolving an entry, so an excluded folder is never touched.

‎src/filesystem/README.md‎

Lines changed: 26 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -165,9 +165,12 @@ The server's directory access control follows this flow:
165165
- Inputs:
166166
- `path` (string): Starting directory
167167
- `pattern` (string): Search pattern
168-
- `excludePatterns` (string[]): Exclude any patterns.
168+
- `excludePatterns` (string[]): Exclude any patterns. An excluded entry is
169+
skipped before it is resolved or read, so excluding a slow folder keeps
170+
the search out of it entirely.
169171
- Glob-style pattern matching
170172
- Returns full paths to matches
173+
- Bounded: see [Slow and very large trees](#slow-and-very-large-trees)
171174

172175
- **directory_tree**
173176
- Get recursive JSON tree structure of directory contents
@@ -182,6 +185,7 @@ The server's directory access control follows this flow:
182185
- Empty array for empty directories
183186
- Omitted for files
184187
- Output is formatted with 2-space indentation for readability
188+
- Bounded: see [Slow and very large trees](#slow-and-very-large-trees)
185189

186190
- **get_file_info**
187191
- Get detailed file/directory metadata
@@ -203,6 +207,27 @@ The server's directory access control follows this flow:
203207
- Returns:
204208
- Directories that this server can read/write from
205209

210+
### Slow and very large trees
211+
212+
A folder backed by a cloud-storage provider (macOS `~/Library/CloudStorage`,
213+
iCloud Drive) or a slow network mount can make a single filesystem call block
214+
for minutes while the provider fetches metadata. Two fixed limits keep one
215+
request from stalling the server:
216+
217+
- **Resolving a path (in any tool), and each directory read in `search_files`
218+
and `directory_tree`, waits at most 15 seconds.** A call that takes longer ends
219+
the request with an error naming the path (`Filesystem call timed out after
220+
15000 ms: ...`). A path whose real location cannot be read in time is
221+
refused, never admitted.
222+
- **`search_files` and `directory_tree` visit at most 100,000 entries.** A walk
223+
that reaches the cap ends with an error (`... stopped after visiting 100000
224+
entries ...`) rather than a partial result. Excluded entries do not count.
225+
226+
Either error means: narrow `path`, or name the slow or large folder in
227+
`excludePatterns`. A timed-out call cannot be cancelled and finishes in the
228+
background, so a provider that stalls repeatedly can still slow the server's
229+
other file operations until it answers.
230+
206231
### Tool annotations (MCP hints)
207232

208233
This server sets [MCP ToolAnnotations](https://modelcontextprotocol.io/specification/2025-03-26/server/tools#toolannotations)
Lines changed: 229 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,229 @@
1+
// Protocol-level tests for the bounds on slow filesystem calls and on the
2+
// recursive walks (#4162). A macOS CloudStorage or iCloud Drive folder can make
3+
// realpath or readdir block for minutes, which no CI runner can reproduce, so
4+
// these tests stand a call that never settles in for the slow provider: they
5+
// spy on the fs/promises object the server shares with this file, and advance
6+
// fake timers past FS_CALL_TIMEOUT_MS instead of waiting it out. Every call
7+
// they do not single out goes to the real filesystem.
8+
9+
import fs from "fs/promises";
10+
import type { Dirent, PathLike } from "fs";
11+
import path from "path";
12+
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
13+
import type { Client } from "@modelcontextprotocol/client";
14+
import {
15+
call,
16+
connect,
17+
makeTempDir,
18+
quietStderr,
19+
textOf,
20+
type Connected,
21+
} from "./helpers.js";
22+
import { FS_CALL_TIMEOUT_MS, MAX_WALK_ENTRIES } from "../lib.js";
23+
24+
const realReaddir = fs.readdir.bind(fs);
25+
const realRealpath = fs.realpath.bind(fs);
26+
27+
let dir: string;
28+
let conn: Connected;
29+
let client: Client;
30+
31+
beforeEach(async () => {
32+
quietStderr();
33+
dir = await makeTempDir("mcp-fs-bounded-");
34+
await fs.mkdir(path.join(dir, "cloud", "deep"), { recursive: true });
35+
await fs.mkdir(path.join(dir, "local"));
36+
await fs.writeFile(path.join(dir, "local", "a.txt"), "");
37+
await fs.writeFile(path.join(dir, "cloud", "deep", "b.txt"), "");
38+
conn = await connect([dir]);
39+
client = conn.client;
40+
});
41+
42+
afterEach(async () => {
43+
vi.useRealTimers();
44+
vi.restoreAllMocks();
45+
await conn.close();
46+
await fs.rm(dir, { recursive: true, force: true });
47+
});
48+
49+
/**
50+
* Make fs.readdir or fs.realpath never settle for `stalled`, the way a lazy
51+
* provider path blocks. Resolves once the server has made that call, so the
52+
* test advances the clock only after the timeout is armed.
53+
*/
54+
function stall(method: "readdir" | "realpath", stalled: string): Promise<void> {
55+
let reached!: () => void;
56+
const called = new Promise<void>((resolve) => {
57+
reached = resolve;
58+
});
59+
const real = method === "readdir" ? realReaddir : realRealpath;
60+
const fake = (target: PathLike, ...rest: unknown[]): Promise<unknown> => {
61+
if (target.toString() === stalled) {
62+
reached();
63+
return new Promise(() => {});
64+
}
65+
return (real as (target: PathLike, ...rest: unknown[]) => Promise<unknown>)(
66+
target,
67+
...rest,
68+
);
69+
};
70+
if (method === "readdir") {
71+
vi.spyOn(fs, "readdir").mockImplementation(fake as typeof fs.readdir);
72+
} else {
73+
vi.spyOn(fs, "realpath").mockImplementation(fake as typeof fs.realpath);
74+
}
75+
return called;
76+
}
77+
78+
/** Start a tool call against a stalled path, and run the clock past the timeout. */
79+
async function callPastTimeout(
80+
called: Promise<void>,
81+
name: string,
82+
args: Record<string, unknown>,
83+
) {
84+
vi.useFakeTimers({ toFake: ["setTimeout", "clearTimeout"] });
85+
const pending = call(client, name, args);
86+
await called;
87+
await vi.advanceTimersByTimeAsync(FS_CALL_TIMEOUT_MS);
88+
return pending;
89+
}
90+
91+
/** `count` plain-file directory entries named f0, f1, … under `parent`. */
92+
function fileEntries(parent: string, count: number): Dirent[] {
93+
return Array.from(
94+
{ length: count },
95+
(_, index) =>
96+
({
97+
name: `f${index}`,
98+
parentPath: parent,
99+
isDirectory: () => false,
100+
isFile: () => true,
101+
isSymbolicLink: () => false,
102+
}) as Dirent,
103+
);
104+
}
105+
106+
describe("search_files", () => {
107+
it("applies excludePatterns before touching an entry: an excluded subtree is never realpath'd or read", async () => {
108+
const realpath = vi.spyOn(fs, "realpath");
109+
const readdir = vi.spyOn(fs, "readdir");
110+
const result = await call(client, "search_files", {
111+
path: dir,
112+
pattern: "**/*.txt",
113+
excludePatterns: ["cloud"],
114+
});
115+
expect(textOf(result)).toBe(path.join(dir, "local", "a.txt"));
116+
const cloud = path.join(dir, "cloud");
117+
const touched = [...realpath.mock.calls, ...readdir.mock.calls].map(
118+
([target]) => target.toString(),
119+
);
120+
expect(touched.filter((target) => target.startsWith(cloud))).toEqual([]);
121+
});
122+
123+
it("fails with a timeout error when a subdirectory's readdir never settles", async () => {
124+
const called = stall("readdir", path.join(dir, "cloud"));
125+
const result = await callPastTimeout(called, "search_files", {
126+
path: dir,
127+
pattern: "**/*.txt",
128+
});
129+
expect(result.isError).toBe(true);
130+
expect(textOf(result)).toContain(
131+
`Filesystem call timed out after ${FS_CALL_TIMEOUT_MS} ms: readdir ${path.join(dir, "cloud")}`,
132+
);
133+
});
134+
135+
it("fails closed when an entry's realpath never settles: the entry is not admitted and the search errors", async () => {
136+
const stalled = path.join(dir, "cloud", "deep", "b.txt");
137+
const called = stall("realpath", stalled);
138+
const result = await callPastTimeout(called, "search_files", {
139+
path: dir,
140+
pattern: "**/*.txt",
141+
});
142+
expect(result.isError).toBe(true);
143+
expect(textOf(result)).toContain(`realpath ${stalled}`);
144+
});
145+
146+
it(`stops with an error after visiting ${MAX_WALK_ENTRIES} entries`, async () => {
147+
vi.spyOn(fs, "readdir").mockImplementation(((target: PathLike) =>
148+
target.toString() === dir
149+
? Promise.resolve(fileEntries(dir, MAX_WALK_ENTRIES + 1))
150+
: realReaddir(target)) as typeof fs.readdir);
151+
// The listed names do not exist on disk; resolve them as themselves so
152+
// each entry costs a string check rather than a real lookup.
153+
vi.spyOn(fs, "realpath").mockImplementation(((target: PathLike) =>
154+
Promise.resolve(target.toString())) as typeof fs.realpath);
155+
const result = await call(client, "search_files", {
156+
path: dir,
157+
pattern: "nothing-matches",
158+
});
159+
expect(result.isError).toBe(true);
160+
expect(textOf(result)).toContain(
161+
`search_files stopped after visiting ${MAX_WALK_ENTRIES} entries under ${dir}`,
162+
);
163+
});
164+
165+
it("still skips an entry that fails for any other reason", async () => {
166+
const refused = path.join(dir, "local", "a.txt");
167+
vi.spyOn(fs, "realpath").mockImplementation(((target: PathLike) =>
168+
target.toString() === refused
169+
? Promise.reject(Object.assign(new Error("EACCES"), { code: "EACCES" }))
170+
: realRealpath(target)) as typeof fs.realpath);
171+
const result = await call(client, "search_files", {
172+
path: dir,
173+
pattern: "**/*.txt",
174+
});
175+
expect(textOf(result)).toBe(path.join(dir, "cloud", "deep", "b.txt"));
176+
});
177+
});
178+
179+
describe("directory_tree", () => {
180+
it("fails with a timeout error when a subdirectory's readdir never settles", async () => {
181+
const called = stall("readdir", path.join(dir, "cloud", "deep"));
182+
const result = await callPastTimeout(called, "directory_tree", {
183+
path: dir,
184+
});
185+
expect(result.isError).toBe(true);
186+
expect(textOf(result)).toContain(
187+
`readdir ${path.join(dir, "cloud", "deep")}`,
188+
);
189+
});
190+
191+
it(`stops with an error after visiting ${MAX_WALK_ENTRIES} entries`, async () => {
192+
vi.spyOn(fs, "readdir").mockImplementation(((target: PathLike) =>
193+
target.toString() === dir
194+
? Promise.resolve(fileEntries(dir, MAX_WALK_ENTRIES + 1))
195+
: realReaddir(target)) as typeof fs.readdir);
196+
const result = await call(client, "directory_tree", { path: dir });
197+
expect(result.isError).toBe(true);
198+
expect(textOf(result)).toContain(
199+
`directory_tree stopped after visiting ${MAX_WALK_ENTRIES} entries under ${dir}`,
200+
);
201+
});
202+
203+
it("does not count excluded entries toward the cap", async () => {
204+
vi.spyOn(fs, "readdir").mockImplementation(((target: PathLike) =>
205+
target.toString() === dir
206+
? Promise.resolve(fileEntries(dir, MAX_WALK_ENTRIES + 1))
207+
: realReaddir(target)) as typeof fs.readdir);
208+
const result = await call(client, "directory_tree", {
209+
path: dir,
210+
excludePatterns: ["f*"],
211+
});
212+
expect(result.isError).toBeFalsy();
213+
expect(JSON.parse(textOf(result))).toEqual([]);
214+
});
215+
});
216+
217+
describe("path validation", () => {
218+
it("refuses a path whose realpath never settles, rather than admitting it", async () => {
219+
const stalled = path.join(dir, "local", "a.txt");
220+
const called = stall("realpath", stalled);
221+
const result = await callPastTimeout(called, "read_text_file", {
222+
path: stalled,
223+
});
224+
expect(result.isError).toBe(true);
225+
expect(textOf(result)).toContain(
226+
`Filesystem call timed out after ${FS_CALL_TIMEOUT_MS} ms: realpath ${stalled}`,
227+
);
228+
});
229+
});

0 commit comments

Comments
 (0)