Atomic Writer MCP 服务器

一个安全且原子性的文件操作服务，以 MCP (模型上下文协议) 服务器的形式实现。该服务器通过 MCP 协议提供安全、事务性的文件操作。

动机

你是否经历过 LLM (大型语言模型) 在试图帮助你时意外删除你的内容？这是一个常见且令人沮丧的经历 - AI 自信地对你的文件进行更改，但事后才意识到它只是删除了重要的内容。

我构建这个系统是因为我在使用 Obsidian 笔记时的一次特别痛苦的经历。在开发一个允许 AI 帮助管理我的笔记的集成时，我发现有时它会无意中擦除一半的笔记内容，而没有意识到其行为的影响。

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

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

虽然最初是为了防止意外的 AI 修改而构建的，但 Atomic Writer 可以用于任何文件安全至关重要的场景。它非常适合：

• 需要修改文件的 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/    # 管理的文件
  ├── journal/  # 操作日志
  ├── locks/    # 文件锁
  ├── trash/    # 删除的文件
  └── temp/     # 临时文件

开发

• npm run build: 构建 TypeScript 代码
• npm run test: 运行测试套件
• npm run lint: 运行 linter

安全

• 所有操作都是原子性的并且被记录在日志中
• 文件在操作期间受到锁的保护
• 内容完整性通过校验和验证
• 删除的文件被移动到回收站而不是永久删除
• 如果需要，可以回滚操作
• 外部文件自动受到完整性保护