atomic-writer-mcp

A secure and atomic file operation service implemented as an MCP (Model Context Protocol) server. This server provides safe, transactional file operations through the MCP protocol.

Have you ever experienced an LLM (Large Language Model) accidentally deleting your content while trying to help? It's a common and frustrating experience - the AI confidently makes changes to your files, only to realize afterwards that it just deleted important content.

I built this system after a particularly painful experience with my Obsidian notes. While working on an integration that allowed AI to help manage my notes, I discovered that sometimes it would inadvertently wipe out half of a note's content without realizing the impact of its actions.

This led me to develop the Atomic Writer - a safety-first file operation system that prevents destructive operations by design:

• New content can only be appended, never overwritten
• Files can only be created if they don't exist and are empty
• All operations are tracked and can be rolled back
• File integrity is constantly monitored and verified

While originally built to protect against unintended AI modifications, the Atomic Writer can be used in any scenario where file safety is paramount. It's perfect for:

• AI integrations that need to modify files
• Collaborative editing systems
• Critical data management
• Any application where preventing accidental data loss is essential

• Create and write files with content verification
• Read files with integrity checks
• Move files to new locations atomically
• Safe file deletion with trash directory
• Append and prepend content to files

• Replace first or all occurrences of text
• Insert content at specific line numbers
• Delete specific lines
• Read specific lines or context around search terms

• All operations are atomic and journaled
• File integrity verification
• Automatic backup before modifications
• Trash directory for deleted files
• Lock management to prevent conflicts
• Operation rollback capability
• Automatic external file integration:
  • Detects files created outside the system
  • Initializes integrity tracking on first access
  • Seamless integration with existing operations

• System status monitoring
• File operation history
• Lock management
• File recovery from journal
• Integrity verification with external file support
• Automatic tracking initialization for untracked files

1. Clone the repository
2. Install dependencies: npm install
3. Build the project: npm run build
4. Configure the server in your MCP host's configuration

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "atomic-writer": {
      "command": "node",
      "args": [
        "/absolute/path/to/atomic-writer/build/index.js",
        "/absolute/path/to/base/directory"
      ]
    }
  }
}

Important: The second argument ("/absolute/path/to/base/directory") is required and specifies where the Atomic Writer will store and manage files. This directory will contain the .atomic-writer subdirectory with all the system files (journal, locks, etc.).

Alternatively, you can set the BASE_DIR environment variable instead of providing the second argument.

Location of config file:

• Windows: %APPDATA%\Claude\claude_desktop_config.json
• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

The server provides these MCP tools:

• write-file: Create new file or write to empty file
• read-file: Read file with integrity verification
• delete-file: Move file to trash directory
• move-file: Atomically move/rename file
• append-content: Append content to file
• prepend-content: Prepend content to file

• replace-content: Replace first occurrence of text
• replace-all-content: Replace all occurrences of text
• insert-content-at-line: Insert content at line number
• delete-line: Delete specific line
• read-lines: Read specific line numbers
• read-around: Read lines around search term

• verify-integrity: Check file integrity and initialize tracking for external files
• get-status: Get system status
• recover-file: Recover from journal
• get-file-history: View operation history
• get-lock-status: Check file locks
• force-release-lock: Release stuck locks
• rollback-operation: Rollback changes

Operations return standardized error codes:

• FILE_NOT_FOUND: File does not exist
• INVALID_PATH: Path is invalid
• EMPTY_CONTENT: Content is empty
• LINE_OUT_OF_BOUNDS: Invalid line number
• FILE_LOCKED: File is locked
• INTEGRITY_ERROR: Checksum verification failed

base/
  ├── files/    # Managed files
  ├── journal/  # Operation journal
  ├── locks/    # File locks
  ├── trash/    # Deleted files
  └── temp/     # Temporary files

• npm run build: Build the TypeScript code
• npm run test: Run the test suite
• npm run lint: Run the linter

• All operations are atomic and journaled
• Files are protected with locks during operations
• Content integrity is verified with checksums
• Deleted files are moved to trash instead of permanent deletion
• Operations can be rolled back if needed
• External files automatically brought under integrity protection