Polarion MCP Servers

Polarion MCP 服务

此存储库包含用于集成 Polarion Application Lifecycle Management（ALM）的 Model Context Protocol（MCP）服务实现。

Polarion 工作项可使用以下 MCP 工具：

• get_document_info：获取 Polarion 文档的元数据和自定义字段。
• get_document_outline：获取 Polarion 文档中的所有章节标题（目录）。
• get_document_revision_history：获取 Polarion 文档/模块的修订历史记录。
• get_document_section：获取 Polarion 文档中特定章节标题及其子章节的内容。
• get_workitem：获取工作项的文本内容。可选获取指定修订版本。
• get_workitem_details：获取工作项的详细信息，包括标准字段、自定义字段和关联的工作项。支持通过递归跟踪链接实现可追溯性。
• get_workitem_history：获取工作项的修订历史记录，包括每个修订版本的内容。
• get_workitems_in_module：从 Polarion 模块/文档中查询工作项。固定引用会显示其固定的修订版本，无法解析的引用会报告其 URI。
• list_custom_fields：列出特定工作项类型可用的自定义字段。
• list_documents：列出 Polarion 项目中的所有文档。可选按空间名称和/或标题筛选。
• list_spaces：列出 Polarion 项目中的所有空间名称。
• list_workitem_types：列出当前项目中配置的所有工作项类型。
• search_in_document：在 Polarion 文档中搜索符合搜索词的工作项。
• search_workitems：使用文本内容在整个 Polarion 项目中搜索工作项。
• search_workitems_sql （选择启用）：运行经过验证的只读 SQL 查询（针对 WORKITEM 的单条 SELECT，投影 C_PK），并将其作为 Polarion SQL:(…) 筛选器；适用于无法用纯 Lucene 表达的多表连接读取。仅当 SqlQueryTool:Enabled=true 时才会注册。结果仅限于端点所属的项目。请参阅 RBAC。

项目

• PolarionRemoteMcpServer：面向服务器安装的 Streamable HTTP MCP 服务。无状态，支持可选的 OAuth 2.1 身份验证 和按调用方进行的 RBAC。
• PolarionMcpServer：面向本地工作站安装的控制台版 Polarion 集成 MCP 服务

通过 Docker 和 Linux 服务器运行（推荐）

1. 在 Linux 服务器上创建用于存放配置和日志的目录：

   mkdir -p /opt/polarion-mcp-server
   cd /opt/polarion-mcp-server
   

2. 拉取 Docker 镜像：

   docker pull peakflames/polarion-remote-mcp-server
   

3. 根据 Polarion 配置创建定制的 /opt/polarion-mcp-server/appsettings.json 文件：

   {
     "Logging": {
       "LogLevel": {
         "Default": "Information",
         "Microsoft.AspNetCore": "Warning"
       }
     },
     "AllowedHosts": "*",
     "ApiConsumers": {
       "Consumers": {
         "my_app": {
           "Name": "My Application",
           "ApplicationKey": "your-secure-api-key-here",
           "Active": true,
           "AllowedScopes": ["polarion:read"],
           "Description": "API consumer for my application"
         }
       }
     },
     "PolarionProjects": [
          {
              "ProjectUrlAlias": "starlight", 
              "Default": true,
              "SessionConfig": { 
                  "ServerUrl": "https://polarion.int.mycompany.com/",
                  "Username": "shared_user_read_only",
                  "Password": "linear-Vietnam-FLIP-212824", 
                  "ProjectId": "Starlight_Main", 
                  "TimeoutSeconds": 60
              },
              "PolarionWorkItemTypes": [
                {
                  "id": "requirement",
                  "fields": ["custom_field_1", "priority", "severity"]
                },
                {
                  "id": "defect",
                  "fields": ["defect_type", "found_in_build"]
                }
              ]
          },
          {
              "ProjectUrlAlias": "octopus", 
              "Default": false,
              "SessionConfig": { 
                  "ServerUrl": "https://polarion.int.mycompany.com/",
                  "Username": "some_other_user",
                  "Password": "linear-Vietnam-FLIP-212824", 
                  "ProjectId": "octopus_gov", 
                  "TimeoutSeconds": 60
              }
          },
          {
              "ProjectUrlAlias": "grogu", 
              "Default": false,
              "SessionConfig": { 
                  "ServerUrl": "https://polarion-dev.int.mycompany.com/",
                  "Username": "vader",
                  "Password": "12345", 
                  "ProjectId": "grogu_boss", 
                  "TimeoutSeconds": 60
              }
          }
      ]
   }
   

4. 运行 Docker 容器：

   docker run -d \
     --name polarion-mcp-server \
     -p 8080:8080 \
     -v appsettings.json:/app/appsettings.json \
     peakflames/polarion-remote-mcp-server
   

5. 现在服务应该已启动。MCP 客户端将使用与所需项目配置别名对应的 URL 连接：

   1. Streamable HTTP 传输：http://{{your-server-ip}}:8080/{ProjectUrlAlias}/mcp。

