mcp-text-stats

只回数字、不回正文的文本统计 MCP 服务器。

一个极小的 MCP 服务器（stdio 传输），对文件或文本给出行数、汉字数、词数、字节数等统计口径。 结果里只有数字、路径与口径说明，绝不返回任何文件正文片段。

• 纯 JavaScript（ESM），单文件实现：index.mjs

• 唯一运行时依赖：@modelcontextprotocol/sdk@1.32.2（精确锁版本）

• 零第三方分词依赖：分词 / 字素 / 断句全部使用 Node 内置 Intl.Segmenter，脚本分类使用 Unicode 属性正则

• 不做 TypeScript 构建，运行时不联网

• 无状态：同一输入必得同一输出，不含时间戳与随机数

1. 功能与统计口径

count_text 工具返回每个文件的下列指标（以及全部文件的汇总 totals）：

其它行为：

• 编码：只支持 UTF-8 纯文本（txt / md / json / csv / log / 源码等）。用 TextDecoder('utf-8', { fatal: true }) 解码，失败则该文件写入 warning decode_failed，不中断整批。

• 二进制格式：pdf / docx / xlsx / 图片 / 压缩包等扩展名不统计，写入 warning unsupported_format。

• 大文件降级：单文件 > maxBytes（默认 70MB）不读取（file_too_large）；> maxBytesForWordCount（默认 20MB）仍统计字符级指标，但跳过 words 与 sentences（skipped_word_segmentation）。

• 目录递归：自实现的极简 glob（支持 ** 与 *，无第三方依赖）按 include / exclude 过滤，只收集文本类扩展名；单次任务最多 200 个文件，超出截断并写 warning too_many_files。

• 符号链接一律拒绝：既不跟随、也不统计，请传入真实文件路径（warning symlink_rejected）。Windows 目录联接（junction / mount point）同样按链接处理并被拒绝。

• 服务端硬上限：maxBytes 上限 200MB、maxBytesForWordCount 上限 64MB；模型传入更大值会被自动钳制（warning max_bytes_clamped）。

Related MCP server: chinese-char-counter-mcp

2. 安装与运行

npm install          # 安装 @modelcontextprotocol/sdk@1.32.2
npm start            # 等价于 node index.mjs（stdio 传输）

直接运行：

node /absolute/path/to/mcp-text-stats/index.mjs

MCP 客户端配置示例（stdio）。任何兼容 MCP 的客户端通用（如 Claude Desktop）：

{
  "mcpServers": {
    "text-stats": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-text-stats/index.mjs"],
      "env": {
        "TEXT_STATS_ROOTS": "/absolute/path/to/allowed/root"
      }
    }
  }
}

Windows 下 env 中的路径用正斜杠或双反斜杠均可；TEXT_STATS_ROOTS 支持用 ;（也接受 , 与换行）分隔多个绝对路径。

环境变量 TEXT_STATS_ROOTS

服务端固定白名单，模型传入的任何参数都不能放宽这个边界。

• 值为分号分隔的绝对路径白名单，例如 /srv/work/tools;/srv/work/data（Windows 用 ;，也接受 , 与换行）。

• 判定方式：先 path.resolve 规范化，再判断目标是否等于根目录或位于根目录之下（Windows 下大小写不敏感）。

• 不设置（或设为空）时一律拒绝所有路径：每个路径都会得到 outside_allowed_roots 警告且不会被读取。这是安全默认，请显式配置后再使用。

• 不在白名单内的路径同样不统计，写入 warning outside_allowed_roots。

3. 使用

工具名：count_text

3.1 输入参数

3.2 返回结构

只含数字、路径与口径说明，没有正文：

{
  "files": [
    {
      "path": "/absolute/path/to/example.txt",
      "bytes": 42, "bom": false,
      "lines": 1, "paragraphs": 1, "sentences": 2,
      "words": 0, "wordsApproximate": false,
      "graphemes": 14, "codepoints": 14, "utf16Units": 14,
      "han": 12, "kana": 0, "hangul": 0,
      "latin": 0, "cyrillic": 0, "arabic": 0,
      "letters": 12, "digits": 0, "spaces": 0,
      "punctuation": 2, "symbols": 0, "nonWhitespace": 14
    }
  ],
  "totals": { "…": "同上各字段求和" },
  "rules": {
    "unit": "grapheme",
    "lines": "物理行数：与 wc -l 一致……",
    "bom": "检测 UTF-8 BOM(EF BB BF)……",
    "words": "words = Intl.Segmenter……",
    "binaryFormats": "本期只支持 UTF-8 纯文本……"
  },
  "warnings": []
}

