Skip to content

Commit d98c856

Browse files
cliffhallclaude
andcommitted
fix(filesystem): allow a client Root in its advertised form as well as its realpath
parseRootUri kept only the realpath of each client Root, so a request that used the Root's own spelling (a symlinked directory, /tmp on macOS) was refused. It now returns both forms and getValidRootDirectories admits both, deduplicated, as resolveAllowedDirectories does for command-line directories. validatePath still realpaths every request, so a symlink inside a Root that points outside it stays refused. Closes #5183 Co-Authored-By: Claude Opus 5.5 <[email protected]> Signed-off-by: cliffhall <[email protected]>
1 parent 858cfff commit d98c856

4 files changed

Lines changed: 113 additions & 13 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+
A client Root is now allowed in the form the client advertised it as well as in its resolved form, as command-line directories already were. A request that names a path through a symlinked Root's own spelling (for example `/tmp/...` for a Root of `file:///tmp/...` on macOS) is no longer refused, and `list_allowed_directories` lists both forms. Every request is still resolved and checked against the resolved directory, so a symlink inside a Root that points outside it stays refused.

‎src/filesystem/README.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,8 @@ A client that connects with a 2025-era protocol version (the `initialize` handsh
3131

3232
Roots notified by Client to Server, completely replace any server-side Allowed directories when provided.
3333

34+
A Root reached through a symlink is allowed in both its advertised form and its resolved form, as a command-line directory is: a Root of `file:///tmp/project` on macOS allows `/tmp/project` and `/private/tmp/project`. Every requested path is still resolved and checked against the resolved directories, so a symlink inside a Root that points outside it is refused.
35+
3436
**Important**: If server starts without command-line arguments AND a 2025-era client doesn't support roots protocol, the server fails at initialization: it logs the reason to stderr, closes the connection and exits with status 1. A client that supports roots but provides none (or none that are valid) keeps the connection, with no allowed directories until it sends `roots/list_changed` with valid roots.
3537

3638
The 2026-07-28 protocol has no `initialize` handshake and no server-to-client `roots/list` request, so a 2026-07-28 client's roots are never asked for: the command-line directories are the whole allow-list. A server started with none answers every tool call on such a connection with an error saying so.
@@ -205,7 +207,7 @@ The server's directory access control follows this flow:
205207
- List all directories the server is allowed to access
206208
- No input required
207209
- Returns:
208-
- Directories that this server can read/write from
210+
- Directories that this server can read/write from. A directory reached through a symlink is listed twice, in the form it was given and in its resolved form
209211

210212
### Slow and very large trees
211213

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

Lines changed: 79 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -84,15 +84,92 @@ describe("initial roots", () => {
8484
);
8585
});
8686