6. 服务还提供：

   • REST API：http://{{your-server-ip}}:8080/polarion/rest/v1/projects/{ProjectId}/...（使用 SessionConfig.ProjectId）
     • 注意： REST API 端点需要通过 X-API-Key 标头进行 API 密钥身份验证
   • API 文档：http://{{your-server-ip}}:8080/scalar/v1（包含身份验证界面）
   • 健康检查：http://{{your-server-ip}}:8080/api/health

7. 📢重要 - 请勿运行服务的多个副本实例，因为副本之间不会共享会话连接。

配置选项

配置文件：

• appsettings.json - 用于生产环境／服务器部署的基础配置。纳入 git 跟踪，且仅包含非机密默认值。
• appsettings.Development.json - 覆盖基础设置，用于本地开发。同样纳入 git 跟踪（仅包含非机密默认值）——在 Development 模式下优先使用。任何填入真实凭据的变体都应保持未提交状态；请参阅 .gitignore。
• .env - 可选的环境变量（从 .env.example 复制），可设置 POLARION_DEFAULT_PROJECT

服务器使用 appsettings.json 中的 PolarionProjects 数组来定义一个或多个 Polarion 实例配置。数组中的每个对象代表一个独立的配置，可通过唯一的 URL 别名访问。

顶层设置	说明
PolarionProjects	（数组）包含一个或多个 Polarion 项目配置对象。
McpAuth	（对象，可选）用于 MCP 端点的 OAuth 2.1 资源服务器身份验证。默认关闭。
Rbac	（对象，可选）针对 MCP 工具调用的逐调用方 Polarion 项目可见性限制。默认关闭；需要启用 McpAuth。
Credentials	（对象，可选）控制 MCP 调用在上游使用谁的 Polarion 凭据。默认沿用当前的共享服务账户行为。

每个项目配置对象：

设置	说明	必填	默认值
ProjectUrlAlias	用于连接 URL（/{ProjectUrlAlias}/mcp）中、标识此配置的唯一字符串。	是	不适用
Default	（布尔值）如果为 true，客户端连接时未指定 ProjectUrlAlias，则使用此配置。只能有一个条目设为 true。	否	false
SessionConfig	（对象）包含此 Polarion 实例的具体连接详情。	是	不适用
PolarionWorkItemTypes	（数组，可选）定义此项目中特定 WorkItem 类型要检索的自定义字段。数组中的每个对象应包含 id（字符串，WorkItem 类型 ID）和 fields（字符串数组，自定义字段名称）。	否	空列表

SessionConfig 对象详情：

设置	说明	必填	默认值
ServerUrl	Polarion 服务器的 URL（例如 "https://polarion.example.com/"）	是	不适用
Username	具有相应权限的 Polarion 用户名。	是	不适用
Password	Polarion 用户的密码。（建议考虑安全的替代方案）	是	不适用
ProjectId	要交互的 Polarion 项目的实际 ID。	是	不适用
TimeoutSeconds	连接超时时间，单位为秒。	否	60
MaxReceivedMessageSize	（可选整数，单位为字节）Polarion 客户端接受的最大响应大小。设置时必须大于零。	否	未设置（无限制，int.MaxValue）

环境变量密码覆盖

无需将密码写入配置文件，只需设置 POLARION_PASSWORD 环境变量。设置后，它会覆盖所有已配置项目的 SessionConfig.Password。

Docker 示例：

docker run -d \
  --name polarion-mcp-server \
  -p 8080:8080 \
  -e POLARION_PASSWORD=your-secret-password \
  -v appsettings.json:/app/appsettings.json \
  peakflames/polarion-remote-mcp-server

这对 PolarionRemoteMcpServer（HTTP）和 PolarionMcpServer（stdio）均适用。

注意：强烈建议使用 POLARION_PASSWORD 环境变量或更安全的凭据存储方式（如 User Secrets、Azure Key Vault 等），而不要将明文密码写入 appsettings.json。

REST API 规范对齐

REST API 的设计与 https://testdrive.polarion.com/polarion/rest/v1/definition 上提供的 官方 Polarion REST API 规范保持一致。我们在 docs/polarion-rest-vq-definition.json 中维护了该规范的本地副本，供实现或扩展端点时参考。

API 密钥身份验证（仅限 REST API）

REST API 端点需要通过 API 密钥进行身份验证。在 appsettings.json 的 ApiConsumers 部分配置 API 使用者：

设置	说明	必填
ApiConsumers.Consumers	以使用者 ID 为键的使用者配置字典	是
Name	API 使用者的显示名称	是
ApplicationKey	用于身份验证的 API 密钥	是
Active	是否允许该使用者进行身份验证	是
AllowedScopes	作用域列表（例如，["polarion:read"]）	是
Description	使用者的可选说明	否

可用作用域：

• polarion:read - 对所有 REST API 端点的读取权限

用法：

curl -H "X-API-Key: your-api-key" http://localhost:8080/polarion/rest/v1/projects/{projectId}/spaces

**注意：**健康检查（/api/health、/api/version）和 API 文档（/scalar/v1）无需身份验证。MCP 端点也无需身份验证，但仅限 McpAuth:Enabled 为 false 时（默认值）——请参阅下一节。

