Draftly (wps-mcp)

Simplified Chinese | English

Run an AI chat sidebar that actually operates the current document in WPS Office (Mac), based on the official JS add-in object model API + Claude Agent SDK. Not keyboard/mouse simulation — it directly calls the WPS Writer / Spreadsheet / Presentation object model through MCP tools (Application.CreateTaskPane, etc.).

Prerequisites

• macOS, with WPS Office (Mac version) installed and fully opened at least once

• Node.js 20 or above

• Claude Code CLI installed and logged in (claude login) — Draftly doesn't manage its own API Key; it reuses your logged-in account state via the locally logged-in Claude Code CLI. If you switch to another machine or another person uses it, you must install and log in to the claude CLI on that machine first.

Related MCP server: wps-mcp-server

Installation

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

The script is idempotent — re-running it after changing the code is the upgrade process. It will:

1. Run npm install to install dependencies

2. Generate a local shared key (.bridge-token, see "Security Model" below)

3. Copy the add-in files to WPS's add-in directory (~/Library/Containers/com.kingsoft.wpsoffice.mac/Data/.kingsoft/wps/jsaddons/wps-mcp_)

4. Install a launchd LaunchAgent so the bridge service starts automatically at login and restarts automatically if it crashes

After installation:

1. Completely restart WPS Office once (required on first install or when ribbon.xml has been updated — WPS only reads ribbon button definitions once at startup, and doesn't support hot updates; taskpane.html/main.js updates are hot-reloaded automatically, no restart needed)

2. In WPS, find the "WPS-MCP" ribbon tab and click the "Draftly" button to open the sidebar

3. If you can't connect, check the logs: tail -f ~/Library/Logs/wps-mcp.log

Uninstallation:

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_

Security Model

The bridge service listens on local 127.0.0.1:58892 and handles WebSocket and HTTP requests. All entry points that produce side effects (the two WebSockets, /tool, /mcp) require ?token= on the URL. This token is a local shared key generated randomly at install time and written to the project root .bridge-token (not in version control); the same value is baked into js/token.js deployed to WPS. Without this validation, any webpage open on your computer could directly connect to this port, impersonate the add-in/panel, and use MCP tools to modify the document you're editing — this isn't a theoretical risk; browsers don't enforce same-origin restrictions on WebSocket connections.

Architecture Overview

• addin/ — WPS JS add-in: ribbon.xml (ribbon), main.js (object model bridge), taskpane.html (chat panel UI)

• server/bridge.js — local WebSocket/HTTP bridge, the hub between the add-in and the MCP server

• server/agent.js — /agent WS handling for the chat panel, uses the Claude Agent SDK's query() to drive conversations

• server/tools.js + server/index.js — MCP server (stdio), forwards wps_word_*/wps_et_*/wps_wpp_* tool calls to the bridge layer

server/index.js auto-detects port conflicts: if 58892 is already occupied by a resident instance, it becomes a lightweight stdio relay and forwards tool calls there instead of grabbing the port — so the MCP server subprocess spawned by the Agent SDK itself won't conflict with the resident service.

Development

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

Strict TDD: write a failing test before changing behavior. Pure logic (session/host handling, streaming accumulator, etc.) is extracted into DOM/WS-independent modules for easy unit testing; WS/DOM glue code stays thin and relies on human review.

Known Limitations

• Only macOS WPS Office is supported for now, and it assumes installation at the standard Container path

• Multi-user scenarios aren't handled — each user must install and log in to the claude CLI themselves; Draftly doesn't provide unified authentication/billing

• The brand name "Draftly" is a placeholder; it's recommended to confirm trademark availability before a public release

License

GPL-3.0. Modified versions based on this project must also be open-sourced under GPL-3.0 when redistributed.