Skip to content

Commit 15f16b9

Browse files
cliffhallclaude
andcommitted
feat(filesystem): report the hard-link count in get_file_info (modelcontextprotocol#5226)
get_file_info gains a hardLinks line (nlink from fs.stat), so a client can see that a file has other names before changing it. The README now says allowed-directory checks are path-based, and that writing or editing a hard-linked file changes it at every name. Co-Authored-By: Claude Opus 5.5 <[email protected]> Signed-off-by: cliffhall <[email protected]>
1 parent 66e3dec commit 15f16b9

6 files changed

Lines changed: 34 additions & 1 deletion

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": minor
3+
---
4+
5+
`get_file_info` now reports a file's hard-link count as a `hardLinks: <n>` line, after `permissions`, so a client can see that a file has other names before changing it. The README now says that allowed-directory checks are path-based, and that overwriting or editing a file that is hard-linked from elsewhere changes it at every name ([#5226](https://github.com/modelcontextprotocol/servers/issues/5226)).

‎src/filesystem/README.md‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -107,6 +107,14 @@ The server's directory access control follows this flow:
107107
time, hard links and permissions (`edit_file` writes the same way). The
108108
overwrite is not crash-atomic: a crash mid-write can leave the file partly
109109
written. A read-only file is refused rather than replaced
110+
- Allowed-directory checks are path-based: they check the name you pass,
111+
not every name the file has. A hard link is a real name of the same file,
112+
so when a file inside an allowed directory is also hard-linked from
113+
somewhere else (pnpm, for example, hard-links package files into
114+
`node_modules` from its store), overwriting or editing it changes the
115+
content at every name, inside the allowed directories or not.
116+
`get_file_info` reports a file's `hardLinks` count; more than 1 means
117+
the file has other names
110118

111119
- **edit_file**
112120
- Make selective edits using advanced pattern matching and formatting
@@ -185,6 +193,9 @@ The server's directory access control follows this flow:
185193
- Access time
186194
- Type (file/directory)
187195
- Permissions
196+
- Hard-link count (`hardLinks`): the number of names the file has. More
197+
than 1 means a write through this name changes the file at its other
198+
names too (see `write_file`)
188199

189200
- **list_allowed_directories**
190201
- List all directories the server is allowed to access

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

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -443,6 +443,7 @@ describe("Lib Functions", () => {
443443
isDirectory: () => false,
444444
isFile: () => true,
445445
mode: 0o644,
446+
nlink: 2,
446447
};
447448

448449
mockFs.stat.mockResolvedValueOnce(mockStats as Stats);
@@ -457,6 +458,7 @@ describe("Lib Functions", () => {
457458
isDirectory: false,
458459
isFile: true,
459460
permissions: "644",
461+
hardLinks: 2,
460462
});
461463
});
462464

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

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1888,6 +1888,7 @@ describe("get_file_info", () => {
18881888
"isDirectory",
18891889
"isFile",
18901890
"permissions",
1891+
"hardLinks",
18911892
]);
18921893
expect(lines[0]).toBe("size: 5");
18931894
expect(lines[4]).toBe("isDirectory: false");
@@ -1900,6 +1901,16 @@ describe("get_file_info", () => {
19001901
expect(lines[2]).toMatch(/^modified: \w{3} \w{3} \d{2} \d{4} /);
19011902
});
19021903

1904+
it("reports a file's hard-link count (#5226)", async () => {
1905+
const file = path.join(dir, "linked.txt");
1906+
await fs.writeFile(file, "shared");
1907+
const info = async () =>
1908+
textOf(await call(client, "get_file_info", { path: file }));
1909+
expect(await info()).toContain("hardLinks: 1");
1910+
await fs.link(file, path.join(dir, "hardlink.txt"));
1911+
expect(await info()).toContain("hardLinks: 2");
1912+
});
1913+
19031914
it("reports a directory", async () => {
19041915
const text = textOf(await call(client, "get_file_info", { path: dir }));
19051916
expect(text).toContain("isDirectory: true");

‎src/filesystem/lib.ts‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,7 @@ interface FileInfo {
2121
isDirectory: boolean;
2222
isFile: boolean;
2323
permissions: string;
24+
hardLinks: number;
2425
}
2526

2627
export interface SearchOptions {
@@ -312,6 +313,9 @@ export async function getFileStats(filePath: string): Promise<FileInfo> {
312313
isDirectory: stats.isDirectory(),
313314
isFile: stats.isFile(),
314315
permissions: stats.mode.toString(8).slice(-3),
316+
// The link count: more than 1 means a file has other names, possibly
317+
// outside the allowed directories, that a write here also changes.
318+
hardLinks: stats.nlink,
315319
};
316320
}
317321

‎src/filesystem/server.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -777,7 +777,7 @@ export function createServer(
777777
description:
778778
"Retrieve detailed metadata about a file or directory. Returns comprehensive " +
779779
"information including size, creation time, last modified time, permissions, " +
780-
"and type. This tool is perfect for understanding file characteristics " +
780+
"type and hard-link count. This tool is perfect for understanding file characteristics " +
781781
"without reading the actual content. Only works within allowed directories.",
782782
inputSchema: jsonSchema2020(GetFileInfoArgsSchema.shape),
783783
outputSchema: jsonSchema2020({ content: z.string() }),

0 commit comments

Comments
 (0)