Polarion MCP Server

一个开源、可安装、带写入防护的 Polarion Model Context Protocol（MCP）服务器。它通过目标 Polarion 安装自带的 SOAP Web Services 读取 LiveDoc、工作项和追踪关系，并在明确确认后执行创建、修改和删除。

Windows 提供一键安装和 DPAPI 凭据加密。Linux/macOS 可以使用 Node.js 与环境变量手动运行。仓库不包含任何账号、密码、token、cookie、私有服务器地址、项目 ID 或需求正文。

主要能力

完整验证边界见 功能覆盖矩阵。

Related MCP server: permission-aware-mcp

工作原理

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. 克隆

git clone https://github.com/suzike/polarion-mcp-server.git
cd polarion-mcp-server

2. 安装与注册

交互式安装：

.\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 能读取新配置。

非交互配置示例（凭据仍会通过安全提示输入）：

.\scripts\install.ps1 `
  -BaseUrl "https://polarion.example.com/polarion" `
  -DefaultProject "MY_PROJECT" `
  -DefaultDocumentLocation "Requirements/Software Requirements" `
  -AuthMode password `
  -Force

安装完成后重启 Codex。

3. 检查环境

.\scripts\doctor.ps1
codex mcp get polarion

凭据处理

凭据绝不会进入仓库或 config.toml。Windows 安装流程默认写入：

%LOCALAPPDATA%\PolarionMcp\credentials.json

其中 secret 使用 Windows DPAPI 绑定到当前 Windows 用户加密，文件 ACL 禁用继承并只允许当前用户访问。MCP 启动时，launcher 将 secret 临时注入子进程环境，退出时立即清除。

重新设置凭据：

.\scripts\setup-credentials.ps1 -AuthMode password
# 或
.\scripts\setup-credentials.ps1 -AuthMode access_token

不同 Polarion 服务器可能禁用 PAT SOAP 登录。此时应使用密码认证，或联系管理员启用 AccessToken 认证。

使用方法

重启 Codex 后，可以直接说：

检查 Polarion 连接状态。
读取项目 MY_PROJECT 的需求文档 Requirements/Software Requirements。
读取工作项 REQ-123，并列出它的追踪链接。
查询 MY_PROJECT 中状态为 approved 的 requirement，最多返回 20 条。

当前浏览器项目自动关联

在支持浏览器控制的 MCP Host 中，可以说：

读取当前浏览器打开的 Polarion 文档前 20 条需求。

Host 从当前激活标签页 URL 中取得 #/project/{projectId}/...，再把完整 URL 传入工具的 polarion_url 参数。MCP 会校验 URL 必须与配置的 Polarion 服务同源，并自动解析项目和 wiki 文档位置。

如果 Host 没有浏览器能力、同时存在多个无法判断的标签页，或当前标签不是 Polarion，则显式提供 project_id。

创建、修改与删除

写工具不允许静默使用默认项目。必须显式传入 project_id 或 polarion_url，并提供精确确认值：

示例对话：

在 MY_PROJECT 创建一条 task，标题为“接口检查”。执行前先给我预览并询问确认。

Host 应先展示项目、类型、标题和描述；只有用户明确确认后才传入确认字符串。Polarion 仍会执行账号权限、类型配置、工作流和审计检查。

手动运行与其他 MCP Host

构建：

npm ci
npm run build

Windows 推荐使用安全 launcher：

$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 可由密码管理器或进程管理器提供环境变量，再运行：

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 配置。

更新与卸载

更新：

git pull --ff-only
npm ci
npm test
npm run build

卸载注册但保留加密凭据：

.\scripts\uninstall.ps1

同时删除当前 Windows 用户的加密凭据：

.\scripts\uninstall.ps1 -RemoveCredentials

验证和开发

npm test                 # 严格编译 + 单元/契约测试
npm run smoke            # MCP 协议和 8 个工具清单
npm audit --omit=dev     # 生产依赖漏洞检查

认证集成测试需要自行设置非秘密目标参数：

$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

真实写入自测默认拒绝执行。只有在得到明确授权并选择可丢弃项目后才设置：

$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。

文档

• 安装与故障排查

• 架构

• 功能覆盖矩阵

• 工具参数参考

• 安全模型

• 变更记录

• 贡献指南

• 安全策略

License

MIT © 2026 suzike