Skip to main content
Glama

file-ops —— 文件操作 MCP 服务

单文件 ESM 实现的本地文件操作 MCP 服务(stdio 传输),面向「让模型安全地改文件」这一场景。除 @modelcontextprotocol/sdk 外零第三方依赖,iconv-lite 为可选依赖(缺失时编码能力降级,见 §4、§7.2)。

核心定位:写边界由工具强制——读路径不限,写类操作只能落在配置的写根(writeRoots)内;配合唯一匹配、幂等、原子写与编码/换行保真,把「改错」与「改坏」两类事故挡在工具层。

1. 设计原则

原则

含义

写边界由工具强制

读路径不限;写类操作只在 writeRoots 内(§6)。不依赖模型自觉

唯一匹配

命中必须唯一;多处命中一律拒绝并给出候选,不猜

幂等

重复提交同一替换不会重复应用;按位置与文件哈希判定,不靠「内容里出现过」

原子写

临时文件 + rename;批量里任一项失败则该文件零写入

保真

保留原文件的编码(UTF-8 / GB18030 / Big5 / UTF-16)与行尾风格

可解释错误

每个错误都带 error/reason,多数给出下一步

Related MCP server: fs-mcp

2. 工具总览(12 个)

工具

一句话职责

read_text

读文本;支持分段读取、行号、缓存复用

edit_text

主力工具:精准替换 / 整文件覆盖

create_directory

建目录(默认递归)

get_file_info

文件元信息

list_directory

列目录(可递归、可限深)

find_files

按名 / 扩展名 / 时间 / 大小查找

trash

移入回收站(可恢复;仅在回收站不可用的受限环境下降级为永久删除并如实标注)

move

移动 / 复制(支持跨盘,带 sha256 校验)

diff

内容级差异(git diff --no-index)

convert_document

文档转换(pandoc):输入 md/docx/html/txt/csv/latex(pdf 不能作输入),输出另含 txt(plain writer)与 pdf(typst 引擎);txt 输入按 markdown 解析

list_protected

查询当前生效的写根、保护规则、批量上限、读上限、配置指纹

count_text

文本统计:行 / 段 / 句 / 词 / 字形 / 码点 / 汉字…(支持目录、多编码与区间统计)

