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