87-
it("resolve a symlinked root to its target", async () => {
87+
// #5183: a Root is allowed in its advertised spelling as well as its
88+
// realpath, as a command-line directory is, so a request that uses the
89+
// Root's own spelling is not refused.
90+
it("admit a symlinked root in both its advertised and its resolved form (#5183)", async () => {
8891
const link = path.join(cliDir, "link-to-root");
8992
await fs.symlink(rootDir, link);
93+
await fs.writeFile(path.join(rootDir, "note.txt"), "inside the root");
9094
const { client } = await connectTracked([], {
9195
capabilities: ROOTS,
9296
listRoots: () => [rootOf(link)],
9397
});
9498
await vi.waitFor(async () =>
95-
expect(await allowedDirectoriesOf(client)).toEqual([rootDir]),
99+
expect(await allowedDirectoriesOf(client)).toEqual([link, rootDir]),
100+
);
101+
const viaLink = await call(client, "read_text_file", {
102+
path: path.join(link, "note.txt"),
103+
});
104+
expect(textOf(viaLink)).toBe("inside the root");
105+
const viaTarget = await call(client, "read_text_file", {
106+
path: path.join(rootDir, "note.txt"),
107+
});
108+
expect(textOf(viaTarget)).toBe("inside the root");
109+
});
110+
111+
// #5183: admitting the advertised spelling does not widen access. Every
112+
// request is still realpath'd and re-checked, so a symlink inside the Root
113+
// that points outside it is refused under either spelling.
114+
it("refuse a symlink inside a symlinked root that points outside it (#5183)", async () => {
115+
const link = path.join(cliDir, "link-to-root");
116+
await fs.symlink(rootDir, link);
117+
const secret = path.join(cliDir, "secret.txt");
118+
await fs.writeFile(secret, "outside the root");
119+
await fs.symlink(secret, path.join(rootDir, "escape.txt"));
120+
const { client } = await connectTracked([], {
121+
capabilities: ROOTS,
122+
listRoots: () => [rootOf(link)],
123+
});
124+
await vi.waitFor(async () =>
125+
expect(await allowedDirectoriesOf(client)).toEqual([link, rootDir]),
126+
);
127+
for (const dir of [link, rootDir]) {
128+
const result = await call(client, "read_text_file", {
129+
path: path.join(dir, "escape.txt"),
130+
});
131+
expect(textOf(result)).toMatch(/^Access denied/);
132+
}
133+
});
134+
135+
// #5183 as reported: on macOS /tmp is a symlink to /private/tmp, so a Root
136+
// of file:///tmp/... was allowed only as /private/tmp/... and a request
137+
// naming /tmp/... was refused.
138+
it.runIf(process.platform === "darwin")(
139+
"admit a macOS /tmp root under its /tmp spelling (#5183)",
140+
async () => {
141+
const tmpRoot = await fs.mkdtemp("/tmp/mcp-fs-5183-");
142+
try {
143+
await fs.writeFile(path.join(tmpRoot, "note.txt"), "in /tmp");
144+
const { client } = await connectTracked([], {
145+
capabilities: ROOTS,
146+
listRoots: () => [rootOf(tmpRoot)],
147+
});
148+
await vi.waitFor(async () =>
149+
expect(await allowedDirectoriesOf(client)).toEqual([
150+
tmpRoot,
151+
await fs.realpath(tmpRoot),
152+
]),
153+
);
154+
const result = await call(client, "read_text_file", {
155+
path: path.join(tmpRoot, "note.txt"),
156+
});
157+
expect(textOf(result)).toBe("in /tmp");
158+
} finally {
159+
await fs.rm(tmpRoot, { recursive: true, force: true });
160+
}
161+
},
162+
);
163+
164+
it("list a root once when it is advertised in both its forms (#5183)", async () => {
165+
const link = path.join(cliDir, "link-to-root");
166+
await fs.symlink(rootDir, link);
167+
const { client } = await connectTracked([], {
168+
capabilities: ROOTS,
169+
listRoots: () => [rootOf(link), rootOf(rootDir)],
170+
});
171+
await vi.waitFor(async () =>
172+
expect(await allowedDirectoriesOf(client)).toEqual([link, rootDir]),
96173
);
97174
});
98175

‎src/filesystem/roots-utils.ts‎

Lines changed: 26 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -5,12 +5,22 @@ import { normalizePath, realpathWithRetry } from "./path-utils.js";
55
import type { Root } from "@modelcontextprotocol/server";
66
import { fileURLToPath } from "url";
77

8+
/** A root's two spellings: as the client advertised it, and its realpath. */
9+
interface RootPaths {
10+
advertised: string;
11+
resolved: string;
12+
}
13+
814
/**
9-
* Converts a root URI to a normalized directory path with basic security validation.
15+
* Converts a root URI to its normalized absolute path and its realpath.
16+
* Both are kept, as resolveAllowedDirectories in index.ts keeps both forms of
17+
* a command-line directory, so a request may use either spelling (#5183).
18+
* validatePath still realpaths every request, so access stays bounded by the
19+
* resolved directory.
1020
* @param rootUri - File URI (file://...) or plain directory path
11-
* @returns Promise resolving to validated path or null if invalid
21+
* @returns Promise resolving to both forms, or null if invalid
1222
*/
13-
async function parseRootUri(rootUri: string): Promise<string | null> {
23+
async function parseRootUri(rootUri: string): Promise<RootPaths | null> {
1424
try {
1525
const rawPath = rootUri.startsWith("file://")
1626
? fileURLToPath(rootUri)
@@ -21,7 +31,10 @@ async function parseRootUri(rootUri: string): Promise<string | null> {
2131
: rawPath;
2232
const absolutePath = path.resolve(expandedPath);
2333
const resolvedPath = await realpathWithRetry(absolutePath);
24-
return normalizePath(resolvedPath);
34+
return {
35+
advertised: normalizePath(absolutePath),
36+
resolved: normalizePath(resolvedPath),
37+
};
2538
} catch {
2639
return null; // Path doesn't exist or other error
2740
}
@@ -51,19 +64,20 @@ function formatDirectoryError(
5164
*
5265
* Converts root URI specifications (file:// URIs or plain paths) into normalized
5366
* directory paths, validating that each path exists and is a directory.
54-
* Includes symlink resolution for security.
67+
* Each root contributes its advertised form and, when it differs, its resolved
68+
* (realpath) form, deduplicated across roots.
5569
*
5670
* @param requestedRoots - Array of root specifications with URI and optional name
5771
* @returns Promise resolving to array of validated directory paths
5872
*/
5973
export async function getValidRootDirectories(
6074
requestedRoots: readonly Root[],
6175
): Promise<string[]> {
62-
const validatedDirectories: string[] = [];
76+
const validatedDirectories = new Set<string>();
6377

6478
for (const requestedRoot of requestedRoots) {
65-
const resolvedPath = await parseRootUri(requestedRoot.uri);
66-
if (!resolvedPath) {
79+
const rootPaths = await parseRootUri(requestedRoot.uri);
80+
if (!rootPaths) {
6781
console.error(
6882
formatDirectoryError(
6983
requestedRoot.uri,
@@ -74,10 +88,12 @@ export async function getValidRootDirectories(
7488
continue;
7589
}
7690

91+
const { advertised, resolved: resolvedPath } = rootPaths;
7792
try {
7893
const stats: Stats = await fs.stat(resolvedPath);
7994
if (stats.isDirectory()) {
80-
validatedDirectories.push(resolvedPath);
95+
validatedDirectories.add(advertised);
96+
validatedDirectories.add(resolvedPath);
8197
} else {
8298
console.error(
8399
formatDirectoryError(resolvedPath, undefined, "non-directory root"),
@@ -88,5 +104,5 @@ export async function getValidRootDirectories(
88104
}
89105
}
90106

91-
return validatedDirectories;
107+
return [...validatedDirectories];
92108
}

0 commit comments

Comments
 (0)