Release walkthrough ·

What Changed Between Filesystem MCP 2.1.0 and 2.2.0?

Version 2.2.0 of @modelcontextprotocol/server-filesystem was published to npm on November 4, 2026. Valyd's static comparison against 2.1.0 records two new write-capable tools, three input-schema changes and a FAIL verdict. This is what that evidence shows, and what it does not.

Tools
14 → 16
Added
2 (both write)
Removed
0
Input-schema changes
3
Static verdict
FAIL
Human review
Pending

Open the full comparison

What Valyd does

Valyd tracks how the interfaces of MCP servers change between releases. For each pinned release it launches the server over stdio, records the interface the server advertises (tool names, descriptions, input and output schemas, and tool annotations) and compares consecutive releases with Modelara's static analysis. Tools are discovered but never called, and no model is involved. Published records are not rewritten. The methodology describes the process in full.

What the comparison observes

The comparison was analyzed on November 5, 2026 with Modelara v0.1.8. The 2.1.0 interface has 14 tools and the 2.2.0 interface has 16. No tool was removed and no output schema changed. The comparison records:

  • 2 added tools, append_file and copy_file. Both declare a write effect, and each produces a FAIL finding.
  • 3 input-schema changes, to directory_tree, read_file and read_text_file. Each produces a REVIEW finding.
  • 3 description changes, to directory_tree, edit_file and search_files.
  • 10 annotation changes: ten read-only tools now declare idempotentHint: true; the value recorded for 2.1.0 is false.

Counting the overlaps, 11 of the 14 tools present in both releases have at least one recorded change. That is 2 FAIL, 3 REVIEW and 13 INFO findings in total. The comparison also records the interface fingerprint of each release and the npm integrity value of each package, so you can check that the release you install is the one that was analyzed.

The two added write-capable tools

append_file

Takes a required path and content. Its description says it appends text to the end of a file, creates the file if it does not exist, never changes existing content, adds no newline, and works only within the server's allowed directories. Its annotations declare readOnlyHint: false, destructiveHint: false, idempotentHint: false and openWorldHint: false.

copy_file

Takes a required source and destination. Its description says it copies one regular file without reading its content into the conversation, keeps permissions and modification time, does not copy directories, fails rather than overwrites when the destination exists, and requires both paths to be within allowed directories. Its annotations declare readOnlyHint: false, destructiveHint: false, idempotentHint: true and openWorldHint: false.

Why they matter

The 2.1.0 interface could already change files: write_file, edit_file and move_file declare destructive effects, and create_directory declares a write effect. So 2.2.0 does not give the server write access for the first time. It gives an agent two more operations, each with its own semantics. For example, append_file can create a new file, and copy_file can duplicate a file anywhere inside the allowed directories without the content passing through the model.

Both tools declare themselves non-destructive. That is the server's own description of itself, taken from its annotations. Valyd did not call either tool to confirm it.

The three input-schema changes

directory_tree
New optional property depth: an integer greater than 0 that limits how many levels are read. Only path remains required. Calls that omit depth still request the whole tree.
read_file
head and tail change from number to integer, with a new minimum of 0 and maximum of 9007199254740991 (253 − 1).
read_text_file
The same change to head and tail.

In the 2.2.0 schema, a negative or fractional head or tail is no longer a valid argument. Under the 2.1.0 schema it was valid. Whether the server rejected such values at runtime before, or does now, was not tested: this is a change to the declared contract. read_file is marked deprecated in favour of read_text_file in both releases.

Description and annotation changes

These are INFO findings, but descriptions are what a model reads when it chooses a tool. In 2.2.0, search_files states that it matches file and directory names, not file content, and that matching is case-sensitive and relative to path. edit_file now documents how matches are found, that edits apply in order, and that nothing is written if any edit fails to match. directory_tree describes the new depth behavior.

What to verify before upgrading

These checks follow from the recorded changes. None of them reports a known problem.

  1. Decide whether agents should see append_file and copy_file. If your client or gateway allowlists tools, the new tools need an explicit decision. If it exposes every tool a server offers, they will be available as soon as you upgrade.
  2. Re-check the allowed directories. Both new tools are limited to them, so they define where an agent can now create, append to and copy files.
  3. Validate stored or generated calls to read_file and read_text_file against the new head and tail schema, especially anywhere values are computed rather than written by hand.
  4. Spot-check tool selection. The new tools and the rewritten search_files and edit_file descriptions can change which tool a model picks for a task.
  5. Pin and verify the package. Install 2.2.0 exactly and compare its npm integrity value with the one recorded in the comparison's evidence.
  6. Run your own workflows against 2.2.0. A static comparison cannot tell you whether your agent's behavior changed.

Why a static FAIL is not proof of a vulnerability or a failure

The FAIL comes from one policy rule: a new tool whose declared effect is anything other than read is FAIL until someone approves it. Two new tools declare a write effect, so the comparison is FAIL. That is all the verdict asserts.

  • No tool was called. The verdict describes the declared interface, not runtime behavior. It is not evidence of a vulnerability, an exploit, a crash or a broken integration.
  • Effects come from annotations. MCP tool annotations are hints supplied by the server. Valyd records them as declared and does not verify them.
  • It is not a security score. It describes this version comparison, not the overall safety of the server or its maintainers' work.
  • Human review is pending. No reviewer decision is recorded for this comparison, and the page says so.

In practice, FAIL means that this upgrade gives agents new authority, so a person should decide whether to accept it.

How to inspect the full comparison

The Filesystem MCP 2.1.0 → 2.2.0 comparison shows everything this article is based on:

  • What changed, tool by tool: every changed tool, with property-level schema differences. Select Added tools or Input-schema changes to filter the list, and link to one tool directly, for example #tool-copy_file or #tool-read_text_file. Each changed tool can show its exact JSON from the published snapshots.
  • Evidence and provenance: the analyzer version, interface fingerprints, npm integrity values and links to the exact published files.
  • Interface findings: all 18 findings, grouped by severity.

The Filesystem MCP release history lists the earlier comparisons and the server's current capability surface.

How to copy an upgrade review

Every comparison page can produce a Markdown upgrade review for an issue, pull request or change ticket. It contains the verdict, the human-review status, the analyzer version, a summary, the notable changes and a checklist of recommended checks.

  1. Open the comparison page.
  2. Select Copy Upgrade Review to copy the Markdown, or Download Markdown to save it as valyd-upgrade-review-filesystem-2.1.0-to-2.2.0.md.
  3. If clipboard access is blocked or JavaScript is off, open View the upgrade review as Markdown and copy the text yourself.

The review is built from the published evidence. It lists possible effects and checks, and states that none of them is a confirmed incident.

What this comparison cannot tell you

  • Whether your agents behave differently with 2.2.0. That needs behavioral tests on your own tasks.
  • Whether the server's runtime behavior matches its annotations and descriptions.
  • Anything outside the advertised MCP interface, such as dependencies or internal implementation changes.
  • Anything about HTTP transport. Valyd currently inspects MCP over stdio.

See the evidence

The full comparison, with every finding, tool-level diff and provenance record.