星战科技xingzhan.cloud
返回市场
原子写入器-mcp

原子写入器-mcp

作者：vanzan015 星标更新：2025-03-24
安装使用来源：spider==github.com

项目介绍

原子写入器MCP服务器

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

动机

你是否曾经遇到过大型语言模型在尝试帮助时意外删除了你的内容？这是一个常见且令人沮丧的经历——AI自信地对文件进行更改，事后才发现它刚刚删除了重要的内容。

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

这促使我开发了原子写入器——一个以安全第一设计的文件操作系统，防止破坏性操作：

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

虽然最初是为了防止意外的AI修改而构建的，但原子写入器可以在任何需要文件安全性的场景中使用。它适用于：

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

特性

核心文件操作

  • 创建和写入带有内容验证的文件
  • 带有完整性检查的读取文件
  • 原子地移动文件到新位置
  • 安全删除文件到回收站目录
  • 追加和前置内容到文件

文本操作

  • 替换第一次或所有出现的文本
  • 在特定行号插入内容
  • 删除特定行
  • 读取特定行或搜索词周围的上下文

安全特性

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

系统操作

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

安装

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

MCP服务器配置

添加到你的claude_desktop_config.json：

{
  "mcpServers": {
    "atomic-writer": {
      "command": "node",
      "args": [
        "/绝对路径/to/atomic-writer/build/index.js",
        "/绝对路径/to/基础目录"
      ]
    }
  }
}

重要：第二个参数（"/绝对路径/to/基础目录"）是必需的，并指定了原子写入器存储和管理文件的位置。该目录将包含.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: 校验和验证失败

目录结构

基础/
  ├── 文件/    # 管理的文件
  ├── 日志/  # 操作日志
  ├── 锁定/    # 文件锁定
  ├── 回收站/    # 已删除文件
  └── 临时/     # 临时文件

开发

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

安全

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