所有工具 schema 均为 additionalProperties:false。参数要点:

  • 读与查:read_text 的 path 必填、encoding='auto',行区间与字节区间互斥(§7.1);list_directory 的 limit=500(超出 truncated:true);find_files 的 root 必填、limit=200,name_pattern 不含通配符时按裸子串匹配,modified_within 是相对时间窗(如 7d)。

  • 写与删:edit_text 的 path 与 paths 互斥、mode='replace'(§3);trash 的目录必须 recursive:true、上限 500 条;move 的 paths[] 最多 200 组、overwrite 默认 false(§5.3);create_directory 默认递归且目标须在写根内。

  • 其余:get_file_info 返回元信息;list_protected 无参数;diff 的 mode='summary'/'full'(超 200 KB 截断);convert_document 的 out_path 可选;count_text 的 paths 与 text 二选一、支持区间统计——start_byte/max_bytes 字节区间与 start_line/count 行区间(与 read_text 同参数同口径),区间统计时 bytes 只覆盖该区间、fileBytes 始终是整文件字节数、单次最多 200 文件 / 200 MB。

  • convert_document 的两个副作用:① txt 作为输入按 markdown 解析(pandoc 没有 plain reader,副作用是 txt 里的 #/* 会被当作 markdown 语法);② pdf 不能作为输入格式(pandoc 无 pdf reader,会报 io_error);输出侧支持 txt(plain writer)。

3. edit_text(最重要的工具)

改已有文件优先用它:不必先读全文,保编码保换行,命中必须唯一,重复提交幂等。

3.1 两种模式

模式

用途

必须显式传什么

mode='replace'(默认)

局部替换

——

mode='overwrite'

整文件覆盖

覆盖已存在文件要 overwriteExisting:true;新建文件要 createIfMissing:true

overwrite 必须显式表态:漏传 overwriteExisting → target_exists;漏传 createIfMissing → target_missing。可配合 expected_sha256 做版本校验,不符 → version_mismatch。

3.2 两级匹配

  1. 精确匹配:字面完全一致,必须唯一命中(matchedBy:'exact')。

  2. 字面量感知规范化:仅在精确匹配零命中时启用,只折叠无语义空白;字符串字面量内部与行首缩进都不折叠(matchedBy:'normalized')。

命中多次 → 拒绝并返回候选(error:'ambiguous',candidates[].line/.snippet);两级都不命中 → 返回 nearMisses,每项给 exactText(该处的精确原文,照它写就能命中)、diffKind(indent 缩进形态不同、常见 tab↔空格 / literal 差异在字符串字面量内 / whitespace 行内空白差异)与 diffInsideLiteral。字面量识别覆盖 "..."、'...'、反引号模板串与 Python 三引号(含转义引号),字面量内的多余空格不会被自动折叠。

3.3 缩进保护(两条规则)

  1. 不会被意外改动:若命中区间的起点落在文件行首缩进内部(oldText 自带前导空白、且与文件缩进只差长度),该候选作废 → not_found + diffKind:'indent' + 完整原文。出路:用不带前导空白的 oldText,或用完整缩进。

  2. 故意改动会被告知:若 oldText 覆盖整行缩进而 newText 不带缩进 → 工具照做,但返回 indentChanged:true 与 originalIndent/newIndent/indentWarning。

YAML 里缩进即结构、Python 里缩进即语法:请让 newText 带上同样的缩进。

3.4 幂等

  • 重复提交同一对 (oldText, newText) → status:'already_applied',并给 alreadyAppliedBy:'ledger'(哈希记账)或 'position'(目标位置已等于 newText)。

  • 判据是位置与哈希一致,不是「文件里出现过 newText」——后者会把「本来就有这句话」误判成已应用。

  • 账本是进程内内存态(上限 200 条),超限丢弃最旧条目(功能不受影响),不落盘——重启或换进程后 already_applied 的 ledger 证据消失,重放只剩位置判据(相同内容会真正再次应用)。already_applied 是状态不是错误,无需再改。

3.5 批量

形态

用途

上限

edits[]

同一文件多处改

每文件 50 处;整批原子(任一失败则该文件零写入)

paths[]

多个文件改同一处

20 个文件 / 单次总替换 200 / 单文件 8 MiB;默认逐文件独立,可选 all_or_nothing:true(先全量预校验,任一不过则整批零写入)

  • summary.failed > 0 表示有文件没改成 → 必须逐个处理;summary.skipped 里的超 8 MiB 文件是 file_too_large,不中断整批。

  • 每个文件改法不同 → 不要用批量,逐个调用;超限 → batch_limit(带 limit/given)。

  • 批量只支持 mode='replace';传 overwrite 或同时传 path 与 paths → invalid_args;目标是目录 → invalid_args(目录内容不变)。

4. 换行与编码

场景

行为

mode='replace' + 原文件混用 CRLF/LF

拒绝(mixed_eol),reason 给出各风格行数与出路:读出全文统一后用 mode='overwrite' 写回

mode='replace' + 原文件纯 LF / 纯 CRLF

跟随文件风格(writtenEol:'lf' / 'crlf')

mode='overwrite' + content 纯 CRLF

写成 CRLF(writtenEol:'crlf',eolNormalized:false)

mode='overwrite' + content 纯 LF

写成 LF(听调用方的,不跟随原文件)

mode='overwrite' + content 自身混用

自动统一为多数风格并回报 eolNormalized:true 与 contentEolNormalizedTo

编码:读写保持原编码(返回 encoding / encodingPreserved),UTF-8 / UTF-16LE / UTF-16BE / GB18030 / Big5 均支持。探测顺序:BOM → UTF-8(strict) → UTF-16 启发式 → GB18030 → Big5;UTF-16 启发式按 2 字节配对统计 NUL 落在偶位/奇位的比例(NUL 数 ≥ 2 且优势方 ≥ 60%),再解码校验(无 U+FFFD、无异常控制字符)才采信 → 无 BOM 的 UTF-16 也能正确读出,含 NUL 的真二进制仍判 binary。

GB18030 与 Big5 可以互相「无错」解码 → 自动探测在两者之间不可靠:无法确定时返回 encodingCandidates(如 ["gb18030","big5"])与 encodingUncertain:true,请显式传 encoding。GB18030 的 BOM(84 31 95 33)会被剥离并回 bom:true,正文不含 U+FEFF。

iconv-lite 缺失时的降级:GB18030 / Big5 依赖可选的 iconv-lite(纯 JS);装不上时能力降级为只支持 UTF-8 / UTF-16,此后处理这两种编码得到 dependency_unavailable,不会静默按 UTF-8 口径读写(那会把中文写成乱码字节);字节区间读则是另一回事:仅支持 UTF-8/ASCII——任何非 UTF-8 文件(含 GB18030 / Big5)的字节区间读一律返回 invalid_args,与 iconv-lite 是否可用无关;错误信息会引导改用 start_line + count 按行读取(行区间对所有编码都支持)。

5. 删除与移动

  • trash → 进 Windows 回收站,可恢复;仅在回收站能力不可用的受限环境下降级为永久删除并如实标注(§5.1);目录必须 recursive:true;单次上限 500 条。

  • move 默认是移动(同卷改名,原子);跨卷时先复制 + SHA-256 校验再删源,返回 crossVolume:true/sha256Verified:true。

  • mode='copy' 是复制(源不限路径,目标须在写根内);mode='move' 源与目标都须在写根内。递归 trash 目录 / move 搬整棵目录前会先扫子树(§6.4);copy 与单文件删除不触发。

  • 批量 trash 的顶层 ok 只有全部成功才为 true(带 succeeded/failed,逐条看 results[]);批量 edit_text 的顶层 ok 与 summary 一致,有失败条目即为 false。

5.1 回收站三态

动手前先探测「本进程能不能真的把文件送进回收站」:在包内临时目录建 1 字节探针 → 记录 <卷>:\$Recycle.Bin\ 下所有 SID 子目录的 $I* 总数(不可读的 SID 目录逐个 try/catch 跳过)→ 用底层原始动作把探针送回收站 → 再数一次,after > before 才算可用。

为什么必须真做一次删除:受限进程(低完整性 / 可写域不含 $Recycle.Bin)里 SHFileOperation 仍返回 rc=0,文件却已被静默永久删除——只看「exit 0 + 文件消失」会谎报成功。结果进程内缓存(懒加载),探测异常一律按不可用处理(fail-closed),原因留在 recycleBinCapability().detail;探针仍在则用 fsp.rm 清掉。

情况

trash 返回

move 覆盖返回

能力 true

ok:true / action:'sent-to-recycle-bin' / recyclable:true

ok:true / overwrote:true / overwrittenToRecycleBin:true / recyclable:true

能力 false(默认)

ok:true / action:'deleted-permanently' / recyclable:false / 顶层 warning:'本进程无法使用回收站(可能受沙箱权限限制),文件已永久删除且不可恢复'

ok:true / overwrote:true / overwrittenToRecycleBin:false / recyclable:false / warning:'…覆盖时目标已永久删除且不可恢复'

能力 false + FOP_REQUIRE_RECYCLE_BIN=1(严格模式)

ok:false / error:'recycle_bin_unavailable',一个文件都不删

同左:ok:false / 源与目标均保持原样

降级原则三条:不谎报(能力不可用时绝不报 sent-to-recycle-bin,即使文件确实消失了)、不阻碍(默认不让删除类任务卡死)、可严格(要「必须可恢复」就设 FOP_REQUIRE_RECYCLE_BIN=1)。能力 false 且非严格时不再调底层 COM 动作(省一次几百毫秒的子进程),直接用 fsp.rm 并标注降级。

FOP_ALLOW_PERMANENT_DELETE=1 的语义是强制永久删:跳过回收站、直接 fsp.rm,返回 permanentDelete:true(即使能力可用也不进回收站),且不带 warning(调用方已明确表态,例如清缓存 / 删 node_modules)。探测成功会在回收站留下一个几字节的探针条目(可接受)。

5.2 删除语义与保护分层

层

机制

管什么

第一层

protected.json(保护规则)

挡住「不该被删的东西」——node_modules/.git/凭据/核心配置/审计日志/包管理器缓存。命中即拒绝,带 ruleId 与 reason

第二层

trash 回收站

兜底「删了还想恢复」——进回收站,可还原

第三层

外部 shell 原生删除

效率优先的日常清理——Remove-Item/fs.rm,快、无批量上限,永久删除

四条容易误判的实际情况:

  1. 回收站是后悔药,不是救命稻草:重要文件的安全依赖第一层与工作区外的备份,不依赖回收站。

  2. trash 的可恢复性依赖执行进程的权限:探测失败即降级并如实标注(deleted-permanently + recyclable:false + warning),绝不谎报。

  3. DSH 的 pwsh 沙箱是 Low integrity,其内部删除恒为永久:Remove-Item/fs.rm 都绕开本工具,回收站兜底对该路径不适用——沙箱固有属性,不是本工具的缺陷。

  4. 因此不强制所有删除走 trash:它走 PowerShell COM、每文件一次调用,慢且受批量上限约束;只有需要后悔药的少量删除才值得用。

严格模式(FOP_REQUIRE_RECYCLE_BIN=1)供「宁可删不掉也不永久删」的场景使用,默认关闭。

5.3 move 的 overwrite(三态)

目标已存在 → 默认拒绝覆盖(invalid_args,避免误伤);要覆盖必须显式传 overwrite:true(批量可按项传,项级覆盖全局)。覆盖前必过三道闸:

  • 闸 A · 目标本身受保护:仍走 guardPath(dst,'move',{write:true}),命中规则照旧拒绝。

  • 闸 B · 目标是目录时查其子树:覆盖目录 = 整棵树被删掉,等价 trash 语义 → 扫子树命中树形规则 → protected_content_inside 拒绝,目标一个字节都不动。

  • 闸 C · 目标不是源自身 / 源的祖先 / 源的后代:src===dst、dst 在 src 内、src 在 dst 内 → invalid_args(防 mv a a/b 自噬)。

执行策略(防数据丢失):

  • 同卷 move(走 rename):记 overwrittenSha256(文件)→ 把目标送进回收站 → rename 源到目标;rename 本身即原子移动,失败时源仍在。

  • 其余(copy / 跨卷):记 overwrittenSha256 → 复制源到目标同目录的临时路径 .fop-ov-<pid>-<ts>(force:false errorOnExist:true)→ 校验临时副本 sha256 等于源 → 才把目标送进回收站 → rename 临时到目标 → mode='move' 再删源;中途失败 finally 清理临时路径、目标保持原样。

  • 处置按能力三态:可用 → 送回收站(overwrittenToRecycleBin:true/recyclable:true);不可用(默认)→ 直接删除并如实标注 overwrittenToRecycleBin:false/recyclable:false/warning;不可用且严格模式 → 拒绝覆盖。处置失败即放弃覆盖(io_error,源与目标均未改动);判定为可用时不会退回直接删除(那等于悄悄永久删除)。

  • mode='move' 删源仍直接删除:这是「移动」的固有语义(源已完整复制并校验通过),只有被覆盖的目标才送回收站;.fop-ov-* 是本次操作自己产生的垃圾,直接删。

  • 返回体加 overwrote:true + overwrittenToRecycleBin + recyclable;被覆盖目标是文件时带 overwrittenSha256(降级另带 warning,强制永久删带 permanentDelete:true)。

6. 写根与保护规则

执行层序(每层都过了才轮到下一层):

device_path_check → realpath_check → write_root_check → sensitive_pattern_check → protected_rule_check

identity_check 不在这个序列里:它是调用侧的独立校验(verifyIdentity),由调用方在真正写入前单独执行,不属于上述层序。

层

判什么

拒绝时的错误码

device_path_check

路径是否为设备名(NUL、CON、COM1…)或 /dev/*

device_path

realpath_check

把路径解析为真实路径后再判一次

——

write_root_check

写类动作的目标是否落在 writeRoots 内

write_root_denied

sensitive_pattern_check

是否命中凭据类规则(.env*、*.pem、*.key、.ssh/**、.aws/**、*.credentials.yaml)

sensitive_denied

protected_rule_check

是否命中其余保护规则(带 ruleId/reason)

protected_rule_denied

identity_check(不在上述序列内,调用侧 verifyIdentity)

校验后目标是否已发生变化(写前复核)

identity_changed

参数校验与存在性检查发生在规则判定之前:参数非法(如 trash 一个目录缺 recursive)→ invalid_args;路径不存在 → not_found;两者都不会走到规则表。

6.1 配置文件在哪

  • 默认是包目录下的 protected.json:<包目录>/protected.json;可用环境变量 FILEOPS_CONFIG 指向另一份(多实例隔离、自测都靠它)。

  • 格式 v2,顶层 version/writeRoots/batchLimits/readCaps/scanBudget/audit/rules:

  • scanBudget:扫描预算(maxFiles 文件数 / maxMs 毫秒),默认 { maxFiles: 20000, maxMs: 15000 };超限返回部分结果 + truncatedBy:'scan_limit'。

{
  "version": 2,
  "writeRoots": [],
  "batchLimits": { "trash": 500, "move": 200, "edits": 50, "editPaths": 20, "editTotalReplacements": 200, "maxEditableBytes": 8388608, "failureDetailFiles": 10 },
  "readCaps": { "maxLines": 2000, "maxBytes": 65536 },
  "audit": { "enabled": false, "logPath": null, "retentionDays": 6, "maxBytes": 20971520, "summaryOnRotate": true },
  "rules": [
    { "id": "R3", "scope": "directory", "pattern": "**/node_modules/**", "patterns": ["**/node_modules/**", "**/node_modules"], "deny": ["trash", "move"], "reason": "依赖目录,误删需重装" }
  ]
}
  • 首次上手必读的三处默认值:① writeRoots 默认空数组 → 忘配则所有写操作被拒(write_root_denied);② audit.enabled 默认 false、audit.logPath 默认 null → 审计默认不落盘;③ 配置模板是 protected.example.json,需复制为 protected.json 后使用(模板里的 writeRoots 也是空的)。

  • 每条规则字段:id、scope(directory/file)、pattern(或 patterns 多路径)、deny(read/list/write/edit/trash/move)、可选 denyMoveAsSourceOnly(move 只看源侧)、reason(必填)。

  • 不允许 per-rule 例外开关字段(enabled/except/exclude/ignore/bypass)——语义统一。目录级规则默认只挡 trash/move,可读可编辑;凭据类规则连 read/list 一起挡。

