ai-filesystem-mcp

Your AI agent's Edit isn't atomic. This MCP makes it so.

A single-tool MCP server for atomic multi-file changes with automatic

rollback — built for Claude Code, Codex CLI, Cursor agents, and other modern

coding agents.

Those agents ship with excellent built-in tools for reading, writing,

searching, editing, and shell. They do not ship with a primitive for

**"apply these N file operations as one transaction; if any of them fail,

revert everything."** That is the one and only thing this MCP provides.

The tool

`transaction` — apply a batch of file operations atomically.

{
  "name": "transaction",
  "arguments": {
    "operations": [
      { "type": "create", "path": "src/feature.ts",  "content": "..." },
      { "type": "write",  "path": "src/index.ts",    "content": "..." },
      { "type": "update", "path": "src/lib/util.ts",
        "updates": [{ "oldText": "foo()", "newText": "foo(arg)" }] },
      { "type": "move",   "path": "src/old.ts", "destination": "src/legacy/old.ts" },
      { "type": "delete", "path": "src/dead.ts" }
    ],
    "rollbackOnError": true
  }
}

If operation 4 fails, operations 1-3 are restored from backup before the call

returns. If everything succeeds, backups are cleaned up.

Operation kinds

Why one tool

Earlier 2.x versions shipped 39 commands: file I/O, search, git, code

analysis, shell, archives, diffs, metadata, encryption, file watcher.

Modern coding agents already do all of that better with their own

Read / Edit / Write / Grep / Glob / Bash tools — wrapping those in MCP

only adds latency and a new failure surface.

What an agent's `Edit` cannot do is treat several file changes as one

unit of work. If op 4 of 5 fails, ops 1-3 are already on disk. Until

the agent grows a real transaction primitive, that gap is filled

externally — which is the entire job of this server.

When you actually need this

You probably don't need it for a typical "fix this bug" turn. You do

need it when a single logical change must touch several files together:

• DB migration: schema file + matching ORM model + matching test

fixtures must all land or all revert.

• Cross-cutting rename / refactor that spans many files and would

half-apply if the agent crashes or runs out of context mid-stream.

• Generated-code updates where the generator output and the hand-edited

glue must stay in sync.

• Config + corresponding code change (e.g. routing table entry +

handler), where the half state is broken.

If your edit fits in one file, just use the agent's `Edit`. If it

fits in one shell command, just use `Bash`. Reach for `transaction`

only when "all or nothing" actually matters.

Install

Requires Node.js ≥ 18.

npm install -g ai-filesystem-mcp

Or from source:

git clone https://github.com/proofmath-owner/ai-filesystem-mcp.git
cd ai-filesystem-mcp
npm install
npm run build
node dist/index.js

Configure (Claude Code / Codex CLI / any MCP client)

{
  "mcpServers": {
    "ai-filesystem": {
      "command": "node",
      "args": ["/absolute/path/to/ai-filesystem-mcp/dist/index.js"]
    }
  }
}

Speaks stdio JSON-RPC. No network ports.

Trust model

Runs locally beside a trusted AI agent as the user that started it. There is

no path sandbox; the trust boundary is your machine. Do not expose to

untrusted clients.

Development

npm install
npm run dev      # tsx watch on src/index.ts
npm run build    # tsc -> dist/
npm run lint
npm run format

`tsc` errors fail the build. No `tsc || true`.

License

MIT