Skip to content

Latest commit

 

History

History
143 lines (72 loc) · 31.1 KB

CHANGELOG.md

File metadata and controls

143 lines (72 loc) · 31.1 KB

@modelcontextprotocol/server-filesystem

2.3.0

Minor Changes

  • #5451 b766bc2 @cliffhall - 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, including moving a directory that contains one, and 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. Each read-only directory must exist when the server starts, or it refuses to start. list_allowed_directories names the read-only directories.

Patch Changes

  • #5475 2a73097 @cliffhall - Describe every tool input property in tools/list (#3669). Every filesystem path argument now says how it is resolved and that it must stay inside the allowed directories, and excludePatterns says how its globs match (which differs between directory_tree and search_files). The memory server's top-level array arguments, and the everything server's resourceType, gain descriptions, and get-resource-reference's resourceId no longer claims to fetch only text resources.

  • #5446 92f03ec @cliffhall - search_files now reads excludePatterns the same way directory_tree does: a bare name such as "node_modules" excludes an entry of that name at any depth and the whole subtree below it, instead of only one directly under the searched path. Wildcard patterns keep their meaning, and an excluded directory is still never resolved or read. Thanks to @xubenqiang for the prototype fix.

  • #5450 39c66a4 @cliffhall - On Windows, refuse paths that name an NTFS alternate data stream (file.txt:stream, file.txt::$DATA): a colon anywhere but the drive-letter prefix now fails with "Access denied - NTFS alternate data stream paths are not supported" instead of letting the tools read or write data no directory listing shows. POSIX hosts are unaffected, since a colon is an ordinary character in a file name there. Thanks to @andreiminca, whose #4523 prototyped the check.

  • #5447 aef22c8 @cliffhall - edit_file: an oldText of whole lines that ends with a newline now matches when only indentation differs, keeping the file's indentation; the trailing newline ends the last line instead of adding an empty one.

  • #5448 db2a4fc @cliffhall - A write into a directory that does not exist (write_file, append_file, move_file, copy_file) now fails with Parent directory does not exist: <directory> instead of a raw chdir error that showed the server's working directory. Any other failure to enter a directory names only that directory.

  • #5458 03891ce @cliffhall - On Windows, refuse paths with a component that is a reserved device name (CON, PRN, AUX, NUL, COM1-COM9, LPT1-LPT9, in any case and with or without an extension) or that ends in a dot or a space (file.txt., file.txt ), with "Access denied - Windows reserved device names ... are not supported" or "Access denied - Windows path components ending in a dot or a space are not supported". Windows opens the device instead of a file in the allowed directory, and strips trailing dots and spaces so the name refers to a different file. . and .. components are not affected, and POSIX hosts are unaffected.

  • #5456 e7b956e @cliffhall - An excludePatterns glob ending in /**, such as **/node_modules/**, now also excludes the directory it names in search_files and directory_tree. Before, the directory itself was still resolved and read, search_files could return it, and directory_tree listed it as an empty directory; now the whole subtree is pruned before it is touched.

  • #5516 f3f636d @cliffhall - Anchor read tools to the validated file, as write tools are, and pin the source of a same-device move_file to the entry that was validated. A FIFO, socket or device is refused rather than read.

  • #5460 5bfe0ae @cliffhall - The list_directory and list_directory_with_sizes descriptions now say when to use each one and name the other: list_directory for the names directly inside a path (and directory_tree for a recursive view), list_directory_with_sizes when sizes matter, sorted by name or by size, largest first, with the totals at the end.

2.2.0

