mcp-read-file-server 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 hebulin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,314 @@
+# 文件操作 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 均可使用：
+
+| 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  --(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）
+├── smithery.yaml     # Smithery 市场上架配置
+├── .gitignore        # Git 忽略规则
+└── node_modules/     # 依赖（@modelcontextprotocol/sdk、zod，不随包发布）
+```
+
+## 安装
+
+### 前置条件
+- Node.js v18+（推荐 v20+）
+- Node.js 已被加密软件列为白名单进程
+
+### 方式一：通过 npx 运行（推荐，无需手动安装）
+
+已发布到 npm，可直接通过 `npx` 运行，无需 `git clone` 和 `npm install`：
+
+```bash
+npx -y mcp-read-file-server
+```
+
+首次运行 npx 会自动下载本包及其依赖到临时目录并启动。配置 Agent 时将 `command` 设为 `npx`、`args` 设为 `["-y", "mcp-read-file-server"]` 即可（见下文「配置」）。
+
+### 方式二：从源码运行（开发 / 离线场景）
+
+```bash
+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 包运行，无需关心本地路径：
+
+```json
+{
+  "mcpServers": {
+    "read-file-server": {
+      "command": "npx",
+      "args": ["-y", "mcp-read-file-server"]
+    }
+  }
+}
+```
+
+### 本地源码方式
+
+若用「方式二」从源码运行，则指向本地 `index.js`：
+
+```json
+{
+  "mcpServers": {
+    "read-file-server": {
+      "command": "node",
+      "args": ["/path/to/mcp-read-file-server/index.js"]
+    }
+  }
+}
+```
+
+### Claude Code CLI
+
+#### 方式一：项目级配置（仅当前项目可用）
+
+在项目根目录创建 `.mcp.json` 文件：
+
+```json
+{
+  "mcpServers": {
+    "read-file-server": {
+      "command": "npx",
+      "args": ["-y", "mcp-read-file-server"]
+    }
+  }
+}
+```
+
+#### 方式二：全局配置（所有项目可用）
+
+```bash
+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`，添加：
+
+```json
+{
+  "mcpServers": {
+    "read-file-server": {
+      "command": "npx",
+      "args": ["-y", "mcp-read-file-server"]
+    }
+  }
+}
+```
+
+#### 验证配置
+
+```bash
+claude mcp list
+```
+
+应该能看到 `read-file-server` 在列表中。
+
+### Cursor / Windsurf / Cline 等
+
+在各自设置界面的 MCP 配置中，添加上述 JSON 配置。
+
+## 提供的工具
+
+| 工具名 | 替代内置 | 功能 | 参数 |
+|--------|---------|------|------|
+| `read_file` | Read | 读取单个文件明文 | `path`: 文件路径 |
+| `read_files` | 多次 Read | 批量读取多个文件明文 | `paths`: 逗号分隔的路径 |
+| `read_file_partial` | Read（局部） | 局部读取文件（前N字符 / 指定行范围） | `path`、`mode`、`charCount`、`startLine`、`endLine` |
+| `write_file` | Write | 写入文件（自动加密落盘） | `path`、`content` |
+| `edit_file` | Edit/MultiEdit | 精确字符串/正则替换后写回 | `path`、`oldString`、`newString`、`useRegex`、`replaceAll`、`ignoreCase` |
+| `search_files` | Grep | 递归搜索文件内容 | `pattern`、`path`、`include`、`ignoreCase`、`onlyMatching`、`maxResults` |
+| `create_directory` | - | 递归创建目录 | `path` |
+| `file_info` | - | 查询文件/目录信息 | `path` |
+| `check_status` | - | 检查工具运行状态 | 无 |
+
+### `read_file_partial` 参数详解
+
+| 参数 | 类型 | 必填 | 默认 | 说明 |
+|------|------|------|------|------|
+| `path` | string | ✅ | - | 文件路径，支持相对路径或绝对路径 |
+| `mode` | enum: `chars` / `lines` | ✅ | - | 读取模式：`chars`=按字符数读取前N个字符；`lines`=按行号读取指定行或行范围 |
+| `charCount` | number | `mode=chars` 时必填 | - | 读取前 N 个字符 |
+| `startLine` | number | `mode=lines` 时必填 | - | 起始行号（从 1 开始） |
+| `endLine` | number | ❌ | =`startLine` | 结束行号（含该行）。不传则只读取 `startLine` 一行 |
+
+**使用示例：**
+
+- 读取文件前 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`，位于本目录根下。
+
+| 项 | 说明 |
+|----|------|
+| 作用 | 教 AI Agent 在加密环境下主动选用 `mcp__read-file-server__*` 工具，避开内置 Read/Write/Edit/Grep |
+| 当前状态 | `SKILL.md` 在工具根目录，**未安装**，需要按下面步骤复制到对应位置才生效 |
+| 触发关键词 | 天锐、绿盾、密文、TSD、IP-Guard、亿赛通、白名单、读不到文件等 |
+
+### 1. 安装到 Claude Code
+
+Claude Code 启动时会自动扫描 `skills/` 目录，每个 Skill 必须是 `skill-name/SKILL.md` 的子目录结构。
+
+| 作用域 | 安装位置 |
+|--------|----------|
+| 项目级（仅本项目） | `<本仓库>/.claude/skills/encryption-file-ops/SKILL.md` |
+| 用户级（所有项目） | `~/.claude/skills/encryption-file-ops/SKILL.md` |
+
+安装示例（项目级，从本目录执行）：
+
+```bash
+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 是否在其中。
+```
+
+**方式二：手动复制**
+
+```bash
+# 以 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` 即可。
+
+> 若需离线使用或二次开发，再按「安装 -> 方式二」从源码克隆运行。
+
+## 上架 MCP 市场
+
+本包已具备 `npx` 直接运行能力，可上架到各 MCP 市场：
+
+| 市场 | 上架方式 |
+|------|---------|
+| npm | `npm publish`（包名 `mcp-read-file-server`，已配置 `bin` 与 `files`） |
+| Smithery | 在 https://smithery.ai 提交包名，仓库根已提供 `smithery.yaml`（上架前以官方文档核对） |
+| mcp.so | 在 https://mcp.so 提交 npm 包名与启动命令 `npx -y mcp-read-file-server` |
+| PulseMCP | 在 https://www.pulsemcp.com 提交包名 |
+
+发布到 npm 前建议本地预检：
+
+```bash
+# 预览将发布到 npm 的文件清单（应只有 index.js / README.md / SKILL.md / LICENSE / package.json）
+npm pack --dry-run
+
+# 登录并发布
+npm login
+npm publish
+```
+
+发布后，他人即可通过 `npx -y mcp-read-file-server` 一行命令运行，无需手动 `npm install`。
+
+## 故障排查
+
+### 读取到的仍是密文
+
+说明 Node.js 未被加密软件列为白名单。解决方法：
+- 联系加密软件管理员，将 `node.exe` 加入白名单
+- 确认加密软件的受信任进程列表中包含 Node.js
+
+### MCP Server 无法启动
+
+```bash
+# 验证 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
+```

package/SKILL.md

@@ -0,0 +1,169 @@
+---
+name: encryption-file-ops
+description: 在文件加密软件（天锐绿盾 / IP-Guard / 亿赛通 / 深信服等）环境下，使用 mcp__read-file-server__* 工具替代 AI Agent 内置 Read/Write/Edit/Grep 工具读写明文。当内置工具返回密文/乱码，或用户提到"加密、绿盾、密文、白名单、读不到文件"等关键词时激活。
+---
+
+# 加密环境文件操作 Skill
+
+> **本 Skill 负责"教策略"，MCP Server 负责"执行"。**
+> 本 Skill 不替代任何 MCP 工具，仅提供使用指引。
+
+## 一、适用场景
+
+### 触发条件（满足任一即激活）
+- 内置 `Read/Write/Edit/Grep` 工具返回密文、十六进制乱码、`%TSD-Header-###%` 文件头
+- 用户提到关键词：天锐、绿盾、TSD、IP-Guard、亿赛通、深信服、加密软件、白名单、密文、解密失败
+- 项目文件头出现 `%TSD-Header-###%` 等加密标识
+
+### 前置条件
+- Node.js 进程已被加密软件列为**白名单（受信任进程）**
+- `mcp-read-file-server` MCP Server 已配置（见项目 `README.md`）
+- 在 `claude mcp list` 中能看到 `read-file-server`
+
+---
+
+## 二、工具映射表
+
+| 场景 | 内置工具（禁用） | MCP 工具（用这个） |
+|------|------------------|---------------------|
+| 读单个文件 | `Read` | `mcp__read-file-server__read_file` |
+| 读 ≥2 个文件 | 多次 `Read` | `mcp__read-file-server__read_files` |
+| 局部读文件（前N字符/指定行） | `Read`（局部） | `mcp__read-file-server__read_file_partial` |
+| 写文件 | `Write` | `mcp__read-file-server__write_file` |
+| 精确编辑 | `Edit` / `MultiEdit` | `mcp__read-file-server__edit_file` |
+| 搜索内容 | `Grep` | `mcp__read-file-server__search_files` |
+| 创建目录 | （无） | `mcp__read-file-server__create_directory` |
+| 查文件信息 | （无） | `mcp__read-file-server__file_info` |
+| 健康检查 | （无） | `mcp__read-file-server__check_status` |
+
+> **强约束**：在加密环境下，**禁止使用** `Read/Write/Edit/MultiEdit/Grep` 内置工具--它们会读到密文或破坏加密结构。
+
+---
+
+## 三、决策树
+
+```
+需要读文件
+  ├─ 单个（全文）-> mcp__read-file-server__read_file
+  ├─ 多个（≥2）-> mcp__read-file-server__read_files（批量更高效）
+  └─ 局部读取（大文件预览/定位特定行）-> mcp__read-file-server__read_file_partial
+      ├─ 读前N字符 -> mode="chars", charCount=N
+      └─ 读指定行范围 -> mode="lines", startLine=X, endLine=Y（endLine 不传则只读一行）
+
+需要修改文件
+  ├─ 已读过 -> 直接 mcp__read-file-server__edit_file
+  └─ 未读过 -> 先 read_file 拿到明文 -> 再 edit_file
+
+需要新建/覆盖文件
+  └─ mcp__read-file-server__write_file
+
+需要搜索内容
+  └─ mcp__read-file-server__search_files
+      ├─ 限定文件类型 -> 用 include（如 "*.java,*.xml"）
+      └─ 控制返回数量 -> 用 maxResults
+
+需要创建目录
+  └─ mcp__read-file-server__create_directory
+
+需要判断文件是否存在 / 查大小
+  └─ mcp__read-file-server__file_info
+
+工具异常 / 不确定是否生效
+  └─ mcp__read-file-server__check_status
+```
+
+---
+
+## 四、典型工作流
+
+### 流程 1：读取并修改文件
+```
+1. mcp__read-file-server__read_file 读取明文
+2. 分析内容
+3. mcp__read-file-server__edit_file 修改
+   - oldString 必须从第 1 步读到的内容里**原样复制**（含空格、缩进、换行）
+4. 必要时再 read_file 验证修改结果
+```
+
+### 流程 2：批量读多个相关文件
+```
+1. mcp__read-file-server__read_files
+   - paths 参数用英文逗号分隔，如 "D:/proj/A.java,D:/proj/B.java"
+2. 统一分析（输出会带"========== 文件: xxx =========="分隔）
+```
+
+### 流程 3：在项目中搜索特定代码
+```
+1. mcp__read-file-server__search_files
+   - pattern: 正则表达式（如 "function\s+\w+"、"@GetMapping"）
+   - path: 搜索根目录
+   - include: 文件名过滤（可选）
+2. 根据返回的 file:line 定位，用 read_file 读取具体文件
+```
+
+### 流程 4：从零创建新模块
+```
+1. mcp__read-file-server__create_directory 建包目录
+2. mcp__read-file-server__write_file 逐个创建文件
+3. read_file 验证（可选）
+```
+
+---
+
+## 五、`edit_file` 关键参数详解
+
+| 参数 | 类型 | 必填 | 默认 | 说明 |
+|------|------|------|------|------|
+| `path` | string | ✅ | - | 文件绝对路径 |
+| `oldString` | string | ✅ | - | 要替换的原内容，必须**精确匹配** |
+| `newString` | string | ✅ | - | 替换后的新内容 |
+| `useRegex` | boolean | ❌ | false | true 时 oldString 当正则，可用 `$1 $2` 引用捕获组 |
+| `replaceAll` | boolean | ❌ | false | true 时替换所有匹配项；false 时仅替换第一处 |
+| `ignoreCase` | boolean | ❌ | false | 是否忽略大小写（仅字符串模式生效） |
+
+### 常见用法
+- **单点替换**：`useRegex=false, replaceAll=false`（默认）
+- **批量替换**：`useRegex=true, replaceAll=true`（如改命名）
+- **正则提取后重组**：`useRegex=true, newString` 里用 `$1` `$2`
+
+---
+
+## 六、注意事项
+
+1. **路径**：用**绝对路径**最稳（如 `D:/AiJiamiToolsPlugins/...`），相对路径以 MCP Server 启动目录为基准
+2. **`edit_file` 前必读**：必须先 `read_file` 拿到明文，再从原文里**原样复制** `oldString`，否则会因为空格/缩进不匹配而失败
+3. **不要在 `oldString` 里漏换行**：多行替换时，行末换行符也要复制完整
+4. **`write_file` 是覆盖写**：会清空原文件再写入，重要文件修改前建议先 `read_file` 备份内容
+5. **`search_files` 自动跳过**：`node_modules`、`.git`、`target`、`build`、`dist`、`.idea`、`.vscode`
+6. **大批量搜索**：用 `maxResults` 控制返回数量，避免一次性返回过多结果
+7. **工具调用顺序**：复杂任务先 `check_status` 确认 MCP 正常，再正式操作
+
+---
+
+## 七、故障排查
+
+| 现象 | 可能原因 | 解决方案 |
+|------|----------|----------|
+| 读到的还是密文/乱码 | Node.js 不在加密软件白名单 | 联系管理员把 `node.exe` 加入白名单 |
+| `mcp__read-file-server__*` 工具全部不可见 | MCP Server 未配置或未启动 | 见 `README.md` 配置 `.mcp.json` |
+| `edit_file` 报"未找到匹配内容" | `oldString` 拼写、缩进、换行不对 | 重新 `read_file` 复制原文，**不要凭记忆写** |
+| `edit_file` 报"匹配到 N 处" | 文件中存在重复内容 | 加更长/更唯一的 `oldString` 唯一定位，或 `replaceAll=true` |
+| `search_files` 报"正则表达式无效" | 正则语法错误 | 检查 `pattern` 是否需要转义特殊字符 |
+| `write_file` 报权限错误 | 文件被占用或目录无写权限 | 关闭占用进程 / 检查目录权限 |
+| 工具调用超时 | 文件过大 | 改用 `search_files` 定位后只 `read_file` 关键段，或用 `read_file_partial` 局部读取 |
+
+---
+
+## 八、与其他工具的关系
+
+| 工具类型 | 在加密环境下 | 备注 |
+|----------|--------------|------|
+| 内置 `Read/Write/Edit/Grep` | ❌ 禁用 | 会读到密文或破坏加密 |
+| 内置 `Bash` | ⚠️ 慎用 | Bash 进程通常不在白名单，`cat`/`sed` 也会读到密文 |
+| 内置 `Glob` | ✅ 可用 | 只列文件名，不读内容 |
+| 内置 `NotebookEdit` | ⚠️ 慎用 | 同 Edit |
+| `mcp__read-file-server__*` | ✅ 主用 | 本 Skill 推广的工具集 |
+| `TaskCreate` / `TaskList` | ✅ 可用 | 任务管理，不涉及文件内容 |
+| `WebFetch` / `WebSearch` | ✅ 可用 | 网络工具，与本地加密无关 |
+
+> **Bash 特别注意**：在加密环境下，`Bash` 工具的 `cat`/`sed`/`grep` 也会读到密文。如需在终端操作文件，应使用 `node -e` 走 Node.js 白名单进程。

package/index.js

@@ -0,0 +1,435 @@
+#!/usr/bin/env node
+/**
+ * MCP Server: 文件操作工具集（加密软件环境明文读写）
+ *
+ * 通用场景：当电脑安装了文件加密软件（如天锐绿盾、IP-Guard、亿赛通等），
+ * 且 Node.js 进程被列为白名单（受信任进程）时，fs.readFileSync / fs.writeFileSync
+ * 可自动解密/加密，读到明文。而 Claude Code CLI 内置工具（Read/Write/Edit/Grep）
+ * 是独立进程，不在白名单内，只能读到密文。
+ *
+ * 本 MCP Server 通过 Node.js 进程提供文件读写工具，替代 Claude Code 内置工具，
+ * 适用于任何「Node.js 是加密软件白名单进程」的场景。
+ *
+ * 提供工具：
+ *   - read_file          读取单个文件明文（替代内置 Read）
+ *   - read_files         批量读取多个文件明文
+ *   - read_file_partial  局部读取文件（前N字符 / 指定行范围）
+ *   - write_file         写入文件，自动加密落盘（替代内置 Write）
+ *   - edit_file          精确字符串/正则替换后写回（替代内置 Edit/MultiEdit）
+ *   - search_files       递归搜索文件内容（替代内置 Grep）
+ *   - create_directory   递归创建目录
+ *   - file_info          查询文件/目录信息
+ *   - check_status       检查工具运行状态
+ */
+const fs = require("fs");
+const path = require("path");
+const { McpServer } = require("@modelcontextprotocol/sdk/server/mcp.js");
+const { StdioServerTransport } = require("@modelcontextprotocol/sdk/server/stdio.js");
+const { z } = require("zod");
+
+// 版本号读取自 package.json，与发布版本保持同步，避免硬编码漂移
+const pkg = require("./package.json");
+const server = new McpServer({ name: "read-file-server", version: pkg.version });
+
+/**
+ * 读取文件内容。Node.js 进程被加密软件列为白名单，fs.readFileSync 可自动解密读到明文。
+ */
+function readFileContent(filePath) {
+  try {
+    const content = fs.readFileSync(filePath, "utf-8");
+    // 加密环境下 stat.size 是密文字节数，与明文长度不一致，改用明文字节数避免误导
+    return { ok: true, content, size: Buffer.byteLength(content, "utf-8") };
+  } catch (e) {
+    if (e.code === "ENOENT") {
+      return { ok: false, error: "文件不存在: " + filePath };
+    }
+    return { ok: false, error: "读取失败（可能是密文，请确认 Node.js 是否被加密软件列为白名单进程）: " + e.message };
+  }
+}
+
+// 注册 read_file 工具
+server.tool(
+  "read_file",
+  "读取指定路径的文件内容（明文）。加密软件环境下，Node.js 进程作为白名单可自动解密读取明文。适用于读取代码、配置、文档等文本文件。替代内置 Read 工具。",
+  { path: z.string().describe("文件路径，支持相对路径或绝对路径") },
+  { readOnlyHint: true },
+  async ({ path: filePath }) => {
+    const result = readFileContent(filePath);
+    if (result.ok) {
+      return { content: [{ type: "text", text: result.content }] };
+    } else {
+      return { content: [{ type: "text", text: "❌ " + result.error }], isError: true };
+    }
+  }
+);
+
+// 注册 read_files 工具（批量读取）
+server.tool(
+  "read_files",
+  "批量读取多个文件的内容（明文）。多个路径用逗号分隔。加密软件环境下通过 Node.js 白名单进程自动解密。",
+  { paths: z.string().describe("文件路径列表，多个路径用英文逗号分隔") },
+  { readOnlyHint: true },
+  async ({ paths: pathsStr }) => {
+    const pathList = pathsStr.split(",").map(p => p.trim()).filter(p => p);
+    if (!pathList.length) {
+      return { content: [{ type: "text", text: "❌ 未提供任何文件路径" }], isError: true };
+    }
+    const results = [];
+    for (const p of pathList) {
+      const result = readFileContent(p);
+      if (result.ok) {
+        results.push("========== 文件: " + p + " ==========\n" + result.content);
+      } else {
+        results.push("========== 文件: " + p + " 【读取失败】 ==========\n❌ " + result.error);
+      }
+    }
+    return { content: [{ type: "text", text: results.join("\n\n") }] };
+  }
+);
+
+// 注册 read_file_partial 工具（局部读取，按字符数或行号范围）
+server.tool(
+  "read_file_partial",
+  "局部读取文件内容（明文）。支持两种模式：①按字符数读取前N个字符；②按行号读取指定行或行范围（如第10行、第5-20行）。加密软件环境下同样通过 Node.js 白名单进程自动解密。适用于大文件预览、定位特定行内容等场景。",
+  {
+    path: z.string().describe("文件路径，支持相对路径或绝对路径"),
+    mode: z.enum(["chars", "lines"]).describe("读取模式：chars=按字符数读取前N个字符；lines=按行号读取指定行或行范围"),
+    charCount: z.number().int().positive().optional().describe("mode=chars 时必填，读取前N个字符"),
+    startLine: z.number().int().min(1).optional().describe("mode=lines 时必填，起始行号（从1开始）"),
+    endLine: z.number().int().min(1).optional().describe("mode=lines 时可选，结束行号（含）。不传则只读取 startLine 一行"),
+  },
+  { readOnlyHint: true },
+  async ({ path: filePath, mode, charCount, startLine, endLine }) => {
+    const result = readFileContent(filePath);
+    if (!result.ok) {
+      return { content: [{ type: "text", text: "❌ " + result.error }], isError: true };
+    }
+    const content = result.content;
+    const totalChars = content.length;
+
+    if (mode === "chars") {
+      if (charCount === undefined) {
+        return { content: [{ type: "text", text: "❌ mode=chars 时必须提供 charCount 参数" }], isError: true };
+      }
+      const slice = content.slice(0, charCount);
+      const header = "📄 文件: " + filePath + "\n模式: 前 " + charCount + " 字符（共 " + totalChars + " 字符）\n";
+      const footer = charCount < totalChars ? "\n\n...(已截断，还有 " + (totalChars - charCount) + " 字符未显示)" : "";
+      return { content: [{ type: "text", text: header + "──────────────────────\n" + slice + footer }] };
+    }
+
+    // mode === "lines"
+    if (startLine === undefined) {
+      return { content: [{ type: "text", text: "❌ mode=lines 时必须提供 startLine 参数" }], isError: true };
+    }
+    const lines = content.split(/\r?\n/);
+    const totalLines = lines.length;
+    const sLine = startLine;
+    const eLine = endLine !== undefined ? endLine : startLine;
+    if (eLine < sLine) {
+      return { content: [{ type: "text", text: "❌ endLine 不能小于 startLine" }], isError: true };
+    }
+    // 行号从1开始，数组索引从0开始
+    const startIdx = Math.max(0, sLine - 1);
+    const endIdx = Math.min(totalLines, eLine); // slice 不含 endIdx，所以用 eLine（因为已经 +1 偏移）
+    const selected = lines.slice(startIdx, endIdx);
+    // 为每行添加行号前缀
+    const numbered = selected.map((line, i) => {
+      const lineNo = startIdx + i + 1;
+      return String(lineNo).padStart(6, " ") + " | " + line;
+    });
+    const actualStart = startIdx + 1;
+    const actualEnd = startIdx + selected.length;
+    const header = "📄 文件: " + filePath + "\n模式: 第 " + actualStart + " - " + actualEnd + " 行（共 " + totalLines + " 行）\n";
+    const footer = eLine > totalLines ? "\n\n⚠️ 请求的结束行 " + eLine + " 超出文件总行数 " + totalLines + "，已自动截断" : "";
+    return { content: [{ type: "text", text: header + "──────────────────────\n" + numbered.join("\n") + footer }] };
+  }
+);
+
+// 注册 write_file 工具（加密软件环境下安全写回）
+server.tool(
+  "write_file",
+  "将内容写入指定路径（明文）。加密软件环境下，Node.js 白名单进程写入会自动加密落盘，适用于安全写回加密文件。替代内置 Write 工具。",
+  {
+    path: z.string().describe("文件路径，支持相对路径或绝对路径"),
+    content: z.string().describe("写入的文件内容（明文）"),
+  },
+  async ({ path: filePath, content }) => {
+    try {
+      // 自动创建父目录，避免新文件路径不存在时直接报错
+      const parent = path.dirname(filePath);
+      if (parent && !fs.existsSync(parent)) {
+        fs.mkdirSync(parent, { recursive: true });
+      }
+      fs.writeFileSync(filePath, content, "utf-8");
+      return { content: [{ type: "text", text: "✅ 写入成功: " + filePath }] };
+    } catch (e) {
+      return { content: [{ type: "text", text: "❌ 写入失败: " + e.message }], isError: true };
+    }
+  }
+);
+
+// 注册 edit_file 工具（精确替换，替代受加密影响的 Edit/MultiEdit）
+server.tool(
+  "edit_file",
+  "对文件内容做精确字符串或正则替换后写回（明文）。加密软件环境下内置 Edit/MultiEdit 直写会破坏加密，本工具用 Node.js fs 读改写，自动加密落盘。替代内置 Edit/MultiEdit 工具。",
+  {
+    path: z.string().describe("文件路径，支持相对路径或绝对路径"),
+    oldString: z.string().describe("要被替换的原字符串。useRegex=true 时作为正则表达式"),
+    newString: z.string().describe("替换后的字符串。正则模式下可用 $1 $2 等捕获组引用"),
+    useRegex: z.boolean().optional().describe("是否将 oldString 当作正则表达式，默认 false（纯字符串匹配）"),
+    replaceAll: z.boolean().optional().describe("是否替换全部匹配项，默认 false 仅替换第一处"),
+    ignoreCase: z.boolean().optional().describe("是否忽略大小写，默认 false。仅在非正则的字符串模式下生效"),
+  },
+  async ({ path: filePath, oldString, newString, useRegex, replaceAll, ignoreCase }) => {
+    try {
+      const original = fs.readFileSync(filePath, "utf-8");
+      let matcher;
+      if (useRegex) {
+        try {
+          const flags = replaceAll ? "g" : "";
+          matcher = new RegExp(oldString, ignoreCase ? flags + "i" : flags);
+        } catch (e) {
+          return { content: [{ type: "text", text: "❌ 正则表达式无效: " + e.message }], isError: true };
+        }
+      }
+      let count;
+      let updated;
+      if (useRegex) {
+        const globalMatcher = new RegExp(matcher.source, "g" + (ignoreCase ? "i" : ""));
+        const matches = original.match(globalMatcher);
+        count = matches ? matches.length : 0;
+        const replaceMatcher = replaceAll ? globalMatcher : new RegExp(matcher.source, ignoreCase ? "i" : "");
+        updated = original.replace(replaceMatcher, newString);
+      } else {
+        if (oldString === "") {
+          return { content: [{ type: "text", text: "❌ oldString 不能为空字符串" }], isError: true };
+        }
+        let idx = 0, c = 0;
+        const hay = ignoreCase ? original.toLowerCase() : original;
+        const needle = ignoreCase ? oldString.toLowerCase() : oldString;
+        while ((idx = hay.indexOf(needle, idx)) !== -1) { c++; idx += needle.length; }
+        count = c;
+        if (replaceAll) {
+          const esc = oldString.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+          updated = original.replace(new RegExp(esc, ignoreCase ? "gi" : "g"), newString);
+        } else {
+          const pos = ignoreCase ? hay.indexOf(needle) : original.indexOf(oldString);
+          if (pos === -1) {
+            updated = original;
+          } else {
+            updated = original.slice(0, pos) + newString + original.slice(pos + oldString.length);
+          }
+        }
+      }
+      if (count === 0) {
+        return {
+          content: [{ type: "text", text: "⚠️ 未找到匹配内容，文件未修改。请检查 oldString（或正则）是否正确: " + filePath }],
+          isError: true,
+        };
+      }
+      let warning = "";
+      if (!replaceAll && count > 1) {
+        warning = "\n⚠️ 注意：共匹配 " + count + " 处，但 replaceAll=false 仅替换了第一处。如需全部替换请设 replaceAll=true。";
+      }
+      if (updated === original) {
+        return { content: [{ type: "text", text: "⚠️ 替换后内容无变化，文件未修改: " + filePath }] };
+      }
+      fs.writeFileSync(filePath, updated, "utf-8");
+      return {
+        content: [{ type: "text", text: "✅ 替换成功: " + filePath + "\n替换 " + (replaceAll ? count : 1) + "/" + count + " 处" + warning }],
+      };
+    } catch (e) {
+      if (e.code === "ENOENT") {
+        return { content: [{ type: "text", text: "❌ 文件不存在: " + filePath }], isError: true };
+      }
+      return { content: [{ type: "text", text: "❌ 替换失败: " + e.message }], isError: true };
+    }
+  }
+);
+
+// 注册 search_files 工具（内容搜索，替代受加密影响的 Grep）
+server.tool(
+  "search_files",
+  "在指定目录递归搜索文件内容（明文）。加密软件环境下内置 Grep(ripgrep) 只能读到密文搜不到内容，本工具用 Node.js fs 读取后正则匹配。替代内置 Grep 工具。",
+  {
+    pattern: z.string().describe("正则表达式（如 log.*Error、function\\s+\\w+）"),
+    path: z.string().describe("搜索根目录，支持相对路径或绝对路径"),
+    include: z.string().optional().describe("文件名 glob 过滤，多个用逗号分隔（如 *.java,*.xml）。不传则搜索全部文件"),
+    ignoreCase: z.boolean().optional().describe("是否忽略大小写，默认 false"),
+    onlyMatching: z.boolean().optional().describe("是否只输出匹配部分（非整行），默认 false 输出整行"),
+    maxResults: z.number().optional().describe("最大返回匹配数，默认 200。超过会在末尾提示被截断"),
+  },
+  { readOnlyHint: true },
+  async ({ pattern, path: rootDir, include, ignoreCase, onlyMatching, maxResults }) => {
+    try {
+      // 修正：忽略大小写时需同时携带 g 与 i 标志，否则 ignoreCase 参数失效
+      const flags = ignoreCase ? "gi" : "g";
+      let regex;
+      try {
+        regex = new RegExp(pattern, flags);
+      } catch (e) {
+        return { content: [{ type: "text", text: "❌ 正则表达式无效: " + e.message }], isError: true };
+      }
+      const includeList = include
+        ? include.split(",").map((s) => s.trim()).filter(Boolean)
+        : null;
+      // include glob 匹配: 仅比对文件名(不含目录), * -> .*, 其余转义
+      const matchesInclude = (name) => {
+        if (!includeList) return true;
+        return includeList.some((pat) => {
+          const re = new RegExp("^" + pat.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*") + "$");
+          return re.test(name);
+        });
+      };
+      const limit = maxResults || 200;
+      const results = [];
+      let truncated = false;
+      let scanned = 0;
+      let matchedFiles = 0;
+      // 对单个文件做内容匹配, 复用与目录遍历相同的行级逻辑
+      const scanFile = (full) => {
+        if (!matchesInclude(path.basename(full))) return;
+        scanned++;
+        let content;
+        try {
+          content = fs.readFileSync(full, "utf-8");
+        } catch (e) {
+          return;
+        }
+        const lines = content.split(/\r?\n/);
+        let fileHit = false;
+        for (let i = 0; i < lines.length; i++) {
+          if (truncated) break;
+          const line = lines[i];
+          if (onlyMatching) {
+            // onlyMatching 模式：输出一行内的所有匹配片段（原实现仅取第一个）
+            regex.lastIndex = 0;
+            let m;
+            while ((m = regex.exec(line)) !== null) {
+              if (!fileHit) { fileHit = true; matchedFiles++; }
+              results.push(full + ":" + (i + 1) + ":" + m[0]);
+              if (results.length >= limit) { truncated = true; break; }
+              // 防止零宽匹配导致死循环
+              if (m.index === regex.lastIndex) regex.lastIndex++;
+            }
+          } else {
+            // 整行模式：一行只输出一条
+            regex.lastIndex = 0;
+            if (regex.exec(line)) {
+              if (!fileHit) { fileHit = true; matchedFiles++; }
+              results.push(full + ":" + (i + 1) + ":" + line);
+              if (results.length >= limit) { truncated = true; }
+            }
+          }
+        }
+      };
+      const walk = (dir) => {
+        if (truncated) return;
+        let entries;
+        try {
+          entries = fs.readdirSync(dir, { withFileTypes: true });
+        } catch (e) {
+          return;
+        }
+        for (const entry of entries) {
+          if (truncated) return;
+          const full = path.join(dir, entry.name);
+          if (entry.isDirectory()) {
+            if (["node_modules", ".git", "target", "build", "dist", ".idea", ".vscode"].includes(entry.name)) continue;
+            walk(full);
+          } else if (entry.isFile()) {
+            scanFile(full);
+          }
+        }
+      };
+      // path 既可能是目录也可能是单个文件: 文件直接搜, 目录递归遍历
+      // 修复: 旧实现无视 path 类型一律 readdirSync, 传入文件路径时 ENOTDIR 被吞,
+      //       静默返回"扫描 0 个文件", 误导调用方以为无匹配
+      let stat;
+      try {
+        stat = fs.statSync(rootDir);
+      } catch (e) {
+        if (e.code === "ENOENT") {
+          return { content: [{ type: "text", text: "❌ 路径不存在: " + rootDir }], isError: true };
+        }
+        return { content: [{ type: "text", text: "❌ 无法访问路径: " + e.message }], isError: true };
+      }
+      if (stat.isFile()) {
+        scanFile(rootDir);
+      } else if (stat.isDirectory()) {
+        walk(rootDir);
+      }
+      let text = results.join("\n");
+      if (results.length === 0) {
+        text = "未找到匹配项（扫描 " + scanned + " 个文件，根目录: " + rootDir + "）";
+      } else {
+        text = "找到 " + results.length + " 处匹配（" + matchedFiles + " 个文件，扫描 " + scanned + " 个文件）:\n" + text;
+        if (truncated) text += "\n... 结果已达上限 " + limit + "，被截断。可通过 maxResults 调大。";
+      }
+      return { content: [{ type: "text", text }] };
+    } catch (e) {
+      return { content: [{ type: "text", text: "❌ 搜索失败: " + e.message }], isError: true };
+    }
+  }
+);
+
+// 注册 create_directory 工具（递归创建目录）
+server.tool(
+  "create_directory",
+  "递归创建目录（类似 mkdir -p）。加密软件环境下，Node.js 白名单进程操作目录同样安全。",
+  { path: z.string().describe("要创建的目录路径，支持相对路径或绝对路径") },
+  async ({ path: dirPath }) => {
+    try {
+      fs.mkdirSync(dirPath, { recursive: true });
+      return { content: [{ type: "text", text: "✅ 目录已创建（或已存在）: " + dirPath }] };
+    } catch (e) {
+      return { content: [{ type: "text", text: "❌ 创建目录失败: " + e.message }], isError: true };
+    }
+  }
+);
+
+// 注册 file_info 工具（查询文件/目录信息）
+server.tool(
+  "file_info",
+  "查询文件或目录的信息：是否存在、类型、大小、修改时间等。加密软件环境下 stat 不读内容，结果准确。",
+  { path: z.string().describe("文件或目录路径，支持相对路径或绝对路径") },
+  { readOnlyHint: true },
+  async ({ path: filePath }) => {
+    try {
+      const stat = fs.statSync(filePath);
+      const info = {
+        path: filePath,
+        exists: true,
+        type: stat.isDirectory() ? "directory" : "file",
+        size: stat.size,
+        modifiedTime: stat.mtime.toISOString(),
+        createdTime: stat.birthtime.toISOString(),
+      };
+      return { content: [{ type: "text", text: JSON.stringify(info, null, 2) }] };
+    } catch (e) {
+      if (e.code === "ENOENT") {
+        return { content: [{ type: "text", text: JSON.stringify({ path: filePath, exists: false }, null, 2) }] };
+      }
+      return { content: [{ type: "text", text: "❌ 查询失败: " + e.message }], isError: true };
+    }
+  }
+);
+
+// 注册 check_status 工具
+server.tool(
+  "check_status",
+  "检查文件操作工具的运行状态，确认 Node.js 进程能否正常读取加密文件明文。",
+  {},
+  { readOnlyHint: true },
+  async () => {
+    return { content: [{ type: "text", text: "✅ read-file-server 运行中\n平台: Node.js " + process.version + "\n功能: 通过 Node.js fs 读写文件明文（加密软件白名单中的 Node.js 进程自动解密/加密）" }] };
+  }
+);
+
+// 启动服务
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}
+
+main().catch(console.error);

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "mcp-read-file-server",
+  "version": "1.0.0",
+  "description": "加密环境文件操作 MCP 工具。当 Node.js 是加密软件白名单进程时，通过 fs 模块自动解密读写文件明文，替代 AI Agent 内置文件工具，适用于任何支持 MCP 协议的 Agent。",
+  "type": "commonjs",
+  "main": "index.js",
+  "bin": {
+    "mcp-read-file-server": "index.js"
+  },
+  "files": [
+    "index.js",
+    "README.md",
+    "SKILL.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "start": "node index.js",
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "keywords": [
+    "mcp",
+    "mcp-server",
+    "model-context-protocol",
+    "file-operations",
+    "file-reader",
+    "encryption",
+    "claude",
+    "ai-agent",
+    "stdio"
+  ],
+  "author": "hebulin",
+  "license": "MIT",
+  "homepage": "https://github.com/hebulin/mcp-read-file-server#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hebulin/mcp-read-file-server.git"
+  },
+  "bugs": {
+    "url": "https://github.com/hebulin/mcp-read-file-server/issues"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "zod": "^4.4.3"
+  }
+}