6.2 三种 pattern 写法的语义

写法

例

实际匹配范围

含该目录本身?

字面路径

C:/work/profiles

只匹配该路径本身;其下的文件与子目录不受此条限制

是(就是它)

通配 + /** 结尾

**/node_modules/**

该目录之下的所有层级(文件与子目录都算)

否

通配(其他形态)

C:/work/logs/app.log*

按模式字面匹配到的所有路径(* 不跨目录分隔符)

视模式而定

  • 同一规则可列多条 pattern:patterns 是数组 → 既能护「整棵树」(**/node_modules/**)又能护「目录本身」(**/node_modules)。示例配置里的 node_modules / .git / .ssh / .aws 就这么写且 deny 都含 move,故目录本身也不能被 trash/move(.ssh/.aws 的 deny 还含 read/list/write/edit,连 list 都拒)。

  • scope 的已知偏差(如实记录,暂不修):scope:"file" 的规则在通配 pattern 下 scope 不参与正则匹配(内部 globToRegex 对 dirScope 取 void)→ **/*.key 也会命中一个名为 my.key 的目录(过度拒绝,宁可偏严);无通配的字面路径规则也不区分文件 / 目录。

  • 判定逐条累加:命中某条且动作在其 deny 内 → 拒;命中但动作不在 deny 内 → 继续判下一条。

6.3 空目录放行

语义:命中的是树形规则(scope:"directory" 且至少一条 pattern 以 /** 结尾)、动作为 trash、目标是空目录时 → 放行。放行粒度是「这一条规则」——继续判定下一条,不是放行整个操作。

四种不放行:① 动作不是 trash(move/write/edit_text/read/list 照旧判);② 目标不是目录;③ 目录非空(只有一个空子目录也算非空);④ 命中的不是树形规则——字面路径规则永不因「空」放行。

  • 判空:statSync + readdirSync,fail-closed:任何异常(不存在 / 无权限 / 实际不是目录)一律按「非空」处理 → 仍然拒绝。判空紧贴操作执行,TOCTOU 窗口极小。

  • 审计留痕:因放行而成功的条目单独写审计:ok:true + waived_rule:"<规则id>" + waived_reason:"empty_directory";失败被拒条目的审计格式一字未改。

  • 副作用(如实记录):空的 .ssh/.aws 目录也可被 trash(空目录没有内容可泄露);非空的一律拒绝。

6.4 祖先包含推理

要堵的洞:§6.2 / §6.3 只回答「目标本身是否受保护」。一个不受保护的父目录被递归 trash 时,子树里整棵 node_modules 会随之消失而规则完全不命中 —— 删父目录等于绕过子树的保护。

语义(不做任何放宽):递归删目录(trash + recursive:true)或 move(mode:'move')搬整棵目录时,若子树里存在命中树形保护规则的路径 → 一律拒绝;绝不因该子树是空的而放行父目录。正确姿势是两道程序:先单独删掉那个空的受保护目录(§6.3 放行),再删它的父级。参与判定的只有树形规则,其「目录本身」pattern(**/node_modules、**/.git、**/.ssh、**/.aws)也计入命中 → 「里面只有一个空 node_modules」同样被拒;字面路径规则不参与。

