Atomic Writer MCP Server

Atomic Writer MCP 服务

这是一个以 MCP（Model Context Protocol）服务形式实现的安全、原子化文件操作服务。该服务通过 MCP 协议提供安全的事务性文件操作。

动机

你是否遇到过大模型（LLM）在尝试提供帮助时意外删除内容？这是一种常见又令人沮丧的情况——AI 信心满满地修改文件，却事后才发现自己删除了重要内容。

我在一次特别痛苦的经历后开发了这个系统。当时我在使用 Obsidian 笔记，并开发一项集成功能，让 AI 帮我管理笔记。我发现，有时它会在没有意识到操作影响的情况下，无意间清除笔记中一半的内容。

这促使我开发了 Atomic Writer——一个以安全为先的文件操作系统，通过设计来防止破坏性操作：

• 新内容只能追加，不能覆盖
• 只有文件不存在或为空时，才能创建文件
• 所有操作都会被记录，并且可以回滚
• 持续监控并验证文件完整性

Atomic Writer 最初旨在防止 AI 意外修改文件，但也可用于任何将文件安全视为首要任务的场景。它非常适合：

• 需要修改文件的 AI 集成
• 协作编辑系统
• 关键数据管理
• 任何需要防止意外数据丢失的应用

功能

核心文件操作

• 创建文件并写入内容，同时验证内容
• 读取文件并检查完整性
• 以原子方式将文件移动到新位置
• 将文件安全地删除到回收目录
• 向文件追加内容或在文件开头插入内容

文本处理

• 替换文本的首次匹配项或所有匹配项
• 在指定行号插入内容
• 删除指定行
• 读取指定行或搜索词周围的上下文

安全功能

• 所有操作都是原子的，并会记录到日志
• 文件完整性验证
• 修改前自动备份
• 为已删除文件提供回收目录
• 锁管理，防止冲突
• 操作回滚能力
• 自动集成外部文件：
  • 检测在系统外创建的文件
  • 首次访问时初始化完整性跟踪
  • 与现有操作无缝集成

系统操作

• 系统状态监控
• 文件操作历史
• 锁管理
• 从日志恢复文件
• 支持外部文件的完整性验证
• 自动初始化未跟踪文件的跟踪

安装

1. 克隆仓库
2. 安装依赖：npm install
3. 构建项目：npm run build
4. 在 MCP 宿主的配置中配置服务

MCP 服务配置

将以下内容添加到你的 claude_desktop_config.json：

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

重要：第二个参数（"/absolute/path/to/base/directory"）是必需的，用于指定 Atomic Writer 存储和管理文件的位置。该目录将包含 .atomic-writer 子目录，其中存放所有系统文件（日志、锁等）。

或者，你也可以设置 BASE_DIR 环境变量，而不提供第二个参数。

配置文件位置：

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

可用工具

该服务提供以下 MCP 工具：

文件操作

• write-file：创建新文件或写入空文件
• read-file：读取文件并验证完整性
• delete-file：将文件移至回收目录
• move-file：以原子方式移动或重命名文件
• append-content：向文件追加内容
• prepend-content：在文件开头插入内容

文本操作

• replace-content：替换文本的首次出现位置
• replace-all-content：替换文本的所有出现位置
• insert-content-at-line：在指定行号插入内容
• delete-line：删除指定行
• read-lines：读取指定行号
• read-around：读取搜索词附近的行

系统工具

• verify-integrity：检查文件完整性，并为外部文件初始化跟踪
• get-status：获取系统状态
• recover-file：从日志中恢复
• get-file-history：查看操作历史
• get-lock-status：检查文件锁
• force-release-lock：释放卡住的锁
• rollback-operation：回滚更改

错误代码

操作会返回标准化的错误代码：

• FILE_NOT_FOUND：文件不存在
• INVALID_PATH：路径无效
• EMPTY_CONTENT：内容为空
• LINE_OUT_OF_BOUNDS：行号无效
• FILE_LOCKED：文件已锁定
• INTEGRITY_ERROR：校验和验证失败

目录结构

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

开发

• npm run build：构建 TypeScript 代码
• npm run test：运行测试套件
• npm run lint：运行代码检查工具

安全

• 所有操作都是原子性的，并会记录到日志
• 操作期间会通过锁保护文件
• 使用校验和验证内容完整性
• 删除的文件会移至回收站，而非永久删除
• 如有需要，可回滚操作
• 外部文件会自动纳入完整性保护