WordCraft 的 MCP 服务和命令行工具

WordCraft 自带一个命令行工具 wordcraft-cli。它不用打开窗口就能转换、查看文档，还能运行 MCP（模型上下文协议）服务，让 Claude 等 AI 智能体新建、编辑和保存文档。WordCraft 里的每个操作都是一条带编号的命令。按 README 的说法，功能区、快捷键、命令行和 MCP 服务用的是同一套命令，共 422 条。

本页整理自 0.7.0 版本的官方文档，下面的配置我们没有亲自试过。如果和实际情况对不上，请以 MCP 文档为准。

wordcraft-cli 在哪里

安装方式	wordcraft-cli 的位置
Windows 安装版（.msi）	`C:\Program Files\WordCraft\wordcraft-cli.exe`；32 位版本在 `C:\Program Files (x86)\WordCraft\`。安装程序不会把它加进 PATH，要写完整路径
Windows 便携版（.zip）	解压后的文件夹里，和 `wordcraft.exe` 放在一起
macOS	要单独下载 Mac 下载页上的 `wordcraft-cli-…-macos-universal.zip`，和 App 一样做了签名和公证
Linux .deb 或 .rpm	`/usr/bin/wordcraft-cli`，已经在 PATH 里
Linux 压缩包（.tar.gz）	解压后文件夹里的 `bin/wordcraft-cli`
Linux Flatpak	用 `flatpak run --command=wordcraft-cli ai.storyteller.wordcraft` 运行。沙盒里它只能访问「文档」和「图片」文件夹，也不能联网
Linux AppImage	用不了，AppImage 只能启动 App 本身

下面的例子都写成 wordcraft-cli。如果它不在 PATH 里，换成完整路径。

转换和查看文档

这几条命令来自 README：

# 转成 PDF，也能转成 odt、rtf、html、md、tex、txt 或 png
wordcraft-cli convert report.docx report.pdf
# 只输出文字
wordcraft-cli text report.docx
# 以 JSON 输出文档结构
wordcraft-cli inspect report.docx

run 对文档执行一串命令，再保存结果。下面的例子从自带的示例文档开始，选中 Membership 这个词，加粗，再存成新文件：

wordcraft-cli run --template sample \
  --cmd 'select.text={"text":"Membership"}' --cmd format.bold --save out.docx

在 Windows PowerShell 里，前面要加 & 和带引号的完整路径：

& "C:\Program Files\WordCraft\wordcraft-cli.exe" convert report.docx report.pdf

通过 MCP 连接 AI 智能体

MCP 服务通过标准输入输出和智能体通信，有两种用法：

不开窗口（wordcraft-cli mcp）：智能体在后台新建、打开、编辑和保存文档。只有这种用法能限制它可以访问的文件夹。
操作正在运行的 App（wordcraft-cli mcp --connect）：你能在 WordCraft 的窗口里看着智能体操作，它还能截图、点击和按键。

Claude Code 用 README 里的这条命令添加：

claude mcp add wordcraft -- wordcraft-cli mcp

其他支持 MCP 的客户端，一般在配置文件里加一段下面这样的 JSON，格式和官方文档一致。command 写 wordcraft-cli 的完整路径。配置文件放在哪里，请查所用客户端自己的说明。

{
  "mcpServers": {
    "wordcraft": {
      "command": "/full/path/to/wordcraft-cli",
      "args": ["mcp"]
    }
  }
}

要操作正在运行的 App，先用控制端口启动 WordCraft，再让 MCP 服务连上去：

wordcraft --control 7981 &
claude mcp add wordcraft-app -- wordcraft-cli mcp --connect 127.0.0.1:7981

在 Mac 上，用 open -a WordCraft --args --control 7981 启动 App；在 Windows 上，在 wordcraft.exe 所在的文件夹里打开 PowerShell，运行 & .\wordcraft.exe --control 7981。

智能体能做什么

工具	作用
`list_commands`	列出 WordCraft 的命令，可以按关键词筛选
`execute`	执行一条命令，比如插入一个 3 × 4 的表格
`batch`	按顺序执行多条命令
`new_document`	新建空白文档、示例文档，或者信函、简历、报告模板
`open_document`、`save_document`	打开 .docx、.doc（只能打开）、.odt、.rtf、.html、.md、.tex、.txt 和 .json；保存时还能输出 PDF 和 PNG
`type_text`、`select_text`	在光标处输入文字，或者选中一段文字
`get_text`、`inspect_document`	读回文档内容，智能体不用截图就能检查自己的结果
`render_page`	把一页渲染成 PNG 图片
`screenshot`、`click`、`key`、`ui_inspect`	只在操作正在运行的 App 时可用

把智能体限制在指定文件夹里

启动服务时指定一个可读文件夹和一个可写文件夹：

wordcraft-cli mcp --automation-read-root /work/project --automation-write-root /work/project/out

{
  "mcpServers": {
    "wordcraft": {
      "command": "/full/path/to/wordcraft-cli",
      "args": ["mcp", "--automation-read-root", "/work/project", "--automation-write-root", "/work/project/out"]
    }
  }
}

按官方文档的说明：

智能体打开或读取的文件，都必须在可读文件夹里，包括文档、模板、图片、邮件合并的数据和用来比较的文档；保存或导出的文件，都必须在可写文件夹里。
读和写是分开授权的。只给可读文件夹，就什么都不能写到磁盘上；想在同一个文件夹里既读又写，就把它写两遍。
通过链接指到文件夹外面的路径，算在文件夹外面；/work2 也不算在 /work 里面。被拒绝的路径会作为普通错误返回给智能体，它可以看到并改正。
两个文件夹都必须已经存在，否则服务会报错退出。
这些限制只对不开窗口的服务有效，不能和 --connect 一起用。桌面 App 目前没有这类限制，所以用 --control 启动的 App 不受限制。
已经打开的文档不受限制，智能体仍然可以读取全部内容，也可以修改。

文档也说明了这些限制防不了什么：路径是先检查、再打开的，如果另一个程序在这两步之间换掉了链接，仍有可能绕过去。所以文件夹限制的作用是让智能体只碰你交给它的文件，而不是防范电脑上的其他软件。

标出智能体改了哪里

修订和批注都记在当前会话的用户名下，默认是 WordCraft User。想把智能体的修改和人的修改区分开，启动服务时给它起个名字：

wordcraft-cli mcp --author "Claude (copyedit)"

让智能体用 review.trackChanges {"value": true} 打开修订。如果不带 value，这条命令会在开和关之间切换：文档保存时修订已经开着，执行后反而会关掉。

操作 App 时怎样防止别人插手

不用 --control 启动 WordCraft，控制端口就不会打开。端口只在本机（127.0.0.1）监听。因为本机任何程序、甚至网页都可能连到这个端口，所以每个请求还要带上窗口的密钥。密钥是 256 位的随机数，App 启动时把它写进设置文件夹里的一个文件，窗口关闭时删掉。密钥不对或者没带，连接会被直接断开。

wordcraft-cli mcp --connect 会自己读取这个密钥，而且只发给本机地址。要操作另一台电脑上的 WordCraft，文档建议用 SSH 转发端口（ssh -L 7981:127.0.0.1:7981 host），再把 WORDCRAFT_CONTROL_KEY 设成那个 App 的密钥。

使用前须知

AI 服务会看到文档内容：WordCraft 本身离线运行，但智能体读到的内容，会发给它背后的 AI 服务。不想让这家服务看到的文档，不要交给智能体处理。
检查结果：文档提醒，WordCraft 不认识的属性名会被直接忽略，不会报错，所以拼错了也不会有提示。让智能体用 inspect_document 读回文档核对。
Alpha 阶段的限制同样存在：智能体写出的文档，和其他 WordCraft 文档有一样的限制，比如分页可能和 Word 不同，也还没有用大量真实的 .docx 文件系统测试过。主要差距见和 Word 对比。
先用副本：在信得过这套配置之前，让智能体只处理副本，或者只能写进单独的文件夹。

资料来源

0.7.0 版本的 docs/mcp.md、docs/control-protocol.md 和 README。各系统里 wordcraft-cli 的位置来自 0.7.0 的打包文件：Windows 安装包定义、Linux 打包脚本和 Flatpak 配置。