错误码 protected_content_inside(与「目标本身受保护」的 protected_rule_denied 明确区分),报文要点:ok:false + error + ruleId(顶层再冗余一份便于筛选)+ reason(形如「目标目录的子树中存在受保护内容(node_modules),已拒绝递归删除/移动」)+ protected_content = { relative_path, ruleId, rule_reason }(relative_path 相对被删/被移目录)+ next_step(先单独删除其中那个目录,再删本目录)+ scanned_entries(本次扫描条目数);仅扫描超预算 / 读目录失败时另有 budget_exceeded(depth/entries/readdir_error 之一)。

扫描预算与 fail-closed:条目上限 50 000、深度上限 32;超预算或读目录失败 → 一律拒绝(错误码仍是 protected_content_inside,带 budget_exceeded)。不存在「扫不完就放行」的路径。生效范围:trash(目录 + recursive:true)与 move(mode:'move',源侧);copy 与单文件删除不触发。

行为代价(如实记录):父目录里有非空受保护子树时,它及其所有上级永远无法经本工具删除或移走;跑过 npm install、是 git 仓库、含 .ssh/.aws 的项目目录因此都不可删,且每次递归都要全量扫子树。

6.5 局部不可读的处置口径

要堵的洞:readdir 失败(ACL 拒绝列举、EACCES/EPERM 等)若被静默吞掉,该目录及其整棵子树会从结果里消失,而返回体仍是 ok:true——这比报错更难发现。

