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

简介

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

适用场景

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

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

支持的 AI Agent

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

架构

AI Agent  --(MCP/stdio)-->  Node.js MCP Server  --(fs.readFileSync)-->  读取明文

文件结构

mcp-read-file-server/
├── README.md         # 本文档
├── SKILL.md          # 配套 Skill（可选，让 AI 学会自动选用本工具）
├── index.js          # MCP Server 主程序（含 shebang，可作可执行入口）
├── package.json      # 包配置（bin/files/依赖声明，可 npm publish）
├── .gitignore        # Git 忽略规则
└── node_modules/     # 依赖（@modelcontextprotocol/sdk、zod，不随包发布）

安装

前置条件

• Node.js v18+（推荐 v20+）
• Node.js 已被加密软件列为白名单进程

方式一：通过 npx 运行（推荐，无需手动安装）

已发布到 npm，可直接通过 npx 运行，无需 git clone 和 npm install：

npx -y mcp-read-file-server

首次运行 npx 会自动下载本包及其依赖到临时目录并启动（需数秒~十几秒；若 Agent 启动超时，可先在终端手动跑一次 npx -y mcp-read-file-server 预热缓存，看到卡住等输入后 Ctrl+C 退出）。配置 Agent 时将 command 设为 npx、args 设为 ["-y", "mcp-read-file-server"] 即可（见下文「配置」；Windows 下部分 Agent 需用 npx.cmd）。

方式二：从源码运行（开发 / 离线场景）

git clone https://github.com/hebulin/mcp-read-file-server.git
cd mcp-read-file-server
npm install

此时配置中使用 node + 本地 index.js 绝对路径。

配置

所有 Agent 配置 MCP Server 的核心信息相同，只是配置文件位置和格式略有差异。

npx 方式（推荐）

通过 npm 包运行，无需关心本地路径：

{
  "mcpServers": {
    "read-file-server": {
      "command": "npx",
      "args": ["-y", "mcp-read-file-server"]
    }
  }
}

⚠️ Windows 用户注意：部分 Agent（Cursor / Cline / Continue 等）在 Windows 下直接用 npx 会启动失败（报 spawn npx ENOENT 或连不上），需把 command 改成 npx.cmd：

{
  "mcpServers": {
    "read-file-server": {
      "command": "npx.cmd",
      "args": ["-y", "mcp-read-file-server"]
    }
  }
}

Claude Code 通常能自动识别 npx，无需改。若 npx.cmd 仍失败，可改用 "command": "cmd"、"args": ["/c", "npx", "-y", "mcp-read-file-server"]。

本地源码方式

若用「方式二」从源码运行，则指向本地 index.js：

{
  "mcpServers": {
    "read-file-server": {
      "command": "node",
      "args": ["/path/to/mcp-read-file-server/index.js"]
    }
  }
}

Claude Code CLI

方式一：项目级配置（仅当前项目可用）

在项目根目录创建 .mcp.json 文件：

{
  "mcpServers": {
    "read-file-server": {
      "command": "npx",
      "args": ["-y", "mcp-read-file-server"]
    }
  }
}

方式二：全局配置（所有项目可用）

claude mcp add read-file-server -s user -- npx -y mcp-read-file-server

参数说明：

• read-file-server：MCP Server 名称（自定义）
• -s user：作用域为全局（所有项目可用），不写则默认项目级
• --：分隔符，后面是实际执行的命令
• npx -y mcp-read-file-server：实际执行的命令（自动从 npm 拉取并运行）

方式三：手动编辑全局配置文件

直接编辑 C:\Users\你的用户名\.claude.json，添加：

{
  "mcpServers": {
    "read-file-server": {
      "command": "npx",
      "args": ["-y", "mcp-read-file-server"]
    }
  }
}

验证配置

claude mcp list

应该能看到 read-file-server 在列表中。

Cursor / Windsurf / Cline 等

在各自设置界面的 MCP 配置中，添加上述 JSON 配置。

提供的工具

read_file_partial 参数详解

使用示例：

• 读取文件前 500 个字符：mode="chars", charCount=500
• 读取第 10 行：mode="lines", startLine=10
• 读取第 5-20 行：mode="lines", startLine=5, endLine=20

