ai-filesystem-mcp: Instructions file for Claude Code

CLAUDE.md

Guidance for Claude Code when working inside this repo.

What this repo is

A one-tool MCP server. The tool is transaction: apply N file operations as one atomic batch with automatic rollback. That is the entire product surface.

It used to ship 39 commands (file I/O, search, git, code analysis, shell, archives, …) and that overlap with your built-in tools is exactly why the project was pared down. Everything but transaction was removed because you already have it.

The contract

TransactionCommand (src/commands/implementations/batch/TransactionCommand.ts) exposes an MCP tool with this shape — keep code, schema, and README aligned on any change:

type	Required	Behavior
create	path, content	New file; mkdir -p parent.
write	path, content	Overwrite existing file.
update	path, updates[]	For each {oldText, newText} apply String.replace in order.
move	path, destination	fs.rename.
delete	path	unlink for files, rm -r for directories.

rollbackOnError defaults to true. On failure, every operation that already executed is reverted from a backup taken before the batch ran.

Architecture

src/index.ts                    MCP stdio server entry
  └── core/ServiceContainer.ts  Minimal DI, registers TransactionService
src/commands/registry/          BaseCommand / CommandRegistry / CommandLoader
src/commands/implementations/batch/TransactionCommand.ts
src/core/services/batch/TransactionService.ts   on-disk backup + restore

~9 .ts files total. Keep it that way. No new tools without a very clear argument that the agent literally cannot do the thing on its own.

Conventions

• Every command extends BaseCommand (src/commands/base/BaseCommand.ts): implement validateArgs() + executeCommand(), register in CommandLoader.loadCommands().
• Services come from the container: context.container.getService<T>('transactionService').
• Errors: throw inside executeCommand; BaseCommand.execute formats them.
• Use execFile (not exec) with array args anywhere shell is needed.
• TS is strict-friendly. npm run build is plain tsc — do not reintroduce tsc || true.