Polarion MCP Server
by suzike
README.md
# Polarion MCP Server
[](https://github.com/suzike/polarion-mcp-server/actions/workflows/ci.yml)
[](CHANGELOG.md)
[](LICENSE)
[](package.json)
一个开源、可安装、带写入防护的 Polarion Model Context Protocol（MCP）服务器。它通过目标 Polarion 安装自带的 SOAP Web Services 读取 LiveDoc、工作项和追踪关系，并在明确确认后执行创建、修改和删除。
> Windows 提供一键安装和 DPAPI 凭据加密。Linux/macOS 可以使用 Node.js 与环境变量手动运行。仓库不包含任何账号、密码、token、cookie、私有服务器地址、项目 ID 或需求正文。
## 主要能力
| 工具 | 作用 | 副作用 |
|---|---|---|
| `polarion_status` | 检查 WSDL、凭据和 SOAP 认证 | 无 |
| `polarion_get_document` | 读取 LiveDoc/Module 元数据 | 无 |
| `polarion_list_document_requirements` | 分页读取文档内工作项 | 无 |
| `polarion_get_work_item` | 按 ID 读取工作项、描述和链接 | 无 |
| `polarion_query_work_items` | 执行限定到项目的 Lucene 查询 | 无；需要查询权限 |
| `polarion_create_work_item` | 在项目或指定 LiveDoc 中创建工作项 | 创建 |
| `polarion_update_work_item` | 选择性修改标题、描述、类型或状态 | 修改 |
| `polarion_delete_work_item` | 删除工作项并识别 Polarion tombstone | 破坏性 |
完整验证边界见 [功能覆盖矩阵](docs/FUNCTIONAL-COVERAGE.md)。
## 工作原理
MCP 进程不抓取网页、不读取浏览器 cookie，也不绕过 Polarion 权限。浏览器自动关联只负责把当前 Polarion 标签页 URL 交给 MCP；需求数据的读取和写入仍全部通过 SOAP MCP 完成。
## Windows 一键安装
### 前置条件
- Windows 10/11
- Node.js 20 或更高版本
- Git
- Codex CLI（`codex` 命令可用）
- 可访问的 Polarion 服务器，其 `/polarion/ws/services/*?wsdl` 已开放
- 具有相应项目权限的 Polarion 账号或 PAT
### 1. 克隆
```powershell
git clone https://github.com/suzike/polarion-mcp-server.git
cd polarion-mcp-server
```
### 2. 安装与注册
交互式安装：
```powershell
.\scripts\install.ps1
```
安装器会：
1. 检查 Node.js、npm 和 Codex CLI；
2. 执行 `npm ci`、严格编译和测试；
3. 询问 Polarion 地址与认证方式；
4. 在 Windows 安全凭据提示中录入密码或 PAT；
5. 备份现有 `~/.codex/config.toml`；
6. 注册用户级 `polarion` MCP；
7. 验证 Codex 能读取新配置。
非交互配置示例（凭据仍会通过安全提示输入）：
```powershell
.\scripts\install.ps1 `
-BaseUrl "https://polarion.example.com/polarion" `
-DefaultProject "MY_PROJECT" `
-DefaultDocumentLocation "Requirements/Software Requirements" `
-AuthMode password `
-Force
```
安装完成后重启 Codex。
### 3. 检查环境
```powershell
.\scripts\doctor.ps1
codex mcp get polarion
```
## 凭据处理
凭据绝不会进入仓库或 `config.toml`。Windows 安装流程默认写入：
```text
%LOCALAPPDATA%\PolarionMcp\credentials.json
```
其中 secret 使用 Windows DPAPI 绑定到当前 Windows 用户加密，文件 ACL 禁用继承并只允许当前用户访问。MCP 启动时，launcher 将 secret 临时注入子进程环境，退出时立即清除。
重新设置凭据：
```powershell
.\scripts\setup-credentials.ps1 -AuthMode password
# 或
.\scripts\setup-credentials.ps1 -AuthMode access_token
```
不同 Polarion 服务器可能禁用 PAT SOAP 登录。此时应使用密码认证，或联系管理员启用 `AccessToken` 认证。
## 使用方法
重启 Codex 后，可以直接说：
```text
检查 Polarion 连接状态。
读取项目 MY_PROJECT 的需求文档 Requirements/Software Requirements。
读取工作项 REQ-123，并列出它的追踪链接。
查询 MY_PROJECT 中状态为 approved 的 requirement，最多返回 20 条。
```
### 当前浏览器项目自动关联
在支持浏览器控制的 MCP Host 中，可以说：
```text
读取当前浏览器打开的 Polarion 文档前 20 条需求。
```
Host 从当前激活标签页 URL 中取得 `#/project/{projectId}/...`，再把完整 URL 传入工具的 `polarion_url` 参数。MCP 会校验 URL 必须与配置的 Polarion 服务同源，并自动解析项目和 wiki 文档位置。
如果 Host 没有浏览器能力、同时存在多个无法判断的标签页，或当前标签不是 Polarion，则显式提供 `project_id`。
## 创建、修改与删除
写工具不允许静默使用默认项目。必须显式传入 `project_id` 或 `polarion_url`，并提供精确确认值：
| 操作 | 确认值 |
|---|---|
| 创建 | `CREATE:<projectId>` |
| 修改 | `UPDATE:<projectId>:<workItemId>` |
| 删除 | `DELETE:<projectId>:<workItemId>` |
示例对话：
```text
在 MY_PROJECT 创建一条 task，标题为“接口检查”。执行前先给我预览并询问确认。
```
Host 应先展示项目、类型、标题和描述；只有用户明确确认后才传入确认字符串。Polarion 仍会执行账号权限、类型配置、工作流和审计检查。
## 手动运行与其他 MCP Host
构建：
```powershell
npm ci
npm run build
```
Windows 推荐使用安全 launcher：
```powershell
$env:POLARION_BASE_URL = "https://polarion.example.com/polarion"
$env:POLARION_PROJECT_ID = "MY_PROJECT" # 可选
$env:POLARION_NODE_PATH = (Get-Command node).Source
.\scripts\start-secure.ps1
```
Linux/macOS 可由密码管理器或进程管理器提供环境变量，再运行：
```bash
export POLARION_BASE_URL="https://polarion.example.com/polarion"
export POLARION_AUTH_MODE="access_token"
export POLARION_ACCESS_TOKEN="$(your-secret-manager read polarion-token)"
node dist/index.js
```
不要把 secret 写入已跟踪的 `.env` 文件或 MCP JSON 配置。
## 更新与卸载
更新：
```powershell
git pull --ff-only
npm ci
npm test
npm run build
```
卸载注册但保留加密凭据：
```powershell
.\scripts\uninstall.ps1
```
同时删除当前 Windows 用户的加密凭据：
```powershell
.\scripts\uninstall.ps1 -RemoveCredentials
```
## 验证和开发
```powershell
npm test # 严格编译 + 单元/契约测试
npm run smoke # MCP 协议和 8 个工具清单
npm audit --omit=dev # 生产依赖漏洞检查
```
认证集成测试需要自行设置非秘密目标参数：
```powershell
$env:POLARION_BASE_URL = "https://polarion.example.com/polarion"
$env:POLARION_TEST_PROJECT_ID = "SANDBOX_PROJECT"
$env:POLARION_TEST_DOCUMENT_LOCATION = "Requirements/Test Document"
$env:POLARION_TEST_WORK_ITEM_ID = "REQ-1"
npm run integration:secure
```
真实写入自测默认拒绝执行。只有在得到明确授权并选择可丢弃项目后才设置：
```powershell
$env:POLARION_TEST_PROJECT_ID = "SANDBOX_PROJECT"
$env:POLARION_CONFIRM_LIVE_WRITE_TEST = "CREATE_UPDATE_DELETE:SANDBOX_PROJECT"
npm run integration:write-self-test
```
该测试创建项目级临时项、修改后删除，不会主动加入 LiveDoc。不要对正式需求文档运行写入自测。
## 已知条件与限制
- `polarion_query_work_items` 需要对应 SOAP 查询权限；有些账号能直接读取已知 ID，但不能执行全局 Lucene 查询。
- 工作项类型、状态和工作流因 Polarion 项目而异，创建工具不提供通用默认类型。
- 创建到 LiveDoc 的 SOAP 请求具有契约测试，但发布前没有在正式文档中执行破坏性验证。
- 当前浏览器自动关联由 MCP Host 编排，不是 MCP 直接读取浏览器。
- Windows DPAPI 安装脚本仅支持 Windows；其他系统使用环境变量或自行接入系统 keychain。
## 文档
- [安装与故障排查](docs/INSTALLATION.md)
- [架构](docs/ARCHITECTURE.md)
- [功能覆盖矩阵](docs/FUNCTIONAL-COVERAGE.md)
- [工具参数参考](docs/TOOLS.md)
- [安全模型](docs/SECURITY-MODEL.md)
- [变更记录](CHANGELOG.md)
- [贡献指南](CONTRIBUTING.md)
- [安全策略](SECURITY.md)
## License
[MIT](LICENSE) © 2026 suzike
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessSyncing