内容
# Polarion MCP
> **产品页面：** [phillipboesger.github.io/polarion-mcp](https://phillipboesger.github.io/polarion-mcp/) · **Docker 镜像：** `ghcr.io/phillipboesger/polarion-mcp:latest`
一个开源的 **模型上下文协议** 服务器，暴露了 **271 个 Polarion REST 操作**，作为 AI 原生工具 — 适用于 VS Code Copilot、Claude、ChatGPT 自定义 GPT 等，以及任何兼容 MCP 的客户端。
---
## 目录
- [功能](#功能)
- [需求](#需求)
- [快速入门](#快速入门)
- [Docker（推荐）](#docker推荐)
- [本地开发](#本地开发)
- [可用工具](#可用工具)
- [配置](#配置)
- [使用示例](#使用示例)
- [架构](#架构)
- [安全性](#安全性)
- [贡献](#贡献)
- [致谢](#致谢)
- [许可证](#许可证)
---
## 功能
- **严格的类型验证** — Zod 模式验证所有输入，并支持 Polarion 查询语法
- **强化错误处理** — 标准化 MCP 错误，并自动进行令牌净化
- **分页助手** — 内置实用程序，轻松导航结果
- **安全检查** — 验证必需的环境变量，并从不记录敏感数据
- **多重传输** — HTTP（可流式 MCP）和 stdio 支持
- **CI/CD 就绪** — 包括 TypeScript 检查和自动 Docker 发布
---
## 需求
- Node.js v20+
- Polarion 个人访问令牌（PAT），具有读取权限
---
## 快速入门
### Docker（推荐）
镜像会自动发布到 GitHub 容器注册表中，每次推送到 `main` 分支时。
**HTTP 模式**（VS Code Copilot、Claude.ai 连接器、任何 HTTP MCP 客户端）：
```bash
docker run -d \
-e API_BASE_URL=https://your-polarion.com/polarion/rest/v1 \
-e BEARER_TOKEN=your_polarion_pat \
-e MCP_HTTP_TOKEN=your_mcp_secret \
-p 3000:3000 \
--name polarion-mcp \
ghcr.io/phillipboesger/polarion-mcp:latest
```
将您的 MCP 客户端连接到 `http://localhost:3000/mcp`，并使用 `Authorization: Bearer your_mcp_secret`。
**stdio 模式**（VS Code、Claude 桌面版）：
```bash
docker run --rm -i \
-e API_BASE_URL=https://your-polarion.com/polarion/rest/v1 \
-e BEARER_TOKEN=your_polarion_pat \
ghcr.io/phillipboesger/polarion-mcp:latest \
node build/index.js
```
### 本地开发
```bash
npm install
cp .env.example .env
# 编辑 .env — 设置 API_BASE_URL、BEARER_TOKEN、MCP_HTTP_TOKEN
npm run dev:http # 在 :3000 上启动 MCP HTTP 传输
```
参见 `docs/examples.http` 以获取现成的 HTTP 请求示例，以及 `docs/client-example.ts` 以获取完整的 Node.js 客户端示例。
---
## 可用工具
从 Polarion OpenAPI 规范中生成了 271 个工具。以下是一些代表性的示例：
| 工具 | 描述 |
|---|---|
| `getAllWorkItems` | 列出项目中的工作项 |
| `getWorkItem` | 按 ID 获取特定工作项 |
| `getAllDocuments` | 列出项目中的文档 |
| `getDocument` | 获取特定文档 |
| `postWorkItems` | 创建新的工作项 |
| `patchWorkItem` | 更新现有工作项 |
所有工具都接受一个可选的 `rawPath` 参数，以覆盖 REST 端点路径，而无需代码更改 — 在您的 Polarion 版本使用非标准路径时很有用。
完整的工具列表由 `src/tools.ts` 生成，参见 `npm run generate-tools`。
---
## 配置
### 环境变量
```bash
# 必需
API_BASE_URL=https://your-polarion.com/polarion/rest/v1
BEARER_TOKEN=your_polarion_personal_access_token
# HTTP MCP 传输所需
MCP_HTTP_TOKEN=your_mcp_bearer_token # 客户端必须将此令牌发送到 /mcp
# 可选
MCP_HTTP_PORT=3000 # MCP HTTP 服务器端口（默认为 3000）
MCP_ALLOWED_HOSTS=your-host.com # DNS 绑定保护（逗号分隔）
NODE_TLS_REJECT_UNAUTHORIZED=0 # 禁用自签名证书的 SSL 验证
```
---
## 使用示例
### Node.js 客户端
```typescript
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
const client = new Client({ name: "my-client", version: "1.0.0" });
await client.connect(
new StreamableHTTPClientTransport(new URL("http://localhost:3000/mcp"), {
requestInit: { headers: { Authorization: "Bearer your_mcp_secret" } },
})
);
const result = await client.callTool({
name: "getAllWorkItems",
arguments: { projectId: "MYPROJECT", query: "status:open", pageSize: 10 },
});
```
### 分页
所有列表操作都支持 `pageSize` 和 `pageStartIndex` 参数：
```typescript
const page1 = await client.callTool({
name: "getAllWorkItems",
arguments: { projectId: "MYPROJECT", query: "status:open", pageSize: 50, pageStartIndex: 0 },
});
```
---
## 架构
```
src/
config.ts — API 基本 URL、令牌和资源 URL 常量
server.ts — 共享 MCP 服务器工厂（传输无关）
tools.ts — 生成的 MCP 工具定义（271 个工具）
executor.ts — 工具调用调度器
mcp-http-server.ts — 流式 HTTP MCP 传输（远程客户端）
http-server.ts — ChatGPT 自定义 GPT 操作的纯 REST 包装器
index.ts — stdio 入口点（本地 MCP 客户端）
polarion.ts — 资源和提示处理程序
auth.ts — 身份验证助手
utils.ts — 共享实用程序
```
**设计说明：**
- 工具通过 `npm run regenerate` 从 Polarion OpenAPI 规范自动生成。
- REST 路径可能因 Polarion 版本而异。每个工具都支持 `rawPath` 以覆盖端点，而无需代码编辑。
- 按照设计，无缓存。仅在 429/5xx 时重试，并带有短暂的回退。
---
## 安全性
- **令牌验证** — MCP HTTP 服务器在没有 `MCP_HTTP_TOKEN` 的情况下拒绝启动；每个 `/mcp` 请求都必须提供它作为 Bearer 令牌
- **凭证隔离** — Polarion 凭证（`API_BASE_URL`、`BEARER_TOKEN`）保留在服务器端，永远不会暴露给 MCP 客户端
- **DNS 绑定保护** — 可选的 `MCP_ALLOWED_HOSTS` 允许列表验证每个请求的 `Host` 头
- **日志中没有机密** — 令牌会自动从所有日志输出和错误消息中删除
---
## 贡献
欢迎贡献。要开始：
```bash
npm install
npm run typecheck # TypeScript 检查
npm run build # 编译到 build/
npm run dev:http # 在本地运行
```
要从最新的 Polarion OpenAPI 规范重新生成工具：
```bash
npm run regenerate # 下载规范，生成工具，构建和测试
```
在提交较大的更改之前，请先打开一个问题，以便我们讨论方法。拉取请求应包括更改内容和原因的描述。
---
## 致谢
🙏 感谢 [@Jonasdero](https://github.com/Jonasdero)，其工作是本 MCP 服务器的基础。
---
## 许可证
[MIT](LICENSE) © Phillip Bösger
