Draftly (wps-mcp)

简体中文 | English

在 WPS Office（Mac）里跑一个真正能操作当前文档的 AI 聊天侧边栏，基于官方 JS 加载项对象模型 API + Claude Agent SDK。不是键盘/鼠标模拟， 是通过 MCP 工具直接调用 WPS 文字 / 表格 / 演示的对象模型（Application.CreateTaskPane 等）。

前置条件

• macOS，装了 WPS Office（Mac 版），至少完整打开过一次
• Node.js 20 及以上
• 已安装并登录 Claude Code CLI（claude login）—— Draftly 不管理自己的 API Key，靠本机已登录的 Claude Code CLI 复用你的账号登录态。换一台机器 / 换一个人用，都要先在那台机器上装好并登录 claude CLI。

安装

git clone <this-repo>
cd wps-mcp
bash scripts/install.sh

脚本是幂等的，改了代码之后重跑一次就是升级流程。它会：

1. npm install 装依赖
2. 生成本地共享密钥（.bridge-token，见下面"安全模型"）
3. 把加载项文件复制到 WPS 的加载项目录 （~/Library/Containers/com.kingsoft.wpsoffice.mac/Data/.kingsoft/wps/jsaddons/wps-mcp_）
4. 安装一个 launchd LaunchAgent，让桥接服务随登录自动启动、崩了自动重启

装完之后：

1. 完整重启一次 WPS Office（首次安装、或者 ribbon.xml 有更新时必须重启——功能区按钮定义 WPS 只在启动时读一次，不支持热更新；taskpane.html/main.js 的更新则会自动热更新，不用重启）
2. WPS 里找 "WPS-MCP" 功能区标签，点 "Draftly" 按钮打开侧边栏
3. 连不上就看日志：tail -f ~/Library/Logs/wps-mcp.log

卸载：

launchctl bootout gui/$(id -u)/com.wps-mcp.bridge
rm ~/Library/LaunchAgents/com.wps-mcp.bridge.plist
rm -rf ~/Library/Containers/com.kingsoft.wpsoffice.mac/Data/.kingsoft/wps/jsaddons/wps-mcp_

安全模型

桥接服务监听本机 127.0.0.1:58892，处理 WebSocket 和 HTTP 请求。所有会产生副作用的入口 （两条 WebSocket、/tool、/mcp）都要求 URL 上带 ?token=，这个 token 是安装时随机生成、 落盘到项目根目录 .bridge-token（不进版本库）的本地共享密钥，同一份值会被烤进部署到 WPS 里的 js/token.js。没有这层校验，你电脑上开着的任何一个网页都能直接连上这个端口冒充加载项/面板， 用 MCP 工具改你正在编辑的文档——这不是理论风险，浏览器不会对 WebSocket 连接做同源限制。

架构速览

• addin/ —— WPS JS 加载项：ribbon.xml(功能区)、main.js(对象模型桥接)、taskpane.html(聊天面板 UI)
• server/bridge.js —— 本地 WebSocket/HTTP 桥接，加载项与 MCP server 之间的枢纽
• server/agent.js —— 聊天面板的 /agent WS 处理，用 Claude Agent SDK 的 query() 驱动对话
• server/tools.js + server/index.js —— MCP server（stdio），把 wps_word_*/wps_et_*/wps_wpp_* 工具调用转发到桥接层

server/index.js 会自动探测端口占用：如果 58892 已经被一个常驻实例占了，会转成轻量 stdio 中继， 把工具调用转发过去，而不是抢端口——这样 Agent SDK 自己 spawn 的 MCP server 子进程不会跟常驻服务冲突。

开发

npm test   # node --test，全仓库单测

严格 TDD：改行为之前先写一个会失败的测试。纯逻辑（session/host 处理、流式累加器等）都抽成了 DOM/WS 无关的模块，方便单测；WS/DOM 胶水代码保持薄，靠人读。

已知限制

• 目前只做了 macOS 版 WPS Office，且假设它安装在标准 Container 路径下
• 多用户场景没做——每个用户都要自己装好并登录 claude CLI，Draftly 不做统一鉴权/计费
• 品牌名 "Draftly" 是占位名，正式对外发布前建议再确认一下商标可用性

License

GPL-3.0。基于本项目的修改版本，再分发时也必须以 GPL-3.0 开源。