bmc-helix-mcp

BMC Helix MCP 服务

BMC Helix MCP Server 是一个用于 SRE 运维的 Model Context Protocol（MCP）服务，通过 BMC Helix ITSM REST API 实现。它使用 TypeScript 编写，由 Express 提供支持，并可选配置 HTTPS/TLS。

有关版本发布和更新详情，请参阅更新日志。

项目特性

• Model Context Protocol（MCP）支持： 基于 @modelcontextprotocol/sdk 构建，可与大模型和编码助手无缝集成。
• 表单和 CI 操作： 封装原生 BMC Helix ITSM REST API 调用，用于获取和分页查询表数据、按 ID 或名称查询 CMDB CI、查询任务和关联项，以及检查关系。
• Express + HTTPS： 同时支持标准 HTTP 和安全 HTTPS，并可完整配置 TLS 证书验证。
• Node v24 和现代 ES 模块结构。

---

目录结构

• src/mcp-server.ts：完全类型化并进行速率限制的 MCP 服务应用，包含 Express 传输和工具映射。
• certs/：存放用于启用安全 TLS 的本地客户端和服务端 CA 密钥、配置及脚本。
• tests/：使用模拟 Helix 服务进行集成测试，以验证服务端点、授权和工具架构。

---

已注册的 MCP 工具

此服务注册了以下高价值工具：

1. helix_get_table_data：从任意 BMC Helix 表单（例如 HPD:IncidentInterface、CHG:Infrastructure Change）检索记录，并可选择查询筛选条件和记录数量限制。
2. helix_get_table_data_paginated：使用基于偏移量的分页，自动从表单获取并汇总多页记录。
3. helix_get_ci_by_id：通过唯一条目 Request ID，从 BMC.CORE:BMC_BaseElement 获取配置项的属性。
4. helix_get_ci_by_name：按名称查找 CMDB 记录。
5. helix_get_change_request_tasks：检索给定 Change ID（CRQ...）在 TMS:Task 中的子任务列表。
6. helix_get_problem_investigation_id：查找给定事件工单所关联的问题 ID。
7. helix_get_change_configuration_items：查找与 Change ID 关联的 AST 配置项。

---

安装与设置

1. 将 .env.example 复制为 .env，并填写相关信息：

cp .env.example .env

1. .env 中的配置项：

• HELIX_API_URL：BMC Helix Entry 级别的 URL 端点。
• HELIX_TOKEN_URL：JWT 登录载荷的 URL 端点。
• HELIX_USERID / HELIX_PASSWORD：Helix API 凭据。
• MCP_PORT：Web 服务运行端口（默认为 3000）。
• MCP_AUTH_TOKEN：可选的 API 授权 Bearer 令牌，用于保护 MCP 端点，防止外部实体访问。
• MCP_TLS_ENABLED：设为 true，即可在 Express 监听器上启用 TLS。

1. 从 BMC Helix 获取 TLS 证书：

如果你的 BMC Helix 实例使用自签名、内部或自定义 CA 证书，可以使用辅助脚本自动获取证书链：

./certs/helix-certs.sh https://your-helix-instance.onbmc.com

此脚本会通过 openssl 获取网站的证书链，并将其保存到 certs/helix-certs.pem。然后在 .env 配置中引用该文件：

HELIX_CERT_PATH=./certs/helix-certs.pem

1. 安装依赖：

npm install

1. 构建应用：

npm run build

1. 启动服务（开发 / 生产）：

• 生产模式： npm run start
• 开发模式： npm run dev

---

测试

本项目包含一个使用 Node 原生测试运行器（通过 --test）实现的集成测试套件。它在模拟的 BMC Helix 服务环境中运行，以验证：

• 服务初始化和健康状态检查。
• API 身份验证和安全授权过滤器（例如，验证 MCP_AUTH_TOKEN 的行为）。
• 工具定义和结构化查询能力。
• 工具检索的精确端到端流程执行（helix_get_table_data、helix_get_table_data_paginated、CI 查询，以及 Change/Problem 关系）。

运行测试套件：

npm test

此命令会将 TypeScript 代码库编译到生产输出目录，启动集成的模拟服务，将 MCP 服务作为独立子进程启动，并执行所有验证断言。

---

贡献

欢迎为本项目做出贡献！为确保符合 Developer Certificate of Origin（DCO），请务必为提交添加签署声明。

Developer Certificate of Origin 1.1

DCO 是一套轻量级法律框架，确保贡献者有权依据项目的开源许可证提交代码。为提交添加签署声明，即表示你证明自己有权贡献该代码，并且该代码符合项目的许可条款。

DCO

如何添加签署声明

为确认你同意 DCO，请在每条提交消息中添加一行 Signed-off-by。你可以使用 -s 或 --signoff 标志为提交添加签署声明，从而自动完成此操作：

git commit -s -m "Your commit message"

这会在提交消息中附加类似以下内容的一行：

Signed-off-by: Jane Doe <[email protected]>

---

更新日志

变更历史请参见 CHANGELOG.md。

许可证

本项目采用 MIT License 许可。