Atomic Writer MCP

🚀 Atomic Writer MCP Server

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

🚀 Quick Start

The Atomic Writer MCP Server is a secure and atomic file operation service. It offers safety and transactional capabilities for file operations via the MCP protocol, preventing accidental data loss and ensuring data integrity.

💡 Motivation

Have you ever had a large language model accidentally delete your content while confidently trying to help? This is a common and frustrating experience - an AI modifies a file with confidence, only to realize later that it has unexpectedly deleted important information.

I developed this system after a particularly painful experience: I encountered issues while using Obsidian notes. I was integrating a feature that allowed an AI to help manage my notes, and I found that sometimes it would inadvertently wipe out half of the note content without realizing the impact.

After that, I developed this system - Atomic Writer, a file operating system with security as its top priority, designed to prevent destructive operations:

• New content can only be appended, never overwritten.
• Files are only created if they do not exist and are empty.
• All operations are logged and can be rolled back.
• File integrity is continuously monitored and verified.

Although initially developed to prevent accidental modifications by AI, Atomic Writer can be used in any scenario where file security is required. It is well - suited for:

• AI integrations that need to modify files.
• Collaborative editing systems.
• Critical data management.
• Any application that needs to prevent accidental data loss.

✨ Features

Core Features

• Atomic Operations: All file operations are atomic, ensuring that they either succeed completely or do not occur at all.
• Integrity Check: Each file has a checksum verification to ensure the integrity and consistency of the content.
• Prevent Overwriting: New content can only be appended, avoiding accidental overwriting of existing data.
• Logging: Detailed operation logs support rollback and troubleshooting.

Security Features

• Locking Mechanism: Files are locked during operations to prevent interference from other processes.
• Trash Directory: Deleted files are not permanently deleted but moved to the trash directory.
• Temporary Files: All changes are first written to temporary files to ensure the security of the original file.

Supported Operations

• File creation
• File reading
• File updating
• File deletion
• Content replacement
• Content insertion
• Content deletion

📦 Installation

1. Clone the repository

   git clone https://github.com/yourusername/atomic-writer.git
   cd atomic-writer
   

2. Install dependencies

   npm install
   

3. Build the project (if using TypeScript)

   npm run build
   

4. Configure the MCP host

   • Add the following settings to your MCP configuration file:

     {
       "servers": {
         "atomic-writer": {
           "type": "MCP",
           "host": "localhost",
           "port": 3001,
           "path": "/api"
         }
       }
     }
     

💻 Usage Examples

Create a file

const writer = new AtomicWriter('localhost', 3001, '/api');
await writer.createFile('/notes/new-note.md', 'hello world');

Update file content

await writer.updateContent('/notes/example.md', 'new content');

Roll back operations

If an error occurs, you can roll back to a previous state through the logs:

writer.rollback('latest successful state');

🤝 Learning and Contribution

• Report issues: If you encounter any problems, please submit them in GitHub Issues.
• Contribute code: You are welcome to fork the repository and submit pull requests to help improve the system's functionality and performance.
• Expand documentation: If you have in - depth knowledge of a certain module or function, feel free to supplement and improve the documentation.

📄 License

This project is licensed under the MIT License. You are free to use and modify it, but you must retain the copyright notice.

With the Atomic Writer MCP Server, you can enjoy higher security and reliability when handling file operations. Whether it's personal notes, team collaboration, or critical data management, it can safeguard your files.