Helix Alm MCP Server

Helix ALM MCP服务器

通过模型上下文协议将AI助手连接到Helix ALM进行需求管理。

概述

这 模型上下文协议（MCP） 是一个开放标准，允许AI助手与外部工具和数据源进行交互。此服务器实现了MCP Helix ALM （Perforce ALM），使Claude和其他兼容MCP的助手能够直接从对话中创建、阅读、更新和搜索需求和需求文档。

您可以通过自然语言管理需求，而Helix ALM仍然是记录系统，而不是在AI助手和Helix ALM UI之间切换。

注： 这是一个集中在以下方面的概念验证 需求模块。它故意省略了破坏性操作（没有删除），并且尚未涵盖问题或测试用例。看 已知限制 了解详情。

你能做什么

搜索和浏览要求：

*“显示已批准的高优先级要求”* 克劳德打电话来 search_requirements 与查询 Priority = 'High' AND Status = 'Approved' 并返回一个分页列表。

根据PRD的要求创建文档：

*“创建一个名为“登录重新设计”的PRD，并为身份验证流程添加三个用户故事”* 克劳德打电话来 create_requirement_document那么 create_requirement 三次，然后 add_requirements_to_document 将它们联系在一起。

通过标签查找需求：

*“US-2195的细节是什么？”* 克劳德打电话来 get_requirement 和 tag="US-2195" 并返回包含所有字段的完整需求。

先决条件

• Python 3.10 或更高版本
• Helix ALM服务器 启用REST API时（默认为端口8443）
• API密钥凭据 （推荐）或Helix ALM服务器的用户名/密码
• 版本控制系统 （克隆存储库）

快速开始

1.克隆存储库

git clone https://github.com/romep/helix-alm-mcp-server.git
cd helix-alm-mcp-server

2.创建虚拟环境并安装

python3 -m venv venv
source venv/bin/activate
pip install -e .

3.配置凭据

cp .env.example .env

编辑 .env 使用您的Helix ALM连接详细信息：

• HELIX_ALM_API_URL -您的服务器的REST API URL（例如。， https://your-server:8443/helix-alm/api/v0)
• HELIX_ALM_PROJECT --具有UUID的项目名称（在Helix ALM管理设置中找到）
• HELIX_ALM_API_KEY 和 HELIX_ALM_API_SECRET -API密钥凭据（推荐），或使用 HELIX_ALM_USERNAME / HELIX_ALM_PASSWORD 用于基本身份验证

看 配置参考 所有可用选项。

4.测试连接

python test_connection.py

此脚本与您的Helix ALM服务器进行身份验证，列出一些需求，获取需求类型，并列出文档。如果一切配置正确，您将看到 ALL TESTS PASSED.

5.配置您的MCP客户端

有关Claude Desktop、Claude Code或其他客户端的设置说明，请参阅下一节。

MCP客户端配置

克劳德桌面

添加到您的Claude Desktop配置文件中：

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• 视窗: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "helix-alm": {
      "command": "/path/to/helix-alm-mcp-server/venv/bin/python",
      "args": ["-m", "helix_alm_mcp.server"],
      "cwd": "/path/to/helix-alm-mcp-server"
    }
  }
}

替换 /path/to/helix-alm-mcp-server 使用克隆存储库的实际路径。 重新启动克劳德桌面 更改配置后。

克劳德代码（VS代码扩展或CLI）

复制提供的示例并更新路径：

cp .mcp.json.example .mcp.json
# Edit .mcp.json and replace /path/to/your/HelixALM_MCP_Server with your actual path

Claude Code自动检测 .mcp.json 在项目根中。

其他MCP客户端

任何支持MCP stdio传输的客户端都可以使用此服务器。把它指向 helix-alm-mcp 入口点或跑道 python -m helix_alm_mcp.server 从项目目录中。

可用工具

需求

需求文件

Item Identifiers

Helix ALM项目有三种类型的标识符。引用特定项目的工具接受以下任何一项：

每次呼叫只提供一个标识符。服务器自动将标签和数字解析为内部ID。

搜索语法

使用 search 参数（on list_requirements, list_requirement_documents)或 query 参数（on search_requirements)使用Helix ALM查询语法过滤结果。

示例：

Summary CONTAINS 'login'
Status = 'Approved'
Priority = 'High' AND Status != 'Closed'

操作员：

逻辑运算符： AND, OR, NOT 不区分大小写

建筑

MCP Client (Claude)    MCP Server (server.py)    Helix ALM REST API
                                          |
                                     client.py (API client)
                                     config.py (settings)

• server.py --注册10个MCP工具并处理工具调度。使用 MCP Python SDK 使用stdio传输与所有MCP客户端兼容。
• client.py -包装Helix ALM REST API。处理身份验证（API密钥或基本身份验证到承载令牌交换）、带指数退避的速率限制重试和标识符解析（标记/编号到内部ID）。
• config.py --通过Pydantic settings从环境变量加载设置。包含字段ID、类型映射和分页默认值的命名常量。

配置参考

