在 Claude Code 里给一份 Word 文档降 AI 率

HumanPen 提供的是一个本地 stdio MCP server。所有客户端启动的都是同一条命令 `npx -y humanpen-mcp`，外加一个存放 API key 的环境变量。agent 传给它的是 `.docx` 的绝对路径而不是文本内容，所以文档不会进入上下文窗口，改写后的文件会被写回你的磁盘。

它前面没有远程端点，也没有网关包一层。如果你给别的 server 用过 `mcp-remote` 或 `supergateway`，这里两个都不需要。

最直觉的设计是收一段字符串、返回一段字符串。它同时也是在「人们真正想改写的那种文档」上会散架的设计。

`.docx` 是一个装着若干 XML 部件的 zip。把它的字节读进对话里，你什么可用的东西都得不到；而把它解开摊进上下文，恰好扔掉了「它值得作为文件保存」的那部分结构：标题样式、表格对象、脚注部件、目录背后的那些域。把一本学位论文压平成字符串、改写这个字符串，你解决的是另一个问题。这趟往返的代价，Word 的域、目录与交叉引用里讲得更细。

所以这个工具调用是：进去一个路径，出来一个路径。文件经 HTTPS 上传、处理，结果写回你的磁盘。没有大块东西碰到你的上下文窗口。

最快的路子是让 agent 自己装：开发者页面会给你一句可直接复制的话，把你的客户端指向 MCP 安装指南；粘进去，agent 会自己把指南取回来、弄清你的客户端读的是哪个配置文件，然后回头问你要 key。

手动装的话，Claude Code 是一行：

claude mcp add humanpen -s user -e HUMANPEN_API_KEY=hp_your_key -- npx -y humanpen-mcp

`-s user` 比它看上去重要。默认 scope 是 `local`，只把这个 server 注册给你运行命令的那个目录。第二天你在别的目录打开 Claude Code，发现一个 HumanPen 工具都没有，然后很合理地断定安装失败了。

Codex 读的是 `~/.codex/config.toml`，同一个 server 在那里是一个 `[mcp_servers.humanpen]` 表：`command = "npx"`、`args = ["-y", "humanpen-mcp"]`、`env = { HUMANPEN_API_KEY = "hp_your_key" }`。可直接复制的整段写在安装指南里。

Cursor、Windsurf、Cline 和 Claude Desktop 在各自的配置文件里是同一个形状。桌面端有一个坑：`command` 里要写 `npx` 的绝对路径。跑一下 `which npx`，用它给出的那个。这类应用是由操作系统以一个极简的 `PATH` 启动的，光写命令名往往找不到，而唯一的症状是工具压根不出现。

重启之后会出现七个工具。这篇讲的是 `humanize_document`；`read_detection_report` 和 `check_job` 是配合它用的那两个。

不用网页表单而从 agent 里做，理由是 agent 手里已经有你的文件了——包括躺在同一个文件夹里的那份检测报告。

把两个都交给这次任务。当附上了报告、又没有给出明确的片段清单时，报告里被标红的片段就成为改写范围，文档里其余部分原样不动。反过来，如果你给了明确的清单，那份清单是最终范围，报告只作为任务的附件保留。走 REST API 是同一件事，其中的 API 根地址在开发者页面上能看到：

curl -X POST "$HP_API_ROOT/jobs/humanize" -H "Authorization: Bearer $HP_API_KEY" -F "file=@paper.docx" -F "turnitin_file=@turnitin-report.pdf" -F "strategy=balanced" -F "additional_instructions=Keep terminology and citations unchanged."

积分按实际被改写的词数计，所以一个按报告划范围、只覆盖四个标红段落的任务，就按这四段计价。Skill、MCP 和 API 三条路花的是同一个余额，而没有完成的任务不计费。

模型看不到输出。

一次跑完的调用交回来的是这次任务的一张回执：文件写到了哪里、花了多少、词数怎么变的。没有内容，没有 diff。你想引导的任何事情，都必须在任务开始前盲写进指令字符串里。

常见的反驳是：客户端有读文件的工具，agent 直接读结果不就行了。它能读出文字——五行 `python-docx` 就能把段落文本抽出来，和原文做 diff。它读不出的是版式有没有活下来，而版式正是你当初传文件而不是传字符串的理由。所以 agent 能告诉你任务成功了、花了多少、现在正文写的是什么，但它没法告诉你第 7 页那张表还在不在。

这一步检查是你的活，在 Word 里做，和任何一次改写之后要做的检查一样：刷新域、数参考文献条数、把带数字的单元格读一遍。完整版见提交前怎么检查一份降过 AI 的 Word 文档。

改写一份真实文档要花几分钟，这在一个围绕「快速工具调用」设计的协议里很别扭。一次调用会等大约 55 秒，然后返回一个 job id 而不是文件。活还在服务端跑着，`check_job` 接着把它取回来。

由此有两件事，在你围着它写循环之前都值得知道。第一，如果你客户端自己的超时比这个等待窗口还短，请求会死在你这边，而任务仍在我们那边跑——补救办法是拿那个你没拿到的 id 去 `check_job`。

第二，返回文件的调用和返回 id 的调用是同一个调用，所以围绕它做的任何自动化，都得同时处理这两种结果，而不能假定回来的一定是文档。

只是想把两段话理顺，这个形状就不对。你为一件本可以用眼睛看完的事，付出了一次文件上传、一个任务、一段等待和一次下载。

到了一整章，这笔账就反过来了：文件不进上下文，中途不会被压平成字符串，范围可以由检测报告来定而不是手工指定。这两者之间某处有一条线，服务端没有任何办法判断你在哪一侧。你自己知道。

它能配哪些客户端？ 任何能启动本地命令的 MCP 客户端。已有文档写明配置的包括 Claude Code、Codex、Cursor、Windsurf、Cline、Claude Desktop、VS Code、OpenCode 等；对其它客户端，约定就是让它以环境变量里带着 `HUMANPEN_API_KEY` 的方式运行 `npx -y humanpen-mcp`。

用 MCP server 需要单独订阅吗？ 不需要。Skill、MCP 和 REST 花的是同一个积分余额，积分按实际被改写的词数计。

agent 能验证结果吗？ 版式这一块不能。调用返回的是任务回执而不是文档；读文件的工具能把正文取回来，但取不回域、表格和样式是否存活。这一步检查得你自己在 Word 里做。

为什么我的工具调用返回的是 job id 而不是文件？ 因为这次任务跑过了那个大约 55 秒的等待窗口。任务在服务端继续跑，拿这个 id 调 `check_job`，好了就会把结果给你。