# WPS Office MCP

面向 Windows 的 WPS Office Model Context Protocol（MCP）桥接器。它通过本机
PowerShell 与 WPS COM 自动化接口，让 Codex 或其他 stdio MCP 客户端检查 WPS
Writer、Spreadsheets 和 Presentation 的活动对象与内容。

> 当前发行版：`1.0.0-hardened.1`。默认 `compact` 配置仅发布 29 个明确选择的
> 读取/检查工具；不会默认开放编辑、保存、删除、导出或任意方法调用。

本仓库是可重新部署的源码包，不包含 WPS Office、账号、许可证、用户文档、真实路径、
访问令牌或日志。使用者需要自行安装并合法使用 WPS Office。

## 设计目标

- 以最小权限连接当前 Windows 用户会话中的 WPS Office。
- 默认只读：compact allowlist 覆盖连接、Writer、Spreadsheets 和 Presentation 检查。
- 移除通用 `wps_execute_method` 分发器，避免绕过工具级边界。
- compact 工具附带 MCP 只读、非破坏、幂等和闭合世界提示。
- 日志目录可配置，请求参数默认脱敏，stdio stdout 默认保持纯净。
- 源码、锁文件、安装/启动脚本和 CI 均可从全新克隆重建。

## 调用链

```text
Codex / MCP client
        │ MCP over stdio
        ▼
WPS MCP server ── compact allowlist / schema validation / redacted logging
        │
        ▼
PowerShell bridge (`scripts/wps-com.ps1`)
        │ Windows COM
        ▼
WPS Writer (`Kwps`) / Spreadsheets (`Ket`) / Presentation (`Kwpp`)
```

完整模块关系、配置档和信任边界见 [架构说明](docs/architecture.md)。

## 运行要求

- Windows 10/11；COM 模式不支持 Linux。
- 已安装且可由当前 Windows 用户启动的 WPS Office。
- Node.js 18 或更高版本，附带 npm。
- Codex 或其他支持 stdio MCP 的客户端。
- PowerShell 5.1 或 PowerShell 7。

## 安装与启动

克隆仓库或解压 Release 后，在普通 PowerShell 中运行：

```powershell
Set-ExecutionPolicy -Scope Process Bypass
.\scripts\setup.ps1
```

该脚本执行锁文件安装、TypeScript 构建和公开包隐私检查。网络受限环境可以在依赖已缓存
时运行 `npm ci --offline`，但不得删除完整性校验或改用未锁定依赖。

手动调试 stdio 服务器：

```powershell
.\scripts\start.ps1
```

正常使用时由插件根目录的 `.mcp.json` 启动 `dist/index.js`。如果客户端不支持相对
`cwd`，请在该客户端的私有配置中填写自己的安装目录；不要提交该文件。

## 配置

`.env.example` 只列出可选变量与安全默认值，不含任何用户信息。服务本身读取进程环境；
可以在 MCP 客户端配置中设置这些变量，或在启动前由用户自己的脚本设置。

| 变量 | 默认值 | 说明 |
|---|---|---|
| `WPS_MCP_TOOL_PROFILE` | `compact` | `compact` 为 29 个只读工具；`full` 为高风险完整目录 |
| `WPS_MCP_LOG_DIR` | `.wps-mcp-logs` | 私有日志目录；已被 Git 忽略 |
| `WPS_MCP_LOG_PARAMS` | `0` | 保持 0，避免记录文档文本、路径或密码 |
| `MCP_CONSOLE_LOG` | `0` | 保持 stdout 纯净，避免破坏 stdio MCP |
| `LOG_LEVEL` | `info` | 日志详细程度 |
| `DEBUG` | `false` | MCP 调试开关 |

## 默认 29 工具

| 领域 | 数量 | 内容 |
|---|---:|---|
| 连接与通用 | 9 | 连通性、活动对象、应用信息、选区 |
| Writer | 6 | 活动/已打开文档、正文、段落、查找、修订状态 |
| Spreadsheets | 7 | 已打开工作簿、单元格/公式/信息、工作表、选区、区域读取 |
| Presentation | 7 | 已打开演示、页数、页面信息/备注/文本框/标题、文本查找 |

实际 allowlist 以 [`.mcp.json`](.mcp.json) 和
`src/server/mcp-server.ts` 中的 `COMPACT_TOOL_NAMES` 为准，两处均应保持 29 项且由 CI
校验。完整工具实现仍保留在源码中，只有显式设置 `WPS_MCP_TOOL_PROFILE=full` 才会注册
写入型目录。

## 授权与风险

- WPS Office 是独立产品，本仓库不提供或绕过其软件许可。
- COM 调用运行在当前 Windows 用户权限下，可访问该用户已打开的文档。
- `full` 配置能够改写、删除、保存、导出、保护或关闭文件，不属于默认安全配置。
- 不应把文档密码放入 `.env`、日志、Issue、CI 或示例；需要密码的写工具只应在受控的
  临时调用中接收。
- 启用 full 前，应取得用户明确授权、确认目标文档并建立可恢复副本。
- 公开 Issue 和测试夹具不得包含真实文档、账号、路径、注释作者或业务数据。

安全报告和部署建议见 [SECURITY.md](SECURITY.md)。

## 开发与测试

```powershell
npm ci
npm run build
npm run verify:public
```

`npm run verify:public` 检查用户目录、私钥材料、明显的嵌入式凭据和误纳入的私有 `.env`。
真实 COM 冒烟测试必须在 Windows 与 WPS Office 上人工执行：先打开一个不含隐私的临时
文档，只测试 compact 工具，不应在 CI 中启动桌面 Office 或上传测试文档。

## 仓库结构

```text
wps/
├─ .codex-plugin/plugin.json      Codex 插件清单
├─ .mcp.json                      可移植、29 工具 compact 配置
├─ .env.example                   无私密值的环境变量模板
├─ skills/wps-office/             Codex 工作流与风险边界
├─ src/
│  ├─ server/                     MCP 服务器、注册表与 profile 过滤
│  ├─ client/                     WPS 客户端与 PowerShell 进程桥接
│  ├─ tools/                      Writer / Excel / PPT / common 工具
│  ├─ types/                      协议和 WPS 类型
│  └─ utils/                      日志与错误处理
├─ scripts/
│  ├─ wps-com.ps1                 Windows COM 实现
│  ├─ setup.ps1 / setup.cmd       锁定依赖与构建
│  ├─ start.ps1 / start.cmd       安全默认启动
│  └─ verify-public-package.mjs   隐私和发布边界检查
├─ docs/architecture.md           调用链和信任模型
├─ package.json / package-lock.json
└─ .github/workflows/ci.yml       构建、清单和隐私检查
```

## 上游与版本

本发行版基于 [`lc2panda/wps-skills`](https://github.com/lc2panda/wps-skills)
提交 `a82533662268b3245f93d8685bc45dffede048b6`。保留原项目 MIT License 和作者归属，
并以 `-hardened.1` 标识本地安全配置差异。完整说明见 [NOTICE.md](NOTICE.md)、
[HARDENING.md](HARDENING.md) 和 [CHANGELOG.md](CHANGELOG.md)。

## 贡献

贡献前请阅读 [CONTRIBUTING.md](CONTRIBUTING.md)。任何新增工具必须说明它属于读取还是
写入能力、是否具有破坏性、应在哪个 profile 发布，以及如何避免记录敏感参数。

项目采用 [MIT License](LICENSE)。