Skip to content

Commit 84b412b

Browse files
authored
Merge pull request #5315 from modelcontextprotocol/v2/feat/5226-filesystem-hard-link-count
feat(filesystem): report the hard-link count in get_file_info and document hard links (#5226)
2 parents 48a0924 + 15f16b9 commit 84b412b

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
@@ -539,6 +539,7 @@ describe("Lib Functions", () => {
539539
isDirectory: () => false,
540540
isFile: () => true,
541541
mode: 0o644,
542+
nlink: 2,
542543
};
543544

544545
mockFs.stat.mockResolvedValueOnce(mockStats as Stats);
@@ -553,6 +554,7 @@ describe("Lib Functions", () => {
553554
isDirectory: false,
554555
isFile: true,
555556
permissions: "644",
557+
hardLinks: 2,
556558
});
557559
});
558560

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

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1943,6 +1943,7 @@ describe("get_file_info", () => {
19431943
"isDirectory",
19441944
"isFile",
19451945
"permissions",
1946+
"hardLinks",
19461947
]);
19471948
expect(lines[0]).toBe("size: 5");
19481949
expect(lines[4]).toBe("isDirectory: false");
@@ -1955,6 +1956,16 @@ describe("get_file_info", () => {
19551956
expect(lines[2]).toMatch(/^modified: \w{3} \w{3} \d{2} \d{4} /);
19561957
});
19571958

1959+
it("reports a file's hard-link count (#5226)", async () => {
1960+
const file = path.join(dir, "linked.txt");
1961+
await fs.writeFile(file, "shared");
1962+
const info = async () =>
1963+
textOf(await call(client, "get_file_info", { path: file }));
1964+
expect(await info()).toContain("hardLinks: 1");
1965+
await fs.link(file, path.join(dir, "hardlink.txt"));
1966+
expect(await info()).toContain("hardLinks: 2");
1967+
});
1968+
19581969
it("reports a directory", async () => {
19591970
const text = textOf(await call(client, "get_file_info", { path: dir }));
19601971
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 {
@@ -421,6 +422,9 @@ export async function getFileStats(filePath: string): Promise<FileInfo> {
421422
isDirectory: stats.isDirectory(),
422423
isFile: stats.isFile(),
423424
permissions: stats.mode.toString(8).slice(-3),
425+
// The link count: more than 1 means a file has other names, possibly
426+
// outside the allowed directories, that a write here also changes.
427+
hardLinks: stats.nlink,
424428
};
425429
}
426430

‎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)