处置口径(四处目录遍历统一:find_files、list_directory、count_text 目录模式、目录统计):

#

规则

说明

1

不整条失败

局部不可读不升级为错误:顶层 ok:true,已扫到的部分结果照常返回

2

不静默丢弃

该目录计入 skipped,并在 skippedBy.unreadable 记数(1 个不可读目录 = 1 条,不按其下文件数)

3

给明细

追加到该函数既有的明细数组(不新增字段):find_files/list_directory 用 skippedSamples,count_text 用 skippedDetails;每条 { path, reason:'unreadable' },path 为 posix 风格,上限 20 条

4

敏感不带 path

命中敏感规则的条目只给 { reason:'unreadable' },不带 path(沿用敏感不泄露纪律)

5

顶层仍 fail-closed

列/扫的就是那个目录本身、且它读不出来 → 仍是 io_error,不降级为 skipped

6

不改既有返回结构

未遇到不可读目录时返回体与改前逐字一致:skipped/skippedBy/skippedSamples 三件套仅在真的遇到不可读目录时出现

7. 读取

  • 默认最多 2000 行 / 64 KiB(readCaps),超出给 truncated:true 与 nextStartLine;显式 count 可突破行数上限。

  • 重复读同一文件命中缓存(cached:true/unchanged:true,正文不再返回);文件变化后自动失效,强制取正文用 force_read:true。

  • 二进制只返回元信息(binary:true、reason:'binary_detected')与 sha256;判定三处一致(read_text/find_files/count_text)。空文件 totalLines=0(与 count_text 的 lines=0 一致)。

7.1 read_text 与字节区间读

两组区间参数互斥,同传 → invalid_args:

组

参数

语义

行区间

start_line(1 起)+ count

从第几行开始读多少行;默认上限 2000 行

字节区间

start_byte(≥ 0 的整数)+ max_bytes(≥ 1 的整数,默认 65536)

从第几个字节开始读多少字节

  • start_byte 负数 → invalid_args;≥ 文件长度 → 空正文并提示「起点超出文件长度」;max_bytes 超 65536 按 65536 处理。

  • max_bytes 只约束正文,续读说明附加在外、只受 65536 字节响应体硬上限约束;单行超限时行内截断并标记 lineTruncated:true(给 truncatedLine/truncatedLineBytes),截断时返回 howToContinue。

  • count_text 区间口径与 read_text 对齐(行区间与字节区间都支持);字节区间落在多字节字符中间时回退到字符边界(alignmentAdjusted/alignmentBackoffBytes)。非 UTF-8 文件的字节区间读一律返回 invalid_args——字节区间仅支持 UTF-8/ASCII,与是否安装 iconv-lite 无关;错误信息会提示改用 start_line + count 按行读取,行区间对所有编码都支持。字节边界落在多字节字符中间时的自动回退(alignmentAdjusted / alignmentBackoffBytes)只发生在 UTF-8 字节区间内。

