极地麦普

Name: 极地麦普
Author: mmerah

作者：mmerah2 星标更新：2025-10-21

安装使用来源：spider==github.com

项目介绍

Polarion MCP Server

一个基于模型上下文协议（MCP）的服务器，提供Polarion ALM与AI助手如Microsoft Copilot Studio和Cline之间的无缝集成。该服务器使用FastMCP 2.10.6构建，使AI代理能够与Polarion项目、工作项、测试运行、文档等进行交互。

功能

完整的MCP协议支持：实现工具、资源和提示
兼容Microsoft Copilot Studio：包含JSON-RPC ID类型兼容性的中间件
13个强大的工具：全面访问Polarion数据，包括计划支持
计划项目支持：专门针对围绕计划组织的项目（发布/迭代）
安全认证：基于令牌的身份验证与Polarion
生产就绪：强大的错误处理和日志记录
现代Python：使用pyproject.toml并遵循最佳实践
GPT操作：提供REST包装器、OpenAPI规范和GPT操作清单

先决条件

Python 3.10+
Git
访问Polarion实例：
- Polarion URL
- 用户名
- 个人访问令牌
Microsoft Copilot Studio账户（用于AI代理集成）

安装

克隆仓库

git clone https://github.com/mmerah/PolarionMcp.git
cd PolarionM

配置Polarion凭证

在项目根目录创建.env文件：

cp .env.example .env

使用您的凭证编辑.env：

POLARION_URL=https://your-polarion-instance.com/polarion
POLARION_USER=your-username
POLARION_TOKEN=your-personal-access-token

运行服务器

使用方便脚本（推荐）：

chmod +x run_server.sh
./run_server.sh

或手动：

python -m venv .venv
source .venv/bin/activate  # 在Windows上：.venv\Scripts\activate
pip install -e .
python -m mcp_server.main

服务器在http://0.0.0.0:8000启动，MCP端点位于/mcp/

GPT操作集成

服务器现在通过HTTP包装器暴露每个MCP工具，因此您可以将其连接到自定义GPT，通过GPT操作。

通过HTTPS公开服务器：对于自定义GPT，服务器必须可以通过OpenAI访问，例如通过Azure Dev Tunnel或其他反向代理。
提供OpenAPI规范URL：告知GPT操作使用https://<your-domain>/openapi.json。
可用端点：所有操作都在/actions/...下，并返回JSON信封。OpenAPI规范（openapi.yaml / openapi.json）描述了每条路由，并镜像现有的MCP工具。
代理指令：详细的使用指南位于agent_instructions.md（完整版）和agent_instructions_simple.md（快速参考）。在工具更改后使用python -m mcp_server.docgen重新生成。

您可以在本地验证设置：

curl http://localhost:8000/openapi.json | jq '.paths | keys'
curl http://localhost:8000/actions/projects

配置系统

服务器支持可选配置文件，提供：

项目别名：使用友好名称而不是晦涩的项目ID
计划项目标记：识别使用计划的项目（发布/迭代）
预定义的工作项类型：消除重复发现调用
自定义字段映射：定义项目特定字段
命名查询：创建可重用的项目特定搜索

XML自定义字段解析器

要快速从Polarion XML导出配置自定义字段，请参阅XML_PARSER.md。

设置配置

复制示例配置：

cp polarion_config.example.yaml polarion_config.yaml

编辑polarion_config.yaml以定义您的项目：

projects:
  # 普通项目
  webstore:  # 您的别名
    id: WEBSTORE_V3  # 实际Polarion ID
    work_item_types:
      - systemRequirement
      - specification
      - defect
    default_queries:
      open_bugs: "type:defect AND status:open"
      my_items: "assignee.id:$current_user"
  
  # 基于计划的项目（用于发布/迭代）
  releases:
    id: RELEASES_PROJECT
    is_plan: true  # 标记为计划项目
    work_item_types:
      - feature
      - userStory
      - task

在所有工具调用中使用别名：

# 而不是：get_project_info("WEBSTORE_V3")
# 使用：get_project_info("webstore")

# 命名查询自动工作：
search_workitems("webstore", "query:open_bugs")