files[].path 为规范化后的绝对路径；text 模式下的伪路径为 (inline text)。

4. 注意事项

1. 只回统计数字，不回文件正文。 返回体里只有数字、路径与口径说明，不会出现任何一行原文。

2. 返回体含绝对路径，会暴露本机目录结构。 对外共享工具输出前请自行脱敏。

3. 必须位于 TEXT_STATS_ROOTS 白名单之内，否则只会得到 outside_allowed_roots 警告，文件不会被读取。

4. 不设置 TEXT_STATS_ROOTS 则一律拒绝（安全默认）：所有路径都会被拒绝并给出 outside_allowed_roots。

5. 非 UTF-8 文件会被跳过，并给出 decode_failed 警告，不会中断整批任务。

6. 大文件有上限：单文件 > 70MB 不读取；> 20MB 跳过分词与断句统计（仍给出字符级指标）。

7. 二进制扩展名不支持（pdf / docx / xlsx / 图片 / 压缩包等），需先抽取为文本再统计。

8. 单任务最多 200 个文件，超出则截断并给出 too_many_files 警告。

9. 任何符号链接一律拒绝：既不跟随、也不统计；请传入真实文件路径。直接传入软链接时给出 warning symlink_rejected，其中只包含链接自身的路径，不解析链接目标。Windows 目录联接（junction / mount point）同样被拒绝；穿过链接的路径（如 root/linkdir/file.txt）也会被拒绝。

10. 服务端对 maxBytes / maxBytesForWordCount 有硬上限（200MB / 64MB）：模型传入更大的值会被自动钳制到上限，并给出 warning max_bytes_clamped；请通过 TEXT_STATS_ROOTS 控制可访问范围。

warning code 一览

5. 与其它计数方式的对比

• 不用 grep 的匹配数：grep -c / grep 输出的 Found N matches 是匹配行数，不是字数，也不区分汉字与 ASCII 字母，更没有码点 / 字素簇口径。想用 grep 统计"汉字数"只能靠 [一-龥] 这类范围匹配，既不可靠也随 locale 变化。

• 不用 wc：wc -l / -m / -c 只给行数 / 字符数 / 字节数三件套；它给不出汉字数，也说不清"字符"是码点还是字素簇，更没有句数、段落数、脚本分类与 BOM 标记。

• Intl.Segmenter 零依赖：Intl.Segmenter 已能给出字素簇、词边界与句边界；引入 nodejieba / @node-rs/jieba 之类会带来原生编译、二进制分发与平台差异问题，也会破坏"单文件 + 不联网 + 零构建"的目标。

• 默认不给近似中文词数：ICU 对中文的切分是按词典规则做的近似，词数既不可靠又会随 ICU 版本漂移。默认关闭（CJK 下 words = 0），需要时显式传 wordsForCjk: true，并用 wordsApproximate = true 明确标注近似值，避免被当作事实引用。字符级指标才是稳定可比的。

6. 开发说明

本项目在 AI 协助下开发。 AI 参与了项目的设计取舍、实现与文档编写：统计口径的定义与边界条件、Unicode 口径的选择、大文件降级策略、白名单安全默认以及本文档，均由人与 AI 协作完成。全部代码与文档由人工逐条复核，并在本机真实环境（真实文件、真实 MCP stdio 握手、真实 Unicode 文本）下验证通过。

开发与测试：

npm install
npm test        # node --test test/

仓库内保留的是可复现的最小测试集：test/count.test.mjs，共 5 个用例，分别覆盖：中文样本的计数正确性、"返回体不含正文"契约、"未设置 TEXT_STATS_ROOTS 时拒绝一切路径"的安全默认、maxBytes 超过服务端硬上限时被钳制、以及符号链接／目录联接一律拒绝。开发期曾使用一套规模更大的临时测试（53 项）做交叉验证，该临时套件未随包发布；运行 npm test 即可复现当前保留的全部用例。

7. License

MIT —— 见 LICENSE。