7.2 编码支持

编码

自动探测

备注

UTF-8(带 / 不带 BOM)

支持(BOM → strict 校验)

非法字节序列不会硬判 UTF-8

UTF-16LE / UTF-16BE

支持(含无 BOM 的启发式)

NUL 奇偶位比例 ≥ 60% 且 NUL 数 ≥ 2,再解码校验

GB18030

支持(BOM 84 31 95 33 剥离并回 bom:true)

需要 iconv-lite

Big5

支持

需要 iconv-lite;与 GB18030 自动区分不可靠

  • 显式 encoding 是可靠的唯一覆盖手段:显式给定编码时只按该编码解码(跳过候选尝试与二进制嗅探),返回 encoding 回显实际所用编码;非法编码名 → invalid_args(不在 schema 里设 enum,避免协议层先拒而给出另一套错误)。

  • 探测顺序与 GB18030 / Big5 的歧义见 §4;遇到日文 / 繁体内容请显式传 encoding。

7.3 三处最易混淆的字段

  1. bytes vs fileBytes vs totalBytes

    • bytes = 本次范围的字节数:区间模式 = 区间字节数;非区间模式 = 整文件字节数(此时与 fileBytes 相等);

    • fileBytes = 整个文件有多大;totalBytes = 整棵范围(单文件即文件本身、目录即整棵子树)累计字节数。 区间统计时 bytes 只算区间,fileBytes 始终是整文件——两者不是同一个数。

  2. range.count vs range.returnedCount

    • range.count = 你请求的行数上限;range.returnedCount = 实际返回 / 统计的行数。 请求 300 行但文件只剩 10 行时,count=300、returnedCount=10。

  3. truncated 与 truncatedBy

    • truncated 只回答「不完整」;原因看 truncatedBy:limit(条数)/ max_lines(行数)/ max_bytes(字节)/ scan_limit(扫描预算)——本 MCP 不产生 max_matches_per_file(属检索类工具)。只读 truncated 分不清是哪条上限。

8. 错误码总表

error

触发条件

该怎么办

target_missing

overwrite 且目标不存在、未传 createIfMissing

传 createIfMissing:true,或改用 replace

target_exists

overwrite 且目标已存在、未传 overwriteExisting

传 overwriteExisting:true(可配合 expected_sha256)

version_mismatch

expected_sha256 与实际不符

重新读取取新 sha256 再提交

not_found

oldText 零命中(含缩进作废、字面量不匹配)

看 nearMisses[].exactText 照抄原文

ambiguous

oldText 命中多处

用 candidates[].line/.snippet 补上下文使其唯一

write_root_denied

写类目标不在 writeRoots(发布版默认空数组!)

改到写根内,或先 move(copy)进来

sensitive_denied