Minor Changes

  • #5395 99ba0c6 @cliffhall - Add a --confine-roots command-line flag. With it, a 2025-era client's Roots can narrow the command-line directories but never replace or widen them: a root inside a command-line directory is allowed, a root containing one is narrowed to it, and a root outside all of them is ignored and logged. Without the flag, Roots replace the command-line directories as before.

  • #5359 ea2997b @cliffhall - Add a --read-only command-line flag. With it the server registers only the tools annotated readOnlyHint: true, so every tool that writes (such as write_file and edit_file) is not listed and cannot be called, on both protocol eras and whether the directories come from the command line or a client's Roots. -- now ends the options, so a directory named like an option can still be given after it.

  • #5376 af8a01b @cliffhall - Add an append_file tool that appends text to the end of a file, exactly as given, creating the file if it does not exist (#1208).

  • #5385 65e68d3 @cliffhall - Add a copy_file tool that copies one regular file to a new location, keeping its permissions and modification time, and never overwrites an existing destination (#519).

  • #5388 3a2e1fd @cliffhall - Add an optional depth parameter to directory_tree that limits how many levels the tree descends; omitted, the whole tree is returned as before (#1077).

  • #5368 3f173d6 @cliffhall - Expose files in the allowed directories as MCP resources through a file://{+path} resource template, so a client can read a file with resources/read (text or a base64 blob by MIME type), confined to the allowed directories exactly as the tools are. resources/list stays empty, so the server never enumerates the disk.

Patch Changes

  • #5390 6017ed3 @cliffhall - Log the effective allowed directories to stderr, with their source, at startup and whenever they change: from the command line, or from the client's Roots (saying whether those replaced the command-line directories), or none, with why every path is now refused. Previously the server logged only a count of valid Roots.

  • #5426 81ca196 @cliffhall - Move minimatch to ^11.0.4. Every 10.x release is affected by GHSA-g3hv-75wg-m249 (denial of service through glob-part amplification), and the search_files patterns and the excludePatterns of search_files and directory_tree reach it from the client. The fix is outside the old ^10.0.1 range, so neither a fresh install nor npm update could pick it up.

  • #5380 d665e43 @cliffhall - Report a dangling symlink as a broken symlink. A request through a symlink whose target does not exist is still refused, but the error now names the symlink instead of saying its parent directory, which exists, does not.

  • #5379 6575d87 @cliffhall - edit_file: when an edit's oldText matches nowhere, the error now names which edit failed, states the matching rules, and quotes the closest lines of the file with line numbers, plus the first differing line JSON-quoted so a whitespace difference is visible. The tool description now states the matching rules too. What matches is unchanged.

  • #5384 eed581e @cliffhall - Expand ~\ to the home directory on Windows, in command-line directories, request paths and client Roots alike, as ~/ already is. On POSIX a backslash is a filename character, so ~\name there still names a literal file.

  • #5377 fbddfb0 @cliffhall - read_text_file (and the deprecated read_file) now treats head: 0 or tail: 0 as a request for zero lines and returns empty text, instead of the whole file. head and tail accept only non-negative integers, and head with tail is rejected even when either is 0.

  • #5353 1a7b9f9 @cliffhall - Every read-only tool (read_file, read_text_file, read_media_file, read_multiple_files, list_directory, list_directory_with_sizes, directory_tree, search_files, get_file_info and list_allowed_directories) now also sets idempotentHint: true and destructiveHint: false, so all four tool annotation hints are explicit on every tool and a client never falls back to the spec's defaults (destructive, not idempotent).

  • #5383 22ce3e5 @cliffhall - Keep an allowed directory's name exactly as the file system spells it. A command-line directory, or a client Root's realpath, whose name ends in a space or a quote was trimmed, so the server allowed the sibling directory without that suffix (and refused the directory that was actually given).

  • #5351 13c781a @cliffhall - Drop the unused glob runtime dependency: nothing in the server imported it (pattern matching goes through minimatch), so installing the server no longer downloads glob and its own dependencies.

  • #5378 9192ea3 @cliffhall - list_directory_with_sizes no longer reports an entry it could not stat (unreadable, a dangling symlink, removed mid-listing, or a symlink leaving the allowed directories) as 0 B. Such an entry is shown with size unknown, sorts last by size, and is left out of the combined size, which notes how many files it excludes.

  • #5367 4441e23 @cliffhall - The search_files description now says plainly that it finds files and directories by name, not by content, and that its glob is matched case-sensitively against each entry's path relative to path (not the working directory), so a model no longer reaches for it to grep file contents.

  • #5355 135a925 @cliffhall - search_files no longer drops a subdirectory it cannot read without saying so. It still returns the matches it found, and now follows them with a note that the search is incomplete, listing each unreadable directory and its error code. Paths outside the allowed directories are still skipped silently, and an unreadable starting directory is still an error.