可用工具

配置工具

list_projects：显示所有配置的项目别名（指示哪些是计划项目）
get_project_types：获取项目的配置工作项类型
get_named_queries：列出项目的可用命名查询

AI代理工具使用约定

错误格式：以"❌"开头的字符串表示错误
成功格式：人类可读的字符串，列表截断（最多20-50项）
输入：project_alias接受别名（例如，webstore）和实际ID（例如，MYPROJ）；document_id是Space/DocumentID（例如，QA/TestSpecs）
计划项目：某些工具仅适用于计划项目，其他工具仅适用于普通项目

1. `health_check`

检查与Polarion服务器的连接。

返回：连接状态消息

2. `get_project_info`

检索Polarion项目的相关信息。

参数：
- project_alias：项目别名或ID（例如，“webstore”或“MYPROJ”）
返回：项目名称和描述

3. `get_workitem` (仅限普通项目)

获取特定工作项的详细信息。

参数：
- project_alias：项目别名或ID（例如，“webstore”或“MYPROJ”）
- workitem_id：工作项ID（例如，“PROJ-123”）
返回：工作项详情，包括标题、类型、状态、作者、日期
注意：不支持计划项目 - 使用get_plan_workitems代替

4. `search_workitems` (仅限普通项目)

使用Lucene查询语法或命名查询搜索工作项。

参数：
- project_alias：项目别名或ID（例如，“webstore”或“MYPROJ”）
- query：Lucene查询或命名查询（例如，“query:open_bugs”）
- field_list：可选逗号分隔的返回字段列表
返回：匹配的工作项列表
注意：不支持计划项目 - 使用get_plan_workitems代替

查询语法：使用Apache Lucene查询语法和Polarion特定字段。有关全面的查询语法文档，请参阅官方Siemens Polarion文档和Apache Lucene查询解析器语法。

5. `get_test_runs`

检索项目中的所有测试运行。

参数：
- project_alias：项目别名或ID（例如，“webstore”或“MYPROJ”）
返回：测试运行列表，包括ID、标题和状态

6. `get_test_run`

获取特定测试运行的详细信息。

参数：
- project_alias：项目别名或ID（例如，“webstore”或“MYPROJ”）
- test_run_id：测试运行ID
返回：测试运行详情，包括状态、日期和测试案例数量

7. `get_documents`

列出项目中的所有文档。

参数：
- project_alias：项目别名或ID（例如，“webstore”或“MYPROJ”）
返回：文档列表，包括ID、标题和位置

8. `get_test_specs_from_document`

从文档中提取测试规范ID。

参数：
- project_alias：项目别名或ID（例如，“webstore”或“MYPROJ”）
- document_id：文档ID（格式：Space/DocumentID）
返回：在文档中找到的测试规范ID列表

9. `discover_work_item_types`

发现项目中的可用工作项类型。

参数：
- project_alias：项目别名或ID（例如，“webstore”或“MYPROJ”）
- limit：要采样的最大工作项数（默认：1000）
返回：工作项类型列表及其出现次数

计划特定工具

这些工具仅适用于配置为is_plan: true的项目：

10. `get_plans`

列出计划项目中的所有计划（发布、迭代）。

参数：
- project_alias：项目别名或ID（必须是计划项目）
返回：计划列表，包括ID、名称和模板类型

11. `get_plan`

获取特定计划的详细信息。

参数：
- project_alias：项目别名或ID（必须是计划项目）
- plan_id：计划ID（例如，“R2024.4”或“Sprint23”）
返回：计划详情，包括名称、日期、模板和允许的类型

12. `get_plan_workitems`

获取特定计划中的所有工作项。

参数：
- project_alias：项目别名或ID（必须是计划项目）
- plan_id：计划ID
返回：计划中的工作项列表

13. `search_plans`

使用Lucene查询语法搜索计划。

参数：
- project_alias：项目别名或ID（必须是计划项目）
- query：Lucene查询（例如，“templateId:release”，“parent.id:R2024”）
返回：匹配的计划列表

MCP资源

polarion://project/{project_id}：作为资源访问项目信息

MCP提示