\*提供 要么 API密钥+密钥（推荐） 或 用户名+密码。

故障排除

“SSL证书验证失败” 预期使用自签名证书，这在Helix ALM部署中很常见。在此概念验证中，默认情况下禁用SSL验证。确保您的 HELIX_ALM_API_URL 是正确的。

“错误：HELIX_ALM_PROJECT未配置” 这 .env 文件丢失或 HELIX_ALM_PROJECT 变量为空。跑 cp .env.example .env 并填写你的价值观。

“错误：未配置身份验证” 中既没有设置API密钥也没有设置基本身份验证凭据 .env.提供其中之一 HELIX_ALM_API_KEY + HELIX_ALM_API_SECRET 或 HELIX_ALM_USERNAME + HELIX_ALM_PASSWORD.

速率限制（HTTP 429） 服务器会自动以指数回退方式重试（默认情况下最多5次尝试）。如果您遇到持续的429错误，您的Helix ALM服务器可能有严格的速率限制——请与您的服务器管理员联系。

工具未出现在Claude中 对于Claude Desktop，更改配置后重新启动应用程序。对于Claude Code，请确保 .mcp.json 位于项目根目录中，Python可执行文件路径正确。

连接测试通过，但Claude无法使用工具 验证 cwd MCP客户端配置中的路径与项目目录匹配，以便 .env 在运行时找到该文件。

令牌端点上的404或“无可用项目” 如果您正在使用Perforce试用服务器(tryhelixalm.perforce.com)，服务器会定期重置-项目和API密钥会被擦除。您需要重新注册新的试用实例并更新您的 .env 使用新的项目名称、UUID和凭据。要验证，请访问Swagger UI https://tryhelixalm.perforce.com:8443/ 并检查您的项目是否出现在项目选择器中。

发展

项目结构

helix-alm-mcp-server/
├── src/helix_alm_mcp/
│   ├── server.py           # MCP tool definitions and dispatch
│   ├── client.py           # Helix ALM REST API client
│   ├── config.py           # Settings and named constants
│   └── models.py           # Pydantic type hints
├── tests/
│   ├── unit/               # Deterministic resolver tests
│   ├── integration/        # Live API tests
│   ├── fixtures/           # Known test data
│   └── conftest.py         # Shared fixtures
├── promptfooconfig.yaml    # Direct MCP eval tests
├── promptfoo-llm.yaml      # LLM eval tests
├── test_connection.py      # Quick connectivity check
├── .env.example            # Configuration template
└── .mcp.json.example       # MCP client config template

运行测试

source venv/bin/activate

# All tests (58 total: 18 unit + 40 integration)
pytest tests/ -v

# Unit tests only (fast, no API calls)
pytest tests/unit/ -v

# Integration tests only (requires valid .env credentials, hits real API)
pytest tests/integration/ -v

集成测试包括API调用之间的内置延迟，以避免速率限制。

使用Promptfoo进行评估测试

该项目使用 Promptfoo 的 用于从两个层面评估MCP工具行为：

直接MCP测试 (promptfooconfig.yaml)--10个直接调用MCP工具并对响应进行断言的测试。无需LLM，完全确定性，零成本。

promptfoo eval

LLM工具选择测试 (promptfoo-llm.yaml)--16个测试，为LLM提供自然语言提示，并验证它选择了具有正确参数的正确工具。涵盖了工具发现、参数提取、分页跟踪和抗幻觉（验证LLM没有声称服务器没有的功能）。

promptfoo eval -c promptfoo-llm.yaml

某些断言使用 llm-rubric --LLM的语义评估——用于字符串匹配无法区分细微差别的情况（例如，“你可以删除”与“不支持删除”）。所有LLM eval测试都通过以下方式在本地托管的模型上运行 奥拉玛 （qwen2.5:32b），将成本保持在零。

# View results in the Promptfoo dashboard
promptfoo view

已知限制

这是一个具有故意限制的概念证明：

• 仅限需求模块 --问题和测试用例尚未得到支持
• 无删除操作 --防止意外数据丢失的故意安全决策
• 更新仅限于摘要和描述 --其他字段必须在Helix ALM UI中编辑
• 文档结构平坦 --需求仅添加到顶层（没有层次结构）
• SSL验证已禁用 --可用于PoC和内部部署，应可配置用于生产

看 BACKLOG.md 查看13个记录在案的限制的完整列表，包括变通方法和计划中的增强功能。

路线图

• 安全强化——SSL验证选项、查询注入逃逸、错误消息净化
• 问题模块——列出、获取、创建、更新和搜索问题
• 测试用例模块——列出、获取、管理测试运行

贡献

欢迎投稿！拜托：

1. 在提交PR之前，打开一个问题来讨论您提出的更改
2. 分叉仓库并创建功能分支
3. 跑 pytest tests/ -v 验证所有测试是否通过
4. 遵循中的现有代码模式 server.py 和 client.py

许可证

MIT许可证——见 许可证 了解详情。

致谢

• Perforce 用于Helix ALM和REST API
• Anthropic 对于模型上下文协议
• 与 MCP Python SDK