2.1.0

Minor Changes

  • #5315 15f16b9 @cliffhall - 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).

Patch Changes

  • #5326 f3e5d36 @cliffhall - 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.

  • #5319 b57b04c @cliffhall - A path that spells an allowed directory's own name in a letter case matching neither the configured nor the on-disk spelling (for example C:\Work\CASETEST\file.txt for an allowed C:\Work\CaseTest) is no longer refused on a case-insensitive file system (Windows NTFS, default macOS APFS). The request is mapped onto the allowed directory only where the file system confirms, component by component, that both spellings name one entry, so a sibling directory differing only in case is still refused on a case-sensitive directory.

  • #5325 322dcf0 @cliffhall - write_file and edit_file compare the file they opened against the one they checked as BigInt stats, so a Windows file id above 2^53 is compared exactly rather than rounded. Where a path-based stat on Windows reports no device (libuv < 1.51.0, the Node 23 line), the overwrite no longer refuses every existing file: the file must instead match on inode, size and modification time, and any difference still refuses.

  • #5317 d98c856 @cliffhall - 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.

  • #5318 dfe9187 @cliffhall - A Root or command-line directory whose realpath fails once is now retried after a short delay instead of being lost for the life of the process. On Windows the first native realpath right after subst maps a drive can fail before the mapping is visible; a Root was dropped as inaccessible, and a command-line directory lost its resolved spelling, so every request on the drive was refused.

  • #5324 1002969 @cliffhall - read_text_file with head no longer leaves a \r at the end of each line of a CRLF file. Like tail, it returns lines normalized to LF, including a \r\n pair split across a read chunk. LF output is unchanged.

  • #5316 30afc34 @cliffhall - read_text_file with tail no longer returns one line too few when the file ends with a newline: the final newline ends the last line instead of counting as an empty one, for LF and CRLF files and for files longer than one read chunk. Like head, the result carries no trailing newline.

  • #5322 f438a62 @cliffhall - move_file now moves a regular file between allowed directories on different filesystems (mounts, disks or shares), where it used to fail with EXDEV: it copies the file to a newly created destination, keeping its permissions and modification time, then removes the source, and removes a partial copy if anything fails. A directory still cannot be moved across filesystems, and now fails with an error that says so.

2.0.1

Patch Changes

2.0.0

Major Changes

  • #5118 5b400a6 @cliffhall - Move to the TypeScript SDK v2 packages (@modelcontextprotocol/server) from @modelcontextprotocol/sdk 1.x (#4856). Breaking for clients: the server now requires Node.js 24 or later; over stdio, a single incoming JSON-RPC message larger than 10 MiB now closes the connection (the SDK v2 default read-buffer cap; SDK 1.x buffered without a limit); an unknown tool name is rejected with JSON-RPC error -32602 instead of returning an isError result; error messages no longer carry the MCP error <code>: prefix, and input-validation messages name the field first (field: message); and tools no longer advertise execution.taskSupport.

Minor Changes

  • #5131 419200b @cliffhall - Serve the 2026-07-28 protocol revision alongside the 2025 era on stdio, through the SDK's serveStdio entry (#4852). A 2026-07-28 connection has no initialize and no server-to-client roots/list, and Roots is deprecated as of that revision, so the command-line directories are its whole allow-list; a server started with none answers each tool call on such a connection with an error saying so. 2025-era clients keep the Roots behavior they had. The README now recommends command-line directories over Roots (#4844).

1.0.0

The first semantic version, resuming semver after the date-stamped releases (last 2026.8.31). It describes everything since 2026.8.31, and is the last release of the legacy-era server, on the 1.x MCP SDK.