命中敏感规则(.env*、*.pem、*.key、.ssh/**、.aws/**、*.credentials.yaml)

不要绕过,请用户提供内容。例外:trash 一个空的 .ssh/.aws 目录走空目录放行(§6.3)→ 成功并带 waived_rule + waived_reason:"empty_directory"(非错误码)

protected_rule_denied

命中保护规则(带 ruleId/reason)

按 reason 处理;受保护目录需人工清理。例外:树形规则下 trash 空目录放行(§6.3)→ ok:true + waived_reason:"empty_directory"

protected_content_inside

递归删/搬整棵目录时子树里有命中树形规则的路径(空子树也算),含 move 传 overwrite:true 覆盖目录的情形(覆盖=整树删除);或扫描超预算(50 000 条 / 32 层)、读目录失败 → fail-closed

不会自动放行;按 next_step 先单独处理 protected_content.relative_path,再删/移父目录;覆盖场景下目标未被改动(§6.4)

recycle_bin_unavailable

仅能力不可用 + FOP_REQUIRE_RECYCLE_BIN=1 时出现;未设该变量时降级执行(永久删 + recyclable:false + warning,不是错误码)。判据:<卷>:\$Recycle.Bin\<SID> 下 $I* 数量没有增加

要「不阻碍」→ 取消严格模式;要「必须可恢复」→ 保持严格并改由用户手工删除;不需回收站 → FOP_ALLOW_PERMANENT_DELETE=1

mixed_eol

原文件混用 CRLF/LF 且用 replace

读出全文统一换行后 overwrite 写回

batch_limit

超过批量上限(带 limit/given)

分批提交

identity_changed

校验后目标发生变化

重试

invalid_args

参数非法(空 paths、path 与 paths 互斥、oldText 为空、批量 overwrite、目标是目录、非法编码名、区间参数互斥等);move 目标已存在却未传 overwrite:true,或 src===dst/dst 在 src 内/src 在 dst 内(闸 C)

按 reason 改正参数;要覆盖就传 overwrite:true,否则换目标名或换不相交的目标

already_applied

status:'already_applied'(非错误,表示此前已生效)

无需再改;查 alreadyAppliedBy

binary

编码探测失败 / 二进制内容不可按文本处理时返回(注意:与 §7 里表示「读到的内容是二进制」的 binary:true 标记字段是两回事)

按元信息处理,或改用脚本按字节处理

aborted

批量编辑 all_or_nothing:true 预校验失败时,随每个文件返回的中止标记

按各文件自己的失败原因逐个处理,修正后重新提交

device_path

路径是设备名(NUL、CON、COM1…)或 /dev/*

换真实文件路径

dependency_unavailable

缺少 iconv-lite 等依赖,无法处理该编码

安装依赖或只处理 UTF-8(§4 / §7.2)

file_too_large

单文件超过 8 MiB 可编辑上限

用脚本处理(批量中仅跳过该文件)

io_error

底层 IO / 编解码 / 校验失败;目录遍历里只用于「顶层」目录本身读不出来 → fail-closed。子树内不可读目录不报错,走 skipped(§6.5)

按 reason 排查;子树被跳过时看 skipped/skippedBy/skippedSamples

scan_limit

历史错误码,现不再作为 error 返回:find_files/list_directory 递归扫描超预算(文件数 20000 或耗时 15000 ms)

现返回 ok:true + truncated:true + truncatedBy:'scan_limit' + reason/hint + scanned/elapsedMs/limit 与部分结果;缩小范围后重试

9. 启用方式

服务是 stdio 传输、长驻进程:被客户端拉起后一直运行,改 index.mjs 必须重启客户端才生效(改 protected.json 是热加载,见 §10.3)。

只读模式:支持 --readonly 启动参数——只注册 7 个只读工具(read_text / get_file_info / list_directory / find_files / count_text / diff / list_protected),调用写类工具会被拦截。适合纯检索场景。

9.1 作为 MCP 客户端注册

通用 mcpServers 格式(Claude Desktop、多数 MCP 客户端通用):

{
  "mcpServers": {
    "file-ops": {
      "command": "node",
      "args": ["D:/tools/mcp-file-ops/index.mjs"],
      "env": { "FILEOPS_CONFIG": "D:/tools/mcp-file-ops/protected.json" }
    }
  }
}

DSH 的 preset 挂载格式(cordis.patch.yml):

- id: mcp-file-ops
  name: '@deepseek-ai/dsh-mcp-client'
  config:
    serverName: file-ops
    transport: stdio
    command: node
    args:
      - D:/tools/mcp-file-ops/index.mjs

挂载后还需把要用的工具名加入该 preset 的工具白名单(allowlists)。

9.2 环境变量

变量

作用

默认

FILEOPS_CONFIG

规则文件路径(替代 <包目录>/protected.json)

未设 → 用包内 protected.json

TYPST_PATH

convert_document 输出 PDF 时的 typst 可执行文件

先扫 PATH,再用内置 fallback

PANDOC_PATH

convert_document 的 pandoc 路径

先扫 PATH,再用内置 fallback

GIT_PATH

diff 用的 git 可执行文件

先扫 PATH,再退回常规安装位置

FOP_ALLOW_PERMANENT_DELETE

=1 强制永久删:跳过回收站、直接删除,permanentDelete:true,不带 warning

未设

FOP_REQUIRE_RECYCLE_BIN

=1 严格模式:回收站能力不可用即拒绝删除 / 拒绝覆盖,绝不降级

未设(宽松降级)

FOP_FORCE_CROSS

=1 把同卷 move 也按跨卷路径处理(复制 + sha256 校验 + 删源),用于验证跨卷分支

未设

外部程序探测顺序:环境变量 → PATH → 内置 fallback(只放常规安装位置)。

10. 保护规则怎么改

10.1 直接编辑 protected.json

  • 文件:<包目录>/protected.json(或 FILEOPS_CONFIG 指向的那份)。编辑前先 list_protected() 看一眼当前生效快照与 config 指纹(configPath/mtime/sha256/规则条数),确认改的是服务端真正在读的那份。

  • 写入前自查:JSON 合法;每条规则必须有 id/scope/pattern 或 patterns/deny/reason;deny 的动作名必须在 read,list,write,edit,trash,move 内;不得出现 per-rule 例外开关字段。

  • protected.example.json 只给 9 条常见规则(node_modules、.git、凭据、密钥、缓存目录等),可按需增删。9 个 ID:R3(node_modules) / R4(.git) / R5(.credentials.yaml) / R8(.env) / R9(.ssh) / R10(.aws) / R11(.pem) / R12(.key) / R15(包管理器缓存目录)。

  • 审计日志要自己保护:若把 audit.enabled 打开并指定 logPath,建议自行加一条规则保护该日志(pattern 覆盖 <你指定的路径> 及其轮转副本,deny 为 trash/move/write/edit)——示例配置里没有这条,不补则日志可被客户端删改。

10.2 管理台用法

仓库内附带 manage-rules.mjs(只用 Node 内置模块,无额外依赖):

node <包目录>/manage-rules.mjs
=== 保护规则管理台 ===
现役: <包目录>/protected.json   最后修改: <时间戳>   规则: <N> 条
[1] 列出全部规则          [2] 新增规则        [3] 修改规则
[4] 删除规则              [5] 试算路径         [6] 校验并写回
[0] 退出

菜单项:1 列出全部规则(编号/范围/路径/deny/reason)、2 新增规则(问答:范围 → 路径 → 拦哪些动作 → 理由 → 确认)、3 修改、4 删除、5 试算路径(「会被哪些规则命中、拦什么动作、能不能读」)、6 校验并写回。单命令模式便于脚本化:

node <包目录>/manage-rules.mjs list
node <包目录>/manage-rules.mjs check "C:/work/projects/app/a.md"
node <包目录>/manage-rules.mjs add --scope file --pattern "C:/work/my.conf" --deny "trash,edit" --reason "手工维护的配置"
node <包目录>/manage-rules.mjs verify
  • list/check/verify 的每个动作都带错误码:敏感类规则 → sensitive_denied;其余保护规则 → protected_rule_denied;放行的动作 → errorCode: null。check 额外输出一行 JSON: {...} 供脚本消费。

  • verify 用固定样例路径输出管理台自己的判定,与 file-ops 实际行为对拍:两者是两套独立实现,不一致说明语义漂移,应修实现而不是改规则。写回前自动备份(<包目录>/backups/protected-<YYYYMMDD-HHMMSS>.json),主文件始终是固定名 protected.json;管理台不表达执行层序,对拍时以现役行为为准(§6)。

10.3 热加载

服务端在每次判定前比对 protected.json 的 mtime + size,变了就重载(hotReload 回报 { enabled:true, configPath, strategy:'mtimeMs+size' })。

  • 改 JSON 立刻生效,不用重启(protected.json 与 FILEOPS_CONFIG 指向的文件一样)。

  • 改 index.mjs 必须重启客户端——它是长驻进程,内存里的实现不会自我替换。

  • list_protected() 返回当前生效快照:writeRoots/batchLimits/readCaps/全部规则(含条数)/enforcement 开关与层序/config 指纹(configPath/mtime/sha256/规则条数)/audit 开关与保留期/hotReload;配置语法错误时另给 configError。用它回答「服务端现在认的是哪一版」。

11. 已知边界与坑

  1. 工具参数里的 \r\n 是字面量(不会被解析成换行)→ 需要真实 CRLF 时,用 read_text 读一个真实含 CRLF 的文件,把返回的 text 原样传回。

  2. 长驻进程:index.mjs 改完必须重启客户端才生效;MCP 层功能验收放在重启之后(protected.json 的规则改动是热加载,无需重启)。

  3. 匹配语义只有一套:字面路径只匹配该路径本身;通配 + /** 结尾匹配该目录之下的所有层级、不含该目录本身;要同时护「整棵树」与「目录本身」,就在同一规则的 patterns 里列两条 pattern(§6.2 / §6.3 / §6.4)。

  4. read_text 默认有行数 / 字节上限,超出要显式 count;max_bytes 只约束正文,续读说明另计。

  5. 写根限制只管本 MCP 的写类操作,管不到外部 shell(如 code-operator 的 pwsh)——后者的写边界由它自己的沙箱(会话工作区)决定。

  6. scope 的已知偏差:通配 pattern 下 scope 不参与匹配(**/*.key 会命中名为 my.key 的目录,过度拒绝);字面路径规则不区分文件 / 目录。要连目录本身一起护,就在 patterns 里显式列 **/xxx。

  7. .tmp/ 是运行时临时目录,不要手工清理:服务按需自动创建,调用外部程序时在其下新建 run-* 存放 stdout/stderr,用完自动删除;删掉不会破坏功能,但清理无收益,且要确认无子进程占用。

  8. 审计日志默认不落盘(enabled:false、logPath:null);开启后返回体带 auditLogged/auditRotated/auditPrevious(未启用时 auditLogged 不出现)。示例规则里没有保护审计日志的规则,开启后请自行加一条(§10.1)。

  9. trash 的可恢复性取决于执行进程权限:探测为不可用即如实降级(deleted-permanently + recyclable:false + warning),绝不谎报 sent-to-recycle-bin;需要硬保证就开 FOP_REQUIRE_RECYCLE_BIN=1。

  10. FOP_TEST_RB_CAP 是内部测试钩子:设为 0 可强制「回收站能力探测」判为不可用,用于验证降级路径;正常使用不要设置。

