MCP Read File Server — AI skill for Claude Code

文件操作 MCP Server（加密软件环境明文读写）

简介

加密环境文件操作工具。当 Node.js 是加密软件白名单进程时，通过 fs 模块自动解密读写文件明文，替代 AI Agent 内置文件工具，解决加密环境下读到密文的问题。适用于任何支持 MCP 协议的 AI Agent。

最新版本：2.1.0（相对 1.0）

本节以仓库 `v1.0` 标签（包版本 `1.0.0`）为基线，汇总当前版本的变化，不再逐条保留中间版本的更新说明。

方面	1.0	2.1.0
文件写入	由 Node 直接读改写，依赖本机透明加密行为	统一暂存、备份、提交及终验；失败回滚，恢复失败保留 recoveryPath
加密策略	没有按原文件状态选择写入策略	auto 比较原文件的 Node 与外部读取视图：原明文继续验证明文，原受保护文件保留受控写入；新建文件不凭 Node 可读就自动加密
工具范围	8 个基础读写、搜索及目录工具	18 个工具，增加分页、列目录、文件查找、复制/移动/删除和 4 个策略诊断/管理工具
编辑准确性	单次字符串或正则替换	批量原子编辑、CRLF/LF 适配、BOM 保留、预览、预期匹配数和 hash 冲突保护
读取与性能	同步文件操作和基础搜索	异步 I/O、流式分页、有界输出；正则与字面量计算在可终止 worker 中执行；glob 累计预算并让出主线程
并发与异常	基础异常返回	跨实例路径/子树锁；目录逐文件校验；部分完成、源保留、回滚和清理错误分别报告
边界保护	主要依赖进程文件权限	可配置允许根、只读和禁删；识别真实路径/链接及受保护根；拒绝目录双向祖先重叠
分发与验证	本地脚本启动，无仓库测试套件	npm CLI 入口、模块化源码、结构化响应、回归/真实 stdio/Windows 适配测试及 CI；最低 Node.js 20

**本次重点修复**：原始明文文件经 MCP 编辑后出现加密内容，而 Node 读回正常、编辑器却显示密文。修复基于每个文件的写入前状态，适用于所有扩展名、未知后缀、无扩展名和点文件。文本工具仍只接受有效 UTF-8，二进制文件通过复制/移动使用相同的提交保护。

**累计修复与优化**：拒绝非法 UTF-8、UTF-16 和 NUL 文本的破坏性编辑；修复分页边界、换行匹配、复制移动重叠、并发追加及部分失败状态；安全中转失败不再回退直写；锁和临时文件清理失败不会掩盖主操作结果；工作线程和扫描预算防止复杂表达式阻塞服务。依赖锁定与 overrides 用于复现已验证的依赖树。

**升级行为变化**：显式 `writePolicy` 优先，其次是持久人工策略，再由 `auto` 观察文件状态。Windows 的 `auto` 缺少可用外部读取器时返回 `DISK_UNVERIFIED`，不会猜测后继续写入；需要新建受保护文件时明确指定 `preserve` 或配置人工 `protected`。更新后重启全部 MCP 实例，并用 `check_status` 确认运行版本为 `2.1.0`。

适用场景

电脑安装了文件加密软件（如天锐绿盾、IP-Guard、亿赛通、深信服等），磁盘上的文件是密文。AI Agent（Claude Code、Cursor、Windsurf、Cline 等）是独立进程，内置文件工具不在白名单内，只能读到密文。而 Node.js 进程在白名单内，通过 MCP Server 提供的替代工具可以正常读写明文。

**前提条件：Node.js 进程已被加密软件列为白名单（受信任进程）。**

支持的 AI Agent

本 MCP Server 遵循标准 MCP 协议，任何支持 MCP 的 Agent 均可使用：

Agent	配置方式
Claude Code CLI	.mcp.json 或 claude mcp add
Cursor	Settings → MCP → 添加 Server
Windsurf	MCP 配置中添加
Cline / Roo Code	MCP 设置中添加
Continue.dev	config.json 中配置 MCP
Zed	settings.json 中配置 MCP
其他支持 MCP 的工具	按各自文档配置

架构

AI Agent  -