# WPS Office MCP 连接包

通过 MCP 协议（Model Context Protocol）实现 AI 助手与 WPS Office 的集成，支持对 WPS 文字（Writer）、表格（ET）、演示（WPP）的自动化操作。

MCP Server 安装时从 GitHub [lc2panda/wps-skills](https://github.com/lc2panda/wps-skills) 自动克隆并编译，提供 231+ 个工具。

---

## 架构说明

```
AI 助手 (Claude Code / Cursor / WorkBuddy / 等)
    │
    │  MCP 协议 (stdio)
    ▼
┌──────────────────────────────────┐
│  wps-mcp-server (node 子进程)     │
│  安装时 git clone + npm build     │
│  ┌────────────────────────────┐  │
│  │  wps-mcp-addon (WPS 加载项) │  │
│  └────────────────────────────┘  │
└──────────────┬───────────────────┘
               │ PowerShell COM 自动化
               ▼
┌──────────────────────────────────┐
│  WPS Office 进程                  │
│  (Writer / ET / WPP)             │
└──────────────────────────────────┘
```

**关键组件：**
1. **wps-mcp-server** — MCP 协议服务端，从 GitHub 自动克隆并编译为 `dist/index.js`
2. **wps-mcp-addon (WPS 加载项)** — 安装在 WPS jsaddons 目录中的 JS 插件，提供 COM 通信通道
3. **PowerShell COM 桥接** — 通过 WPS COM 接口自动化操作 WPS Office

---

## 文件结构

```
wps-office-mcp/
├── README.md                   ← 本文件：安装使用说明
├── package.json                ← npm 脚本入口
├── install-wps-mcp.ps1         ← 一键安装/卸载脚本
├── start-wps-mcp-server.ps1    ← MCP Server 启动脚本（前台/后台/停止）
└── wps-addin/                  ← WPS 加载项文件（wps-mcp-addon）
    ├── manifest.xml            ← 加载项注册清单（wps/et/wpp 三端注册）
    ├── ribbon.xml              ← WPS 功能区按钮布局
    ├── index.html              ← 加载项入口页面
    └── js/
        └── main.js             ← 核心脚本（COM 桥接模式）
```

> **注意**：`wps-mcp-server/` 目录不在包中，执行 `-InstallServer` 时从 GitHub 自动克隆。

---

## 快速开始

### 前置依赖

| 软件 | 版本要求 | 用途 |
|------|----------|------|
| WPS Office | 2019+ / 个人版 / 专业版 | 办公软件 |
| Node.js | >= 18.0.0 | 编译 MCP Server |
| Git | 任何版本 | 从 GitHub 克隆代码 |
| PowerShell | Windows 自带 | 安装脚本和 COM 桥接 |

### 一键安装

以 **管理员身份** 打开 PowerShell，执行：

```powershell
cd <本包目录>

# 安装全部组件（WPS 加载项 + 从 GitHub 下载并编译 MCP Server）
.\install-wps-mcp.ps1 -Action Install -InstallServer
```

或使用 npm 脚本：

```bash
npm run install:all
```

> 执行过程：
> 1. 关闭所有 WPS 进程
> 2. 将 `wps-addin/` 复制到 `%APPDATA%\Kingsoft\WPS\jsaddons\wps-mcp-addon_\`
> 3. 更新 `publish.xml` 注册加载项
> 4. 更新 `authaddin.json` 配置 wps/et/wpp 三端
> 5. `git clone --depth 1` 下载 MCP Server 源码
> 6. `npm install && npm run build` 编译
> 7. 已有克隆时自动 `git pull` 更新

### 仅安装 WPS 加载项（手动）

1. **关闭所有 WPS Office 程序**（Writer、ET、WPP 全部关闭）
2. 将 `wps-addin/` 文件夹复制到 WPS 加载项目录：

   ```
   %APPDATA%\Kingsoft\WPS\jsaddons\wps-mcp-addon_\
   ```

3. **编辑** `%APPDATA%\Kingsoft\WPS\jsaddons\publish.xml`，添加：

   ```xml
   <jsplugin name="wps-mcp-addon" type="wps,et,wpp" url="wps-mcp-addon_/" enable="enable_dev"/>
   ```

### 启动 MCP Server

**stdio 模式**（默认，MCP 客户端直接启动子进程）：

```powershell
.\start-wps-mcp-server.ps1               # 前台运行（测试用，Ctrl+C 停止）
.\start-wps-mcp-server.ps1 -Mode background  # 后台运行
.\start-wps-mcp-server.ps1 -Stop            # 停止后台进程
```

**HTTP SSE 模式**（独立 HTTP 服务，WorkBuddy 通过端口连接）：

```powershell
.\start-wps-mcp-server.ps1 -HTTP                        # 前台，端口 18000
.\start-wps-mcp-server.ps1 -HTTP -Mode background        # 后台
.\start-wps-mcp-server.ps1 -HTTP -Mode background -Port 8080  # 自定义端口
```

> HTTP 模式启动后，WorkBuddy 通过 `http://localhost:18000/sse` 连接。
> 首次启动会自动安装依赖（express, cors, @modelcontextprotocol/sdk）。

### 启动 WPS Office

1. 打开 WPS Office（推荐先打开 **WPS Writer**）
2. 检查功能区顶部是否出现 **"MCP助手"** 选项卡
3. 点击 → **"连接状态"** 按钮，确认初始化成功
4. 如果看不到该选项卡，请重启 WPS Office

### 配置到 AI 工具

提供两种连接方式：

#### stdio 模式（默认，通用）

在 AI 工具配置文件中添加：

```json
{
  "mcpServers": {
    "wps-office": {
      "command": "node",
      "args": ["<本包绝对路径>/wps-mcp-server/wps-office-mcp/dist/index.js"]
    }
  }
}
```

#### HTTP SSE 模式（独立 HTTP 服务）

先启动 HTTP 服务：`.\start-wps-mcp-server.ps1 -HTTP -Mode background`

然后在 AI 工具中配置：

```json
{
  "mcpServers": {
    "wps-office": {
      "url": "http://localhost:18000/sse",
      "transport": "http"
    }
  }
}
```

配置文件位置：

| 客户端 | 配置文件 |
|--------|----------|
| WorkBuddy | `~/.workbuddy/mcp.json` |
| Claude Code | `~/.claude/settings.json` |
| Cursor | 项目根目录 `.cursor/mcp.json` |
| Codex CLI | `~/.codex/config.toml` |
| 其他 | 参考各工具文档 |

---

## 卸载

```powershell
# 卸载 WPS 加载项
.\install-wps-mcp.ps1 -Action Delete

# 卸载加载项 + 删除 MCP Server 目录
.\install-wps-mcp.ps1 -Action Delete -InstallServer

# 静默卸载
.\install-wps-mcp.ps1 -Action Delete -Force
```

---

## 使用说明

### 基本功能

| 功能 | 说明 |
|------|------|
| 新建文档 | 在 WPS 中创建空白 Word/Excel/PPT |
| 插入文本 | 在光标处或指定位置写入内容 |
| 读取文档 | 获取当前文档的标题、内容、字数等 |
| 另存为 | 保存文档到指定路径 |
| 查找替换 | 在文档中搜索并替换文本 |
| 设置格式 | 调整字体、颜色、段落等样式 |
| 插入表格/图片 | 在文档中插入表格和图片 |
| 插入页眉/页脚 | 添加文档页眉页脚 |

### 高级功能（231+ 工具）

| 应用 | 工具数 | 主要能力 |
|------|--------|---------|
| Excel | 82 | 公式、图表、透视表、数据验证、条件格式、宏 |
| Word | 32 | 模板填写、批注、书签、目录生成、修订 |
| PPT | 112+ | 动画、3D、母版、形状、数据可视化、幻灯片 |
| 通用 | 9+ | 保存、格式转换、连接检测 |

### 常用命令示例

```
"在 WPS 中新建一个空白文档"
"在当前文档中插入文字：xxxx"
"保存文档到桌面，文件名：xxx.docx"
"把文档中所有的 'abc' 替换为 'xyz'"
"读取当前文档内容"
"插入一个 3x5 的表格"
```

---

## 脚本命令速查

```powershell
# 安装全部
.\install-wps-mcp.ps1 -Action Install -InstallServer

# 仅安装加载项
.\install-wps-mcp.ps1 -Action Install

# 自定义加载项名称
.\install-wps-mcp.ps1 -Action Install -AddonName "my-addon"

# 指定源文件夹
.\install-wps-mcp.ps1 -Action Install -SourcePath "D:\my-addon"

# 卸载
.\install-wps-mcp.ps1 -Action Delete [-Force]

# 启动 MCP Server（前台）
.\start-wps-mcp-server.ps1

# 启动 MCP Server（后台）
.\start-wps-mcp-server.ps1 -Mode background

# 停止后台 MCP Server
.\start-wps-mcp-server.ps1 -Stop

# 启动 HTTP SSE 服务（前台）
.\start-wps-mcp-server.ps1 -HTTP

# 启动 HTTP SSE 服务（后台，自定义端口）
.\start-wps-mcp-server.ps1 -HTTP -Mode background -Port 8080
```

```bash
# npm 快捷方式
npm run install:all        # 安装全部
npm run install:addon      # 仅安装加载项
npm run install:server     # 仅编译 MCP Server（stdio）
npm run start:http         # 启动 HTTP SSE 桥接服务
```

---

## 故障排查

| 问题 | 原因 | 解决方法 |
|------|------|----------|
| WPS 未响应 | WPS 未运行 | 打开 WPS Writer/ET/WPP |
| "PowerShell COM 调用失败" | COM 注册未就绪 | 以管理员身份运行 WPS 一次 |
| 看不到 "MCP助手" 选项卡 | 加载项未正确安装 | 确认 `publish.xml` 配置正确，重启 WPS |
| 操作无响应 | 文档未打开 | 确保 WPS 中已打开一个文档 |
| 权限错误 | PowerShell 执行策略限制 | 运行 `Set-ExecutionPolicy RemoteSigned -Scope CurrentUser` |
| stdio MCP 无法启动 | 未安装 MCP Server | 运行 `.\install-wps-mcp.ps1 -Action Install -InstallServer` |
| git clone 失败 | 无 Git 环境 | 安装 Git：https://git-scm.com |
| 编译失败 | Node.js 版本过低 | 升级到 Node.js >= 18.0.0 |
| HTTP 模式端口被占用 | 已有进程占用端口 | 使用 `-Port` 指定其他端口，或先停止占用进程 |
| HTTP 桥接依赖安装失败 | 网络问题 | 手动执行 `npm install` |
| PowerShell 脚本被禁止 | 执行策略限制 | 运行 `Set-ExecutionPolicy RemoteSigned -Scope CurrentUser` |

---

## 技术细节

| 项目 | 说明 |
|------|------|
| **通信协议** | MCP over stdio / MCP over HTTP SSE |
| **HTTP 端口** | 18000（可通过 `-Port` 参数自定义） |
| **WPS 控制方式** | PowerShell COM 自动化 |
| **WPS 加载项** | JS 插件模式，WPS 原生加载项 API |
| **MCP Server 技术栈** | TypeScript + @modelcontextprotocol/sdk + winston |
| **HTTP 桥接技术栈** | Node.js + Express + @modelcontextprotocol/sdk |
| **工具数量** | 231+（持续增长） |
| **支持版本** | WPS Office 2019+ / 个人版 / 专业版 |
| **许可证** | MIT |

### 组件来源

| 组件 | 来源 | 方式 |
|------|------|------|
| WPS 加载项 (wps-addin) | 基于 [lc2panda/wps-skills](https://github.com/lc2panda/wps-skills) 的 `wps-claude-addon` (MIT) 修改 | 内置 |
| MCP Server | [lc2panda/wps-skills](https://github.com/lc2panda/wps-skills) (MIT) | 安装时 `git clone` |
| HTTP 桥接 (http-bridge-server.js) | 本包内部 | 内置，首次启动时自动 `npm install` 依赖 |
| COM 桥接脚本 | wps-skills 内置 | 含在克隆代码中 |

> **版权声明**：本项目遵循 MIT License。WPS 加载项 (wps-addin/) 基于 [lc2panda/wps-skills](https://github.com/lc2panda/wps-skills) 的原始代码修改，原始版权归 lc2panda 所有。

---

## 更新日志

- 2026-07-04：初始版本，含 WPS 加载项 + GitHub 自动下载 MCP Server + 启动脚本