可选：MCP 身份验证与按调用者进行访问控制

PolarionRemoteMcpServer 支持 MCP 端点的两项独立功能，默认均处于关闭状态：

• OAuth 2.1 身份验证（McpAuth:Enabled）——在允许执行 tools/call 前，要求提供来自外部授权服务器的 bearer 令牌。每个已提供服务的项目别名都会在 /.well-known/oauth-protected-resource/{alias}/mcp 发布自己的 RFC 9728 受保护资源元数据，以便符合规范的 MCP 客户端自动发现身份验证方式。
• 按调用者进行 RBAC（Rbac:Enabled）——此外，还会根据调用用户自身的 Polarion 项目成员身份，对每个 tools/call 进行授权，而不是让所有已通过身份验证的调用者共享相同的访问权限。需要设置 McpAuth:Enabled=true。

两项功能的默认值均为 false；除非进行配置，否则服务器行为与先前版本保持不变。有关设置、配置参考表和启动验证错误，请参阅 docs/authentication.md 和 docs/rbac.md。

第三项默认关闭的功能是 SQL 查询工具：

键	默认值	作用
SqlQueryTool:Enabled	false	设为 true 时，会在两个服务器上注册 search_workitems_sql 工具。该工具的查询范围限定在所属项目内（请参阅 docs/rbac.md），因此无需为每个工具单独配置 RBAC 规则；但它会通过繁重的联接查询泄露其他项目中是否存在数据这一是非信息——如果无法接受这种残余风险，请保持禁用。

配置 MCP 客户端

配置 Cline：

1. 打开 Cline 的 MCP 设置界面
2. 点击“Remote Servers”选项卡
3. 对于用户想要连接的 appsettings.json 中的每个 ProjectUrlAlias：

{
  "mcpServers": {
    ...
    ...

    "Polarion Starlight": {
      "autoApprove": [],
      "disabled": true,
      "timeout": 60,
      "url": "http://{{your-server-ip}}:8080/starlight/mcp",
      "transportType": "streamableHttp"
    },
    "Polarion Octopus": {
      "autoApprove": [],
      "disabled": true,
      "timeout": 60,
      "url": "http://{{your-server-ip}}:8080/octopus/mcp",
    "transportType": "streamableHttp"
    }
  ...
  ...
}

1. 对要连接的每个 ProjectUrlAlias 重复上述步骤。

配置 Visual Studio Code：

将以下配置添加到 settings.json 文件中：

"servers": {
    "polarion-starlight": { // Use a descriptive key
        "type": "http",
        "url": "http://{{your-server-ip}}:8080/starlight/mcp", // Replace with your alias
        "env": {}
    },
    "polarion-octopus": { 
        "type": "http",
        "url": "http://{{your-server-ip}}:8080/octopus/mcp", // Replace with your alias
        "env": {}
    }
    // Add entries for each ProjectUrlAlias
}

或通过命令行执行：

claude mcp add --transport http polarion-starlight http://{{your-server-ip}}:8080/starlight/mcp

配置 Claude Desktop：

Claude Desktop 尚不原生支持可流式传输的 HTTP，但你可以通过在 claude_desktop_config.json 文件中添加以下内容来使用代理：

{
  "mcpServers": {
    "polarion-remote": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "http://{{your-server-ip}}:8080/{ProjectUrlAlias}/mcp" // Replace {ProjectUrlAlias}
      ]
    }
    // Add entries for each ProjectUrlAlias, potentially using different keys like "polarion-starlight"
  }
}

在本地运行（stdio）

用于本地开发或工作站时，你可以运行基于 stdio 的 MCP 服务：

1. 从 releases 页面下载适用于你平台的可执行文件
2. 将 MCP 客户端配置为使用 stdio 传输，并指定可执行文件的路径

故障排除

POST /{alias}/mcp 返回 401，且客户端始终不提示登录 — 请确认客户端实现了 MCP 的 OAuth 发现流程（RFC 9728）。自行获取 /.well-known/oauth-protected-resource/{alias}/mcp；如果返回 404，则运行中的服务实际上并未将 McpAuth:Enabled 设为 true。请参阅 docs/authentication.md。

POST /{alias}/mcp 返回 403 — 调用方已通过身份验证，但缺少所需的 scope，或者其 OAuth 客户端 ID 不在 McpAuth:AllowedClientIds 中。请参阅 401 vs 403。

服务因 McpAuth 或 Rbac 验证错误而拒绝启动 — 每条消息都会指出需要修正的确切键；请参阅 docs/authentication.md 和 docs/rbac.md 中的验证错误表。

RBAC 拒绝所有 MCP 工具调用 — RBAC 的设计是默认拒绝。设置 Rbac:AuditOnly=true，并查看访问审计记录中的 DecisionReason 字段；请参阅 docs/rbac.md#troubleshooting。

贡献

希望参与贡献或从源代码构建的开发者，请参阅 CONTRIBUTING.md。

许可证

详情请参阅 LICENSE。