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 をインストールしてログインしておく必要があります。

Related MCP server: wps-mcp-server

インストール

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 リクエストを処理します。副作用を生じるすべてのエントリポイント （2 つの WebSocket、/tool、/mcp）は URL に ?token= を必須とします。この token はインストール時にランダム生成され、 プロジェクトルートの .bridge-token に保存されるローカル共有キーです（バージョン管理には含まれません）。同じ値が WPS にデプロイされる js/token.js にも焼き込まれます。この検証がないと、あなたのコンピュータで開いている任意の Web ページが、このポートに直接接続してアドイン/パネルになりすまし、 MCP ツールを使って編集中のドキュメントを変更できてしまいます。これは理論上のリスクではなく、ブラウザは WebSocket 接続に対して同一オリジン制限を適用しません。

アーキテクチャ概要

• addin/ — WPS JS アドイン：ribbon.xml（リボン）、main.js（オブジェクトモデルブリッジ）、taskpane.html（チャットパネル UI）

• server/bridge.js — ローカル WebSocket/HTTP ブリッジ。アドインと MCP サーバー間のハブ

• server/agent.js — チャットパネルの /agent WS 処理。Claude Agent SDK の query() で対話を駆動

• server/tools.js + server/index.js — MCP サーバー（stdio）。wps_word_*/wps_et_*/wps_wpp_* ツール呼び出しをブリッジ層に転送

server/index.js はポートの使用状況を自動検出します。58892 がすでに常駐インスタンスによって使用されている場合は、ポートを奪うのではなく、軽量な stdio リレーに切り替えてツール呼び出しを転送します。これにより、Agent SDK 自身が spawn した MCP サーバーの子プロセスが常駐サービスと衝突しません。

開発

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

厳密な TDD：動作を変更する前に、失敗するテストを書きます。純粋なロジック（session/host 処理、ストリーミングアキュムレータなど）はすべて DOM/WS に依存しないモジュールに抽出し、単体テストを容易にしています。WS/DOM のグルーコードは薄く保ち、人間が読めるようにしています。

既知の制限

• 現時点では macOS 版 WPS Office のみ対応しており、標準の Container パスにインストールされていることを前提としています

• マルチユーザーシナリオには未対応です。各ユーザーが自分で claude CLI をインストールしてログインする必要があり、Draftly は一元的な認証/課金を行いません

• ブランド名「Draftly」は仮の名前です。正式に公開する前に商標の利用可能性を再確認することをお勧めします

ライセンス

GPL-3.0。本プロジェクトに基づく修正版は、再配布時にも GPL-3.0 でオープンソースにする必要があります。