# 读写文件的mcp服务器

**Repository Path**: user_gitee/reasonix_mcp_fs

## Basic Information

- **Project Name**: 读写文件的mcp服务器
- **Description**: 用于读写文件的MCP服务器，采取多种方式，优化agent工具读写文件，效率生产工具。
- **Primary Language**: Python
- **License**: AGPL-3.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-13
- **Last Updated**: 2026-08-14

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Reasonix MCP FS — 本地文件操作服务器

**版本: 1.5.0** — 性能加速 + 功能增强 · 许可证: MIT · 协议: MCP (stdio)

为 [Reasonix](https://reasonix.ai) 打造的本地文件操作 MCP 服务器，提供高效读写增删改查本机文件的能力，专为高频源码编辑优化。

---

## ✨ 特性总览

| 能力 | 说明 |
|---|---|
| **读** | 读取文件（行号/偏移/行数限制）、并发读取多个文件，大文件按需读取 |
| **写** | 写入/创建文件，原子写入（崩溃安全），自动创建父目录 |
| **改** | 智能编辑：自动处理行尾空格/CRLF 差异、锚点消歧义；按行号精准替换/插入 |
| **删** | 安全二阶段删除：先标记、确认后才真正执行，可取消 |
| **查** | 文件内搜索（带上下文）、递归内容搜索（grep）、列目录、文件信息、通配符搜索 |
| **移动/复制** | 移动、重命名、复制文件和目录（同盘 O(1)） |

**核心安全机制**：沙箱权限控制 + 删除二阶段确认 + 编码/字节级往返保护，防止 AI 工具越权操作或损坏文件。

---

## 📦 快速开始

### 方式一：一键安装（推荐）

在项目文件夹中运行：

```bash
python install_full.py
```

脚本会自动：探测 Python 环境 → 安装虚拟环境和依赖（带进度条）→ 复制源码并部署 → 验证模块导入和基本功能 → 打印 Reasonix 手动配置信息。

### 方式二：手动安装

```bash
# 1. 创建虚拟环境
python -m venv .venv

# 2. 激活虚拟环境
# Windows:
.venv\Scripts\activate
# Linux/macOS:
source .venv/bin/activate

# 3. 安装依赖和本包
# 注意：mcp 2.x 已将 FastMCP 拆分为独立包，本项目基于 1.x，必须锁定版本
pip install "mcp>=1.0.0,<2.0.0"
pip install chardet          # 可选增强：编码统计检测（缺失时自动回退）
pip install -e .

# 4. 启动服务器（stdio 模式）
python -m reasonix_mcp_fs
# 或（安装后）直接使用命令：
reasonix-mcp-fs
```

---

## ⚙️ 在 Reasonix 中配置

Reasonix 支持三种配置方式，**推荐快速配置**（一行命令，最省事）。

### ⭐ 快速配置（推荐）— 粘贴一行命令

在 Reasonix 设置 > MCP 与工具 > 添加服务器 的「快速配置」输入框中，粘贴下面**整行命令**（命令 + 参数）：

```
D:/Develop/Serve/MCP/reasonix_mcp_fs_serve/.venv/Scripts/python.exe -m reasonix_mcp_fs
```

- 这一行就是"命令 + 参数"，快速配置框会自动拆分并识别 stdio 传输方式
- 路径使用**正斜杠** `/`：反斜杠 `\D`、`\S` 等是非法转义，配置解析时路径会被破坏，报 `file does not exist`
- `command` 指向**真实存在的** python.exe（默认部署目录见"一键安装"输出）

### 手动配置 — 命令与参数分开

若使用「手动配置」界面（该界面**通常没有独立的参数栏**，带 `-m` 参数的 stdio 服务器请优先用快速配置或 `.mcp.json`）：

| 字段 | 值 |
|---|---|
| 名称 | `reasonix_mcp_fs` |
| 传输方式 | `stdio` |
| 命令（Command） | `D:/Develop/Serve/MCP/reasonix_mcp_fs_serve/.venv/Scripts/python.exe` |
| 参数（Args） | `-m reasonix_mcp_fs` |
| 环境变量 | 留空 |

> 注意：手动配置的**命令栏里只填纯路径**、参数单独放 Args——不要把两者拼进命令栏。这一点与快速配置不同：快速配置框专门接受"命令 + 参数"的一整行。

### 备选：项目级 `.mcp.json`（自动加载，无需界面手填）

在项目根目录创建 `.mcp.json`（Reasonix 打开项目时自动发现并连接）：

```json
{
  "mcpServers": {
    "reasonix_mcp_fs": {
      "command": "D:/Develop/Serve/MCP/reasonix_mcp_fs_serve/.venv/Scripts/python.exe",
      "args": ["-m", "reasonix_mcp_fs"],
      "env": {}
    }
  }
}
```

要点：
- 路径用**正斜杠** `/`（反斜杠会被配置解析转义破坏）
- `command` 与 `args` 是 JSON 中的**独立字段**（`args` 为数组）
- `command` 指向真实存在的 python.exe

配置完成后，工具列表应出现 **23 个文件操作工具**（其中 10 个只读工具带 `readOnlyHint` 注解，plan 模式下可用；9 个写/删/移动工具带 `destructiveHint` 注解）。

---

## 🛠️ 工具列表（23 个）

### 注解说明

> 🔵 只读（`readOnlyHint=true`，plan 模式下可用）· 🔴 破坏性（`destructiveHint=true`，写/删/移动）· ⚪ 状态/追加（无注解）
>
> 工具顺序与 Reasonix 界面一致（按工具名字母序排列）。

### 按模块速览

| 模块 | 工具 |
|---|---|
| A 沙箱 / 安全（3） | `set_workspace_root` ⚪ · `allow_external_write` ⚪ · `get_workspace_info` 🔵 |
| B 编码（1） | `detect_encoding` 🔵 |
| C 读取（2） | `read_file` 🔵 · `read_multiple_files` 🔵 |
| D 写入 / 编辑（3） | `write_file` 🔴 · `edit_file` 🔴 · `append_to_file` ⚪ |
| E 行级编辑（2） | `replace_lines` 🔴 · `insert_at_line` 🔴 |
| F 删除（安全二阶段，5） | `delete_file` 🔴 · `batch_delete` 🔴 · `confirm_deletions` 🔴 · `cancel_deletions` ⚪ · `get_pending_deletions` 🔵 |
| G 查询 / 浏览（5） | `find_in_file` 🔵 · `grep` 🔵 · `search_files` 🔵 · `list_directory` 🔵 · `get_file_info` 🔵 |
| H 移动 / 复制（2） | `move_file` 🔴 · `copy_file` 🔴 |

### 工具详情（按字母序）

| 工具 | 描述 | 说明 |
|---|---|---|
| `allow_external_write` ⚪ | 授权一次沙箱外写入 | 一次性权限，用完即收；v1.5.0 起支持目录前缀授权 |
| `append_to_file` ⚪ | 追加内容到文件 | encoding 默认 auto（已有文件保留原编码） |
| `batch_delete` 🔴 | 批量标记删除（安全模式） | 需 confirm_deletions 确认 |
| `cancel_deletions` ⚪ | 取消删除操作 | 保留文件 |
| `confirm_deletions` 🔴 | 确认执行删除操作 | 实际执行删除（确认时复查沙箱） |
| `copy_file` 🔴 | 复制文件/目录 | OS 级零拷贝，目录递归复制 |
| `delete_file` 🔴 | 标记删除（安全模式） | 需 confirm_deletions 确认 |
| `detect_encoding` 🔵 | 检测文件文本编码 | BOM + UTF-8 + chardet + 系统编码 + 启发式评分 |
| `edit_file` 🔴 | 智能编辑文件 | 自动降级匹配，锚点消歧义，正则，encoding |
| `find_in_file` 🔵 | 文件中搜索文本 | 支持正则、上下文、流式不整读、encoding |
| `get_file_info` 🔵 | 获取文件/目录详细信息 | 单次 os.stat |
| `get_pending_deletions` 🔵 | 查看待删除列表 | 管理待删除项 |
| `get_workspace_info` 🔵 | 查看沙箱状态 | 工作区根（含来源）和授权列表 |
| `grep` 🔵 | 递归目录内容搜索 | 正则、独立沙箱、glob 过滤、并发、超时控制 |
| `insert_at_line` 🔴 | 在指定行前插入内容 | 精准插入，encoding |
| `list_directory` 🔵 | 列出目录内容 | os.scandir 批量获取 stat |
| `move_file` 🔴 | 移动/重命名文件 | 源与目标均做沙箱写检查，同盘 O(1) |
| `read_file` 🔵 | 读取文件内容 | 行号/偏移/行数限制，encoding 参数，大文件按需读取 |
| `read_multiple_files` 🔵 | 并发读取多个文件头部 | 线程池并行 IO，每文件前 5 行预览 |
| `replace_lines` 🔴 | 按行号替换代码块 | 最精准，不受文本匹配影响，encoding |
| `search_files` 🔵 | 按通配符搜索文件 | 支持 `**/*.py` 路径模式，os.scandir 递归 |
| `set_workspace_root` ⚪ | 设置/关闭工作区沙箱 | 限制文件操作范围；空字符串关闭 |
| `write_file` 🔴 | 写入/创建文件 | 原子写入，encoding 默认 auto（已有文件保留原编码） |

### 编辑工具详解

**`edit_file`** — 智能匹配引擎（三策略自动降级）：

```
策略1: exact       精确匹配（最快路径）
策略2: trailing_ws 去掉每行尾部空白后匹配（处理空格/tab 差异）
策略3: full_norm   去掉每行首尾空白后匹配（最宽松）
```

当某一策略找到多处匹配时，用 `anchor` 参数指定附近唯一文本来消歧义：

```
edit_file(path="app.py",
          old_string="    return result",
          anchor="def process(data):",    # ← 附近唯一文本
          new_string="    return sorted(result)")
```

匹配失败时返回文件末尾片段和建议操作。

**`replace_lines`** — 按行号替换（最精准，不受文本匹配影响）：

```
replace_lines(path="app.py",
              start_line=10, end_line=20,   # 替换 10-20 行
              new_content="def new_func():\n    pass")
```

**`insert_at_line`** — 按行号插入：

```
insert_at_line(path="app.py",
               line_number=5,               # 在第 5 行前插入
               content="import os\nimport sys")
```

---

## 🔒 安全机制

### 沙箱系统

防止 AI 工具越权操作文件。核心三工具：

| 工具 | 说明 |
|---|---|
| `set_workspace_root` | 设置工作区根目录（沙箱），限制所有文件操作范围 |
| `allow_external_write` | 授权一次沙箱外写入/删除操作，操作后自动收回权限 |
| `get_workspace_info` | 查看当前沙箱状态和待消费的授权列表 |

#### 工作区自动识别（v1.4.0+）

服务器启动时自动探测 agent 的工作区并**直接启用为默认沙箱根**，无需手动设置，优先级：

1. **环境变量**（显式最高）：`REASONIX_WORKSPACE` 或 `MCP_WORKSPACE`，指向工作区目录
2. **Reasonix 工作区状态文件**（自主识别，零配置）：读取 Reasonix 桌面「当前工作区」状态文件（`desktop-workspace`）获得 agent 当前项目——多项目共享同一服务器实例也能正确识别
3. **进程 cwd**（兜底）：仅当 cwd 是普通工作目录（非应用安装目录）时采用

> ⚠️ **cwd 回退的局限**：Reasonix 以**自身安装目录**为 cwd 启动 MCP 子进程，直接取 cwd 会把沙箱根错误设到安装目录（agent 真实工作区全被判定为"沙箱外"）。服务器会识别安装目录特征（`Reasonix.exe`/`versions/` 等）并跳过 cwd，优先使用工作区状态文件。未识别到有效工作区时**不启用沙箱**（错误的沙箱比无沙箱更糟），`get_workspace_info` 会显示识别来源与提示。

识别结果可通过 `get_workspace_info` 查看（含"工作区来源"字段）；`set_workspace_root("")` 可随时关闭。

#### 沙箱行为

- 识别到工作区后即自动启用沙箱（可用 `set_workspace_root("")` 关闭）
- 设置沙箱后，**写入/删除/移动/复制**操作仅限于沙箱内
- **读取**操作在沙箱外仍可进行，但返回结果末尾附加 `⚠️ 沙箱外读取` 警告
- **外部写入**需通过 `allow_external_write()` 明确授权，且仅对下一次操作有效（v1.5.0 起支持**目录前缀授权**：授权父目录可覆盖其下任意子路径的一次操作）
- 未识别到工作区时沙箱不启用（向后兼容，不做限制）

#### 工作区根目录保护（v1.5.0）

`delete_file` / `batch_delete` / `confirm_deletions` 拒绝删除**工作区根目录或其上级目录**，防止误删清空整个沙箱根。

### 删除安全（二阶段确认）

所有删除操作均需用户明确确认后才能实际执行，防止误删。示例：

```
# 1. 标记删除（不会立即执行）
delete_file(path="C:/temp/old_file.txt")
# 返回: ⚠️ 已标记待删除: C:\temp\old_file.txt
#          ├─ 执行删除 → confirm_deletions(id=1234567)
#          ├─ 取消删除 → cancel_deletions(id=1234567)
#          └─ 查看全部 → get_pending_deletions()

# 2. 确认删除
confirm_deletions(deletion_id=1234567)
# 返回: [OK] 已删除文件: C:\temp\old_file.txt
#       结果: 1 个成功

# 3. 或取消删除（保留文件）
cancel_deletions(deletion_id=1234567)
# 返回: 已取消 1 个文件/目录的删除操作
```

---

## 🧬 编码支持

所有读写工具（`read_file`、`write_file`、`edit_file`、`find_in_file`、`replace_lines`、`insert_at_line`、`append_to_file`、`read_multiple_files`、`grep`）均支持 `encoding` 参数。

**编码安全原则（v1.4.0）**：读取和修改文件前，服务器一律先检测原文件编码，避免乱码。

### 默认行为（`encoding="auto"`）

| 操作类型 | 行为 |
|---|---|
| 读操作 | 默认 `encoding="auto"`，先检测再解码 |
| 修改已有文件 | 先检测原文件编码，写回时自动保留（GBK 文件修改后仍是 GBK） |
| 新建文件 | 使用 UTF-8 |
| 大文件（>1MB） | 编码检测只采样头部，不整读 |

### 自动检测流程

```
① BOM 匹配          → utf-8-sig / utf-16-le / utf-16-be
② UTF-8 严格解码    → 覆盖 95%+ 源码文件
③ chardet 统计检测  → 增强无 BOM 的 GBK/Shift-JIS 区分（可选依赖，置信度≥0.3 且可解码才采用）
④ 系统 locale 编码   → 中文 GBK / 日文 Shift-JIS 等
⑤ 启发式评分        → 尝试常见编码，选 � 替换最少者（v1.5.0 起先做严格解码快速路径）
```

### 显式指定编码

用于已知编码的文件：

```python
read_file(path="data.txt", encoding="gbk")
edit_file(path="shift-jis.txt", old_string="...", new_string="...", encoding="shift_jis")
write_file(path="output.txt", content="...", encoding="gb2312")
```

### 数据完整性保护

- **字节级往返安全**（v1.1.0+）：所有读/写操作使用 Python 的 `surrogateescape` 错误处理，文件中未被修改的字节也能无损保留，不会因编码解码导致数据损坏
- **行尾风格保留**（v1.1.0+）：编辑类工具自动检测并保留原文件的 CRLF (`\r\n`)、LF (`\n`) 或旧 Mac (`\r`) 行尾风格
- **`detect_encoding` 工具**可单独探测文本编码

---

## 🚀 性能优化（v1.5.0）

| 优化点 | 实测加速（见 `benchmarks/bench.py`） |
|---|---|
| 编码检测启发式：严格解码快速路径 | ~10x（1MB GBK 样本） |
| 智能匹配 `_smart_find`：命中即停 + 惰性归一化 | ~4x（10 万行内容） |
| 大文件部分读取：换行偏移检查点 seek 定位 | ~1.6x（偏移越深收益越大） |
| `grep` 混合策略：≤64MB 整读 / >64MB 流式 | 速度持平，大文件内存 O(行) 而非 O(文件) |

运行基准（对比优化前后，防止回归）：

```bash
python benchmarks/bench.py             # 默认 20MB 测试文件
python benchmarks/bench.py --size 50   # 自定义文件大小 (MB)
```

---

## 📁 项目结构

```
reasonix_mcp_fs/
├── reasonix_mcp_fs/          # 源代码包
│   ├── __init__.py        # 包信息
│   ├── __main__.py        # python -m 入口
│   ├── server.py          # FastMCP 实例
│   ├── tools.py           # 23 个文件操作工具
│   └── pending.py         # 待删除管理器
├── tests/                 # unittest 测试（无需额外依赖）
├── benchmarks/bench.py    # 性能基准脚本（对比优化前后）
├── pyproject.toml         # 项目构建配置
├── install_full.py        # 一键安装脚本
├── .gitignore             # 忽略运行时产物与测试临时目录
└── README.md              # 本文件
```

**运行测试**（无第三方依赖，使用标准库 unittest）：

```bash
python -m unittest discover -s tests -v
```

---

## 📋 依赖

- Python >= 3.10
- mcp >= 1.0.0, < 2.0.0（MCP Python SDK）
- chardet >= 5.0（可选增强：编码统计检测；缺失时自动回退到 locale + 启发式，不影响功能）

---

## 📄 许可证

MIT

---

## 📝 更新日志

### v1.5.0

**性能加速（基准验证，见 benchmarks/bench.py）**

- `_detect_encoding` 启发式评分新增**严格解码快速路径**（首个能完整解码的候选立即采用），
  1MB GBK 样本实测 **~10x** 提速（旧算法对每个候选做 replace 解码 + � 计数）
- `_smart_find` 改为**命中即停 + 惰性归一化**：精确匹配（最常见）命中后不再对
  trailing_ws/full_norm 策略做整文件扫描，10 万行内容实测 **~4x** 提速；
  同时修复旧逻辑"exact 唯一命中却提示精确匹配失败"的矛盾警告
- `_read_file_lines` 大文件部分读取新增**换行偏移检查点**：第一遍计数时记录换行字节位置，
  第二遍直接 seek 到目标起始行（不再从文件头重读 begin 行），中段/深偏移读取实测 **~1.6x** 提速
  （偏移越深收益越大）；检查点上限 100 万行防内存膨胀；UTF-16/32（换行为多字节）自动退回从头跳过
- `grep` 单文件搜索改为**混合策略**：≤64MB 整读（C 级 splitlines 最快），>64MB 自动切换流式逐行
  （内存 O(行) 而非 O(文件)），大文件不再整读进内存
- `find_in_file` 匹配数改为**流式搜索直接计数**（不再用分隔符字符串计数，消除误计），
  `_search_file_stream` 返回精确匹配数

**功能增强**

- `allow_external_write` 支持**目录前缀授权**：授权父目录可覆盖其下任意子路径的一次
  写/删/移动操作（大小写不敏感）
- **工作区根目录删除保护**：`delete_file` / `batch_delete` / `confirm_deletions` 拒绝删除
  工作区根目录或其上级目录，防止误删清空整个沙箱
- `PendingDeletion.add/add_multi` 统一归一化为 Path，兼容 str 输入（此前 str 会在确认时崩溃）

**工程完善**

- 新增 `tests/`（52 个 unittest 用例：编码检测/智能匹配/沙箱边界/待删除/glob 模式/流式搜索/工具注册）
  与 `benchmarks/bench.py`（对比优化前后，`--size` 自定义文件大小）；新增 `.gitignore`
- 版本号更新至 1.5.0

### v1.4.0

- **工具注解（ToolAnnotations）**：为全部 23 个工具声明 MCP 标准注解——10 个只读工具标记
  `readOnlyHint=true`（plan 模式下可用）；9 个写/删/移动工具标记 `destructiveHint=true`；
  `append_to_file` 及 3 个状态工具保持默认
- **编码检测增强（chardet）**：新增 chardet 统计检测分支（BOM → UTF-8 → chardet → locale → 启发式）；
  修复长/混合 CJK 文本在中文 Windows 上 Shift-JIS 被 cp936 误判的问题；chardet 为可选依赖，
  缺失时自动回退；中文编码归一化为 gb18030（GBK 超集）避免 gb2312 编码器写回报错
- **编码安全强化**：读取和修改文件前一律先检测原文件编码；`write_file` / `append_to_file`
  默认 `encoding="auto"`，已有文件自动保留原编码，避免覆盖乱码
- **工作区自动识别**：启动时探测 `REASONIX_WORKSPACE` / `MCP_WORKSPACE` 环境变量
  （无则回退进程 cwd），识别到即自动启用为默认沙箱根；`get_workspace_info` 显示识别来源
- **安全修复**：`move_file` 源路径改为写权限检查（移动会删除源文件，此前可绕过沙箱删除
  沙箱外文件）；`confirm_deletions` 确认时复查沙箱（防 TOCTOU）
- **正确性修复**：`_is_in_workspace` 修复驱动器根目录（如 `C:\`）作为沙箱根时误判、
  Windows 路径大小写敏感问题；待删除批次 ID 改为进程内严格递增，消除同毫秒碰撞
- **性能优化**：`read_file` 大文件按需读取不整读（<4MB 仍全量，行数精确）；
  `read_multiple_files` 只读头部预览；`detect_encoding` 大文件采样 1MB；`_smart_find` 首行预筛；
  `grep` 单文件读取受超时约束
- **性能优化（P0，基准验证）**：`read_file` 全量读取由双遍 IO 改单遍（20MB 实测 150→92ms，-38%）；
  `find_in_file` 改流式搜索（不整读、内存 O(窗口)，输出与原实现逐字一致）；
  `grep` 文件级并发搜索（最多 8 路并行，结果按路径排序恢复稳定顺序）
- **健壮性**：`append_to_file` 改用 `with` 管理句柄（修复句柄泄漏）；`search_files` / `grep`
  的 `include` 支持 `**/*.py` 等路径模式；`asyncio.get_running_loop()` 替代已弃用 API；
  新增 `reasonix-mcp-fs` 命令行入口
- 新增 `tests/`（unittest）覆盖编码检测、智能匹配、沙箱边界、待删除管理器、路径模式搜索
- 版本号更新至 1.4.0

### v1.3.0

- **新增 `grep` 工具**：递归搜索目录中文件内容，支持正则、glob 文件过滤、超时控制、结果截断
- grep **独立于沙箱权限体系**，可检索任意位置（只读操作）
- 自动跳过隐藏文件/目录和常见忽略目录（node_modules、__pycache__、.venv 等）
- 版本号更新至 1.3.0（工具总数 22 → 23）

### v1.2.0

- **新增沙箱安全系统**：`set_workspace_root` 可设置工作区沙箱，限制文件操作范围
- **一次性写入授权**：`allow_external_write` 授权沙箱外单次写/删操作，用完自动收回
- **沙箱状态查询**：`get_workspace_info` 查看当前沙箱状态和授权列表
- **读操作沙箱提醒**：沙箱外读取在结果末尾附加 `⚠️ 沙箱外读取` 警告
- **写操作沙箱阻断**：沙箱外写入返回明确错误提示，引导用户授权
- 版本号更新至 1.2.0（工具总数 19 → 22）

### v1.1.0

- **修复文件编码损坏**：所有解码/编码使用 `surrogateescape` 错误处理，保证非 UTF-8 文件字节级往返安全
- **修复行尾破坏**：编辑类工具（`edit_file`、`replace_lines`、`insert_at_line`）自动检测并保留原文件的 CRLF/LF/CR 行尾风格
- **正则路径增强**：`edit_file` 的正则模式下，`new_string` 自动规范化行尾以匹配原文件风格
- **原子写入增强**：Windows 下使用 `O_BINARY` 标志防止 `\r\n` 被意外转换
- 版本号更新至 1.1.0