返回内容会带文件名、读取范围、总字符数/总行数的头部信息，行模式下每行带行号前缀。超出文件范围时自动截断并提示。

使用

配置好后，在 Agent 中直接说需求即可。Agent 会自动调用 MCP 工具读写文件明文。

配套 Skill（可选）

本工具附带一份 Skill：SKILL.md，位于本目录根下。

1. 安装到 Claude Code

Claude Code 启动时会自动扫描 skills/ 目录，每个 Skill 必须是 skill-name/SKILL.md 的子目录结构。

安装示例（项目级，从本目录执行）：

mkdir -p ../.claude/skills/encryption-file-ops
cp SKILL.md ../.claude/skills/encryption-file-ops/SKILL.md

安装后重启 Claude Code 即可生效。

2. 安装到 OpenClaw（小龙虾）

⚠️ 以下为通用约定写法，OpenClaw 的 Skill 加载机制请以其官方文档为准，确认后可对本节做相应调整。

方式一：让 OpenClaw 自动安装

把 SKILL.md 交给 OpenClaw，用自然语言让它自己装：

我把一个 Skill 文件放在 D:/AiJiamiToolsPlugins/mcp-read-file-server/SKILL.md，
请按 OpenClaw 的 Skill 规范把它安装到我的 skills 目录，并确认能否被加载。

OpenClaw 会读取文件、确认 frontmatter（name / description），并复制到它自己的 Skill 目录。装完后可让它自检：

列出你当前已加载的所有 Skill，确认 encryption-file-ops 是否在其中。

方式二：手动复制

# 以 OpenClaw 默认 skill 目录 ~/.openclaw/skills 为例
mkdir -p ~/.openclaw/skills/encryption-file-ops
cp SKILL.md ~/.openclaw/skills/encryption-file-ops/SKILL.md

配置目录名（.openclaw）仅为示例，请替换为 OpenClaw 实际使用的目录。

方式三：项目级随仓库分发

如果希望 Skill 跟随项目走（团队成员拉代码即生效），把 SKILL.md 放进项目的 Skill 扫描目录（例如 <仓库根>/.openclaw/skills/encryption-file-ops/SKILL.md），与 OpenClaw 的项目级 Skill 约定保持一致即可。

3. 验证安装

无论哪种 Agent，安装后重启客户端，然后：

1. 输入触发关键词测试，例如："这个项目里有文件加密，读文件是密文，怎么办？"
2. 观察是否自动选用 mcp__read-file-server__* 工具而非内置 Read/Grep

在新电脑上使用

已发布到 npm，新电脑上无需拷贝文件，只要装了 Node.js（v18+），直接配置 Agent 使用 npx -y mcp-read-file-server 即可。

若需离线使用或二次开发，再按「安装 -> 方式二」从源码克隆运行。

故障排查

读取到的仍是密文

说明 Node.js 未被加密软件列为白名单。解决方法：

• 联系加密软件管理员，将 node.exe 加入白名单
• 确认加密软件的受信任进程列表中包含 Node.js

MCP Server 无法启动

# 验证 Node.js 和依赖
node --version
cd mcp-read-file-server && npm install

# 测试启动
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0.0"}}}' | node index.js

Agent 连不上 MCP Server

包本身正常但 Agent 连不上时，按以下顺序排查：

1. Windows 下 npx 找不到：部分 Agent（Cursor / Cline / Continue 等）需把 command 写成 npx.cmd，详见上文「配置 -> npx 方式」的 Windows 注意事项。这是 Windows 上最常见的连不上原因。
2. 首次 npx 下载超时：npx 首次拉取包需数秒~十几秒，某些 Agent 启动超时较短会连不上。先在终端手动跑一次 npx -y mcp-read-file-server（看到卡住等输入即启动成功，Ctrl+C 退出），让包进入缓存，再让 Agent 连接即可秒启。
3. npx 缓存了旧版 / 损坏：清缓存重试 ——

   npx clear-npx-cache
   # 或 Windows 下手动删除缓存目录
   rm -rf "C:/Users/你的用户名/AppData/Local/npm-cache/_npx"
   

4. 确认包本身是否正常：

   npx -y mcp-read-file-server   # 能启动=包没问题，问题在 Agent 配置/环境
   

   能启动并卡住等输入，说明包正常，需检查 Agent 的配置 JSON 格式与 command 写法。