Patch Changes

  • #4970 3a63f52 @cliffhall - Internal: the server is now built by a createServer() factory in server.ts, and index.ts starts it over stdio only when run as the bin, with each server instance holding its own allowed directories. No change to the tools, their results, or how the allowed directories are resolved from arguments and Roots.

  • #5011 d8ebdbe @cliffhall - edit_file keeps a file's line endings: a CRLF file is written back with CRLF instead of being converted to LF. When oldText has no exact match and the whitespace-tolerant matcher is used, each replacement line now takes the indentation of the file line it replaces, shifted by its indentation relative to the matching oldText line, instead of only the first line being reindented.

  • #5022 7dc802f @cliffhall - write_file and edit_file now overwrite an existing file in place instead of renaming a temp file over it, so the file keeps its inode, creation time (birthtime), hard links and permission bits (#4512), and an overwrite no longer fails with EPERM on Windows when another process holds the file open (#3199). A symlink swapped in after the path was validated is still refused rather than written through, now by an O_NOFOLLOW open (on POSIX) and a check that the opened file is the one validated (on every platform). The overwrite is no longer crash-atomic. A read-only file is now refused (EACCES, or EPERM on Windows) instead of being replaced, since writing in place opens the file itself for writing.

  • #5025 2309e08 @cliffhall - Tool calls now wait for the client's initial roots before checking paths, so a call sent right after connecting is no longer refused with "Access denied" (#3204). A server started with no directories, connected to a client without Roots support, now fails visibly: it logs the reason, closes the connection and exits with status 1, instead of staying up and refusing every call (#4992).

  • #5030 5c04d74 @cliffhall - Every tool's input and output schema in tools/list now declares "$schema": "https://json-schema.org/draft/2020-12/schema" instead of draft-07, so clients that validate tool schemas strictly against JSON Schema 2020-12 no longer reject every tool. The schemas are otherwise unchanged.

  • #5087 09edf63 @cliffhall - Require @modelcontextprotocol/sdk 1.31.0 or later (was ^1.30.0), so an install can no longer resolve an SDK version affected by GHSA-6qxp-vccf-f47h. The advisory concerns the SDK's OAuth client, which this server does not use.

  • #5010 fd4dff7 @cliffhall - On Windows, a UNC share root given as an allowed directory (\\server\share or \\server\share\) now admits the files and subdirectories under it. Before, only the share root itself was accessible and every path below it was refused. Sibling shares such as \\server\share-evil are still refused.

  • #5009 f621c75 @cliffhall - Paths that differ from the names on disk only in Unicode form now resolve (#1970). An NFC spelling of an allowed directory whose name is stored NFD (macOS "Capture d’écran", Japanese dakuten) is no longer refused as outside the allowed directories, and a request that spells a U+202F or U+00A0 in a name as a plain space (the macOS screenshot "Screenshot … at 2.40.40 PM.png") finds the file instead of failing with ENOENT. The exact spelling still wins when it exists, and a name matching two entries is refused as ambiguous.

  • #5094 bea1c9a @cliffhall - A roots/list_changed update that leaves no valid root now revokes access once the client's roots are in force, instead of keeping the previous allowed directories, so a client that withdraws its roots withdraws the server's access too (#5094). Every path is then refused with "Access denied - no allowed directories" until the client exposes a root again. Before any root has been in force, such an update still keeps the command-line directories.

  • #5097 a13e809 @cliffhall - Overlapping roots refreshes now take effect in the order they started: when a client sends roots/list_changed again before the previous roots/list answer arrived (or while the initial roots are still loading), an answer that arrives after a newer refresh has started is discarded instead of overwriting it, so a stale answer can no longer undo a newer update such as a revocation (#5097).

  • #5101 3f6aaf4 @cliffhall - Tool calls that arrive while a roots/list_changed refresh is fetching the client's roots now wait for it, as they already did for the initial roots, so a call can no longer reach a root the client has just withdrawn while the answer is pending (#5101).