analyze_project：为项目生成分析提示
workitem_analysis：为特定工作项生成分析提示

Microsoft Copilot Studio集成

公共URL配置

为了让服务器被Microsoft Copilot Studio访问，您需要一个公共URL：

开发：使用VSCode端口转发，具有公共可见性
生产：部署到Azure等云服务

服务器端点将在：https://your-public-url/mcp/

集成步骤

确保服务器正在运行 服务器必须在上述公共URL上可访问。
OpenAPI规范 openapi.copilot.yaml文件已预先配置：
- 正确的主机URL
- MCP协议规范：x-ms-agentic-protocol: mcp-streamable-1.0
- 正确的端点配置
添加到Copilot Studio 有关将MCP服务器添加到Microsoft Copilot Studio的详细说明，请参阅官方Microsoft文档： https://github.com/microsoft/mcsmcp/blob/main/README.md
测试您的集成 Copilot Studio示例提示：
- “检查Polarion连接的健康状况”
- “获取MyProject项目的相关信息”
- “搜索WebApp项目中的开放缺陷”
- “显示QA项目中的测试运行”
- “查找Development项目中分配给john.doe的所有需求”

与Cline一起使用

此服务器也可以与Cline（VSCode扩展）一起使用，通过运行SSE传输模式：

运行Cline兼容服务器
```
./run_server_cline.sh
```
这将在http://localhost:8000/mcp上启动服务器，使用SSE传输。
配置Cline
- 打开安装有Cline扩展的VSCode
- 点击Cline图标 → 菜单（⋮）→ MCP服务器
- 转到“远程服务器”标签
- 添加服务器：
  - 名称：polarion
  - URL：http://localhost:8000/mcp
或编辑cline_mcp_settings.json：
```
{
    "mcpServers": {
        "polarion": {
            "url": "http://localhost:8000/mcp",
            "disabled": false,
            "autoApprove": ["health_check", "get_project_info"]
        }
    }
}
```
与Cline一起使用
- 请求Cline与Polarion互动：
  - “检查我的Polarion连接”
  - “搜索XYZ项目中的开放bug”
  - “从Polarion获取测试运行结果”
  - “显示ABC项目中的所有需求”

项目结构

PolarionMcp/
├── mcp_server/          # MCP服务器实现
│   ├── __init__.py
│   ├── main.py         # 服务器入口点
│   ├── tools.py        # MCP工具定义
│   ├── middleware.py   # Copilot Studio兼容层
│   ├── config.py       # 项目别名和查询配置
│   ├── helpers.py      # 格式化工具输出的辅助函数
│   └── settings.py     # 加载环境和配置
├── lib/                 # 核心库
│   └── polarion/
│       └── polarion_driver.py  # Polarion API封装
├── polarion_config.example.yaml  # 配置模板
├── openapi.yaml        # 包含HTTP动作的OpenAPI规范（GPT操作）
├── openapi.copilot.yaml # 为Copilot Studio的OpenAPI规范
├── run_server.sh       # 方便启动脚本
├── pyproject.toml      # Python包配置
├── .env.example        # 环境变量模板
├── WORKFLOW_EXAMPLES.md # 使用模式和示例。自定义并用作您的AI代理的系统指令。
└── README.md           # 本文档

开发

运行测试

pytest

代码格式化

black mcp_server lib
isort mcp_server lib

类型检查

mypy mcp_server lib

故障排除

连接问题

验证您的Polarion URL是否正确且可访问（请注意使用/mcp/而非/mcp）
确保您的个人访问令牌具有足够的权限
检查.env文件是否正确配置

Copilot Studio集成

确认您的公共URL可访问
验证服务器是否在8000端口上运行
检查服务器日志是否有任何中间件相关错误
查看官方Microsoft MCP文档：https://github.com/microsoft/mcsmcp

常见错误

“无效凭据”：检查您的用户名和令牌
“项目未找到”：验证项目ID是否存在于Polarion中
“工作项未找到”：确保工作项ID包含项目前缀

许可

本项目根据MIT许可发布。详情请参阅LICENSE文件。

贡献

欢迎贡献！请随时提交Pull Request。