12. 许可

MIT,完整条款见 LICENSE。

  • 包名 @fastunbeaten/mcp-file-ops,版本 0.1.0;engines.node >= 20;运行时依赖 @modelcontextprotocol/sdk(1.32.2),可选依赖 iconv-lite(缺失时编码能力降级,见 §4 / §7.2)。

  • 实现参考 @modelcontextprotocol/server-filesystem(MIT)的公开行为,按行为自行实现,未复制其源码。

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      Provides sandboxed access to local filesystem operations including directory and file management, content search with glob and regex patterns, and binary file support with configurable safety limits.
      -
    • F
      license
      A
      quality
      D
      maintenance
      Enables localized file system operations such as listing, reading, editing, creating, deleting, and searching files, scoped to the directory where the server is invoked.
      6
      -
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables LLM clients to safely perform file operations such as create, read, edit, delete, move, copy, and more, with every path checked against an explicit permission database managed through a desktop GUI.
      GPL 3.0
    • A
      license
      A
      quality
      C
      maintenance
      Enables reading, writing, editing, searching, and organizing files and directories within allowed root directories, with every tool result size-capped and large text files returned in paged windows instead of all at once. Media reads are rejected above a configurable byte limit, keeping responses bounded while preserving the usual filesystem tool set.
      14
      260 npm
      MIT