AI导哈

原子文件操作服务

一个基于MCP协议的安全原子文件操作服务，提供事务性文件操作、内容完整性验证和操作回滚功能，适用于AI集成、协作编辑和关键数据管理等场景。

  • by vanzan01
  • TypeScript
  • 本地部署
  • 6 星标
  • 更新于
在 GitHub 查看 vanzan01/atomic-writer-mcp

使用说明

原子写入器MCP服务器

作为MCP（模型上下文协议）服务器实现的安全和原子文件操作服务。此服务器通过MCP协议提供安全的事务性文件操作。

动机

您是否曾遇到过LLM（大型语言模型）在尝试提供帮助时意外删除您的内容？这是一种常见而令人沮丧的体验——人工智能自信地对你的文件进行更改，但事后才意识到它只是删除了重要内容。

在经历了一段特别痛苦的黑曜石笔记之后，我建立了这个系统。在开发一个允许人工智能帮助管理我的笔记的集成时，我发现有时它会无意中抹去笔记内容的一半，而没有意识到其行为的影响。

这促使我开发了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 环境变量，而不是提供第二个参数。

配置文件的位置：

  • 窗户： %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:文件已锁定
  • 完整性_错误：校验和验证失败

目录结构

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：打开门楣

安全

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

相关 MCP