Skip to content

Commit b766bc2

Browse files
cliffhallclaude
andcommitted
feat(filesystem): per-directory read-only access with --read-only-dir
Add a repeatable --read-only-dir <path> option that makes one allowed directory read-only while the others stay writable (#5348). validatePath now takes a required access mode; a "write" validation must be handed the read-only directories and refuses a resolved path inside any of them, so a write tool cannot skip the check. Every write tool stays listed. move_file checks both ends, copy_file its destination. Roots never lift the marking. Co-Authored-By: Claude Opus 5.5 <[email protected]> Signed-off-by: cliffhall <[email protected]>
1 parent 281b167 commit b766bc2

12 files changed

Lines changed: 725 additions & 49 deletions
Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
"@modelcontextprotocol/server-filesystem": minor
3+
---
4+
5+
Add `--read-only-dir <path>`, repeatable, to make one allowed directory read-only while the others stay writable. Every write tool stays listed but refuses a target inside a read-only directory (`move_file` on either end, `copy_file` on its destination), checked on the resolved path so a symlink cannot route around it; a 2025-era client's Roots never lift the marking. `list_allowed_directories` names the read-only directories.

‎src/filesystem/README.md‎

Lines changed: 18 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,8 @@ Specify Allowed directories when starting the server:
2424
mcp-server-filesystem /path/to/dir1 /path/to/dir2
2525
```
2626

27+
Options may come before, between or after the directories: `--read-only`, `--read-only-dir <path>` (both below) and `--confine-roots` (under Method 2).
28+
2729
This is the only method that works on every protocol version, so it is the one to use.
2830

2931
### Read-only Mode
@@ -36,7 +38,22 @@ The server then registers only the tools annotated `readOnlyHint: true` in the [
3638

3739
The flag may appear anywhere among the arguments. `--` ends the options, so a directory literally named `--read-only` can be given after it.
3840

39-
Read-only mode covers every allowed directory. To make only some of them read-only, run two servers: one with `--read-only` for the directories to protect, and one without it for the rest. That separation holds only while the writable server keeps its command-line directories: a 2025-era client that supports Roots replaces them (see Method 2), so it could expose a protected directory to the writable server, unless that server is started with `--confine-roots` (see below). Where that matters, make the protected directories read-only at the operating-system level as well, with file permissions or, with Docker, a bind mount's `ro` flag.
41+
Read-only mode covers every allowed directory. To make only some of them read-only, use `--read-only-dir` below.
42+
43+
#### Read-only directories
44+
Add `--read-only-dir <path>` to make one directory read-only while the others stay writable. Repeat it for each directory to protect:
45+
```bash
46+
mcp-server-filesystem --read-only-dir /path/to/reference /path/to/workspace
47+
```
48+
49+
- A read-only directory is an allowed directory too, so it need not also be listed on its own.
50+
- Every write tool (`write_file`, `append_file`, `edit_file`, `create_directory`, `move_file` and `copy_file`) stays listed, since the other directories are writable, but refuses a target inside a read-only directory with an error such as `Access denied - read-only directory: /path/to/reference/notes.md is in /path/to/reference, which the server was started with --read-only-dir`. `move_file` is refused when either its source or its destination is inside one; `copy_file` may copy out of one, never into it. `edit_file` is refused there even with `dryRun`.
51+
- The check runs on a path's resolved location, so a symlink in a writable directory cannot route a write into a read-only one.
52+
- A path inside any read-only directory is refused, so a directory nested inside a read-only one is read-only too, even if it is also given as a writable directory.
53+
- The marking is fixed at startup and holds on both protocol eras. A 2025-era client's Roots can replace the allowed directories (see Method 2), but Roots say nothing about writing, so they never lift it: a write into a read-only directory is refused whichever directories are in force, with or without `--confine-roots`.
54+
- `list_allowed_directories` lists the read-only directories after the allowed ones, and the server logs them to stderr at startup.
55+
56+
The option may appear anywhere among the arguments, and takes the next argument as its directory, whatever it is. `--` ends the options, so after it `--read-only-dir` is a directory name. With `--read-only` as well, every write tool is withheld anyway. For defence in depth, make the protected directories read-only at the operating-system level as well, with file permissions or, with Docker, a bind mount's `ro` flag.
4057

4158
### Method 2: MCP Roots (Deprecated, 2025-era clients only)
4259
A client that connects with a 2025-era protocol version (the `initialize` handshake) and supports [Roots](https://modelcontextprotocol.io/docs/learn/client-concepts#roots) can dynamically update the Allowed directories.

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

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -227,11 +227,13 @@ describe("the command line", () => {
227227
directories: ["/a"],
228228
readOnly: false,
229229
confineRoots: true,
230+
readOnlyDirectories: [],
230231
});
231232
expect(parseArgs(["--", "--confine-roots"])).toEqual({
232233
directories: ["--confine-roots"],
233234
readOnly: false,
234235
confineRoots: false,
236+
readOnlyDirectories: [],
235237
});
236238
});
237239

‎src/filesystem/__tests__/lib.test.ts‎

Lines changed: 24 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -288,7 +288,7 @@ describe("Lib Functions", () => {
288288
if (process.platform === "win32") return;
289289

290290
await expect(
291-
validatePath("C:\\Users\\me\\notes\\file.md", allowedDirs),
291+
validatePath("C:\\Users\\me\\notes\\file.md", allowedDirs, "read"),
292292
).rejects.toThrow("Windows-style path received on a POSIX host");
293293
});
294294

@@ -308,7 +308,7 @@ describe("Lib Functions", () => {
308308
process.platform === "win32"
309309
? "C:\\Users\\test\\file.txt"
310310
: "/home/user/file.txt";
311-
const result = await validatePath(testPath, allowedDirs);
311+
const result = await validatePath(testPath, allowedDirs, "read");
312312
expect(result).toBe(testPath);
313313
});
314314

@@ -317,9 +317,9 @@ describe("Lib Functions", () => {
317317
process.platform === "win32"
318318
? "C:\\Windows\\System32\\file.txt"
319319
: "/etc/passwd";
320-
await expect(validatePath(testPath, allowedDirs)).rejects.toThrow(
321-
"Access denied - path outside allowed directories",
322-
);
320+
await expect(
321+
validatePath(testPath, allowedDirs, "read"),
322+
).rejects.toThrow("Access denied - path outside allowed directories");
323323
});
324324

325325
it("handles non-existent files by checking parent directory", async () => {
@@ -338,7 +338,7 @@ describe("Lib Functions", () => {
338338
.mockRejectedValueOnce(enoentError)
339339
.mockResolvedValueOnce(parentPath);
340340

341-
const result = await validatePath(newFilePath, allowedDirs);
341+
const result = await validatePath(newFilePath, allowedDirs, "read");
342342
expect(result).toBe(path.resolve(newFilePath));
343343
});
344344

@@ -360,7 +360,7 @@ describe("Lib Functions", () => {
360360
// undefined, so every component below it counts as missing.
361361
mockFs.realpath.mockRejectedValueOnce(enoentError);
362362

363-
const result = await validatePath(newFilePath, allowedDirs);
363+
const result = await validatePath(newFilePath, allowedDirs, "read");
364364
expect(result).toBe(path.resolve(newFilePath));
365365
});
366366

@@ -381,7 +381,7 @@ describe("Lib Functions", () => {
381381
mockFs.lstat.mockResolvedValueOnce({} as Stats);
382382

383383
await expect(
384-
validatePath(path.join(base, "LINK", "a"), allowedDirs),
384+
validatePath(path.join(base, "LINK", "a"), allowedDirs, "read"),
385385
).rejects.toThrow(
386386
`Access denied - symlink target outside allowed directories: ${outsideDir}`,
387387
);
@@ -398,7 +398,7 @@ describe("Lib Functions", () => {
398398
mockFs.lstat.mockRejectedValueOnce(new Error("EACCES lstat"));
399399

400400
await expect(
401-
validatePath(path.join(base, "new", "f.txt"), allowedDirs),
401+
validatePath(path.join(base, "new", "f.txt"), allowedDirs, "read"),
402402
).rejects.toThrow("EACCES lstat");
403403
});
404404

@@ -416,7 +416,7 @@ describe("Lib Functions", () => {
416416
mockReaddirNames.mockResolvedValueOnce(["link"]);
417417

418418
await expect(
419-
validatePath(path.join(base, "link", "a"), allowedDirs),
419+
validatePath(path.join(base, "link", "a"), allowedDirs, "read"),
420420
).rejects.toThrow("EACCES realpath");
421421
});
422422

@@ -432,9 +432,9 @@ describe("Lib Functions", () => {
432432
// Every ancestor, all the way up to the filesystem root, is missing.
433433
mockFs.realpath.mockRejectedValue(enoentError);
434434

435-
await expect(validatePath(newFilePath, allowedDirs)).rejects.toThrow(
436-
"Parent directory does not exist",
437-
);
435+
await expect(
436+
validatePath(newFilePath, allowedDirs, "read"),
437+
).rejects.toThrow("Parent directory does not exist");
438438
});
439439

440440
it("resolves relative paths against allowed directories instead of process.cwd()", async () => {
@@ -447,7 +447,7 @@ describe("Lib Functions", () => {
447447
process.cwd = vi.fn(() => disallowedCwd);
448448

449449
try {
450-
const result = await validatePath(relativePath, allowedDirs);
450+
const result = await validatePath(relativePath, allowedDirs, "read");
451451

452452
// Result should be resolved against first allowed directory, not process.cwd()
453453
const expectedPath =
@@ -499,9 +499,9 @@ describe("Lib Functions", () => {
499499

500500
it("respells the request onto the allowed directory when the file system folds case", async () => {
501501
foldingLstat();
502-
await expect(validatePath(requestedFile, allowedDirs)).resolves.toBe(
503-
respelled,
504-
);
502+
await expect(
503+
validatePath(requestedFile, allowedDirs, "read"),
504+
).resolves.toBe(respelled);
505505
});
506506

507507
it("refuses when a directory holds two entries differing only in case", async () => {
@@ -512,14 +512,14 @@ describe("Lib Functions", () => {
512512
p.toString() === parent ? [first, first.toUpperCase()] : [second],
513513
);
514514
await expect(
515-
validatePath(requestedFile, allowedDirs),
515+
validatePath(requestedFile, allowedDirs, "read"),
516516
).rejects.toThrow("Access denied - path outside allowed directories");
517517
});
518518

519519
it("refuses when the requested spelling does not exist (a case-sensitive directory)", async () => {
520520
// beforeEach makes every lstat ENOENT.
521521
await expect(
522-
validatePath(requestedFile, allowedDirs),
522+
validatePath(requestedFile, allowedDirs, "read"),
523523
).rejects.toThrow("Access denied - path outside allowed directories");
524524
});
525525

@@ -529,24 +529,24 @@ describe("Lib Functions", () => {
529529
async () => ({ dev: 1n, ino: ++ino }) as BigIntStats,
530530
);
531531
await expect(
532-
validatePath(requestedFile, allowedDirs),
532+
validatePath(requestedFile, allowedDirs, "read"),
533533
).rejects.toThrow("Access denied - path outside allowed directories");
534534
});
535535

536536
it("refuses when a directory cannot be listed", async () => {
537537
foldingLstat();
538538
mockReaddirNames.mockRejectedValue(new Error("EACCES readdir"));
539539
await expect(
540-
validatePath(requestedFile, allowedDirs),
540+
validatePath(requestedFile, allowedDirs, "read"),
541541
).rejects.toThrow("Access denied - path outside allowed directories");
542542
});
543543

544544
it("still refuses a name that only folds onto part of an allowed directory", async () => {
545545
foldingLstat();
546546
const parentOnly = win ? "C:\\USERS\\x.txt" : "/HOME/x.txt";
547-
await expect(validatePath(parentOnly, allowedDirs)).rejects.toThrow(
548-
"Access denied - path outside allowed directories",
549-
);
547+
await expect(
548+
validatePath(parentOnly, allowedDirs, "read"),
549+
).rejects.toThrow("Access denied - path outside allowed directories");
550550
});
551551
});
552552
});

0 commit comments

Comments
 (0)