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 요청을 처리합니다. 부작용이 발생하는 모든 진입점(두 WebSocket, /tool, /mcp)은 URL에 ?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/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가 직접 생성한 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으로 오픈소스여야 합니다.