HaloPSA MCP服务器

HaloPSA MCP服务器

MCP服务器 Halopsa --通过SQL或REST API查询票证、代理、客户端和报告数据。对工单、操作和时间表的完全读/写支持。

免责声明： 这是一个独立的开源项目。它不隶属于HaloPSA或NinjaOne，也不受其认可或支持。

看 更改日志.md 发布历史。Docker镜像作为semver标签发布在 Docker 中心 (redanthrax/halopsa-mcp:<version> --没有 latest 标签）。

特性

• 使用PKCE进行OAuth 2.1身份验证
• 双模：stdio（桌面MCP主机）+流式HTTP（远程MCP客户端/生产）
• Stdio模式包括一个后台OAuth服务器——无需重新启动即可进行身份验证
• 用于高效计数、聚合和基于日期的过滤的SQL查询工具
• 带有状态ID、代理ID和查询示例的实时架构
• 自动令牌刷新
• 调整响应以最大限度地减少上下文使用
• 完整的票证生命周期：创建、读取、更新、添加操作
• 时间表管理：日期记录、时间条目、提交/批准工作流

HaloPSA设置

在配置MCP服务器之前，在HaloPSA中创建一个API应用程序。

推荐：授权代码（本地应用程序）

这是推荐的设置——使用OAuth 2.1授权码+PKCS，没有客户端密钥。

1. 首选 配置→ 集成→ 卤代PSA API→ 应用程序→ New
2. 集 认证方式 到 授权码（本地应用程序）
3. 集 登录重定向URL 到 http://localhost:3000/callback （添加用于生产的其他URL，例如。 https://your-domain.com/callback)
4. 启用 允许代理登录
5. 离开 客户端密钥 空白
6. 保存并复制 客户端ID

备选方案：客户端ID和密码（服务）

如果您的HaloPSA实例需要机密客户端，或者您需要在没有用户登录的情况下进行机器对机器访问，请使用此选项。

1. 首选 配置→ 集成→ 卤代PSA API→ 应用程序→ New
2. 集 认证方式 到 客户端ID和密码（服务）
3. 集 登录重定向URL 到 http://localhost:3000/callback
4. 启用 允许代理登录
5. 保存并复制 客户端ID 和 客户端密钥
6. 添加 HALOPSA_CLIENT_SECRET=your-secret 到你的 .env 文件

注： 不要使用 隐式流（单页应用程序） --它在OAuth 2.1中已被弃用，其安全性不如授权码+PKCE。

部署模式

对所有三个使用相同的图像/二进制文件；只有环境变量和周围的基础设施会发生变化。

1.本地开发（桌面标准）

1. 创建 .env （复印件 .env.example):

   复制

   HALOPSA_URL=https://your-tenant.halopsa.com
   HALOPSA_CLIENT_ID=your-client-id
   HALOPSA_TOKEN_STORE=./data/tokens.json
   HALOPSA_DPKEY_DIR=./data/dp-keys
   AUTH_BASE_URL=http://localhost:3000
   LOG_FORMAT=text
   

2. 构建：

   复制

   dotnet build
   

3. 配置MCP主机的stdio条目（示例配置形状）：

   主人的 env 挡块未通过 wsl.exe.将env变量放入 .env.

   WSL（推荐）：

   复制

   {
     "mcpServers": {
       "halopsa": {
         "command": "wsl.exe",
         "args": [
           "--distribution", "Ubuntu",
           "bash", "-c",
           "cd /path/to/halopsa-mcp && exec ./bin/Debug/net10.0/HaloPsaMcp"
         ]
       }
     }
   }
   

   本机Windows：

   复制

   {
     "mcpServers": {
       "halopsa": {
         "command": "dotnet",
         "args": ["run", "--project", "C:\\path\\to\\halopsa-mcp"]
       }
     }
   }
   

4. 重新启动MCP主机。

5. 首次连接时，如果您未登录，MCP服务器 在浏览器中打开登录页面 并发送 服务器指令 到主机提示登录。完成HaloPSA登录，然后在主机中重试——不需要重新启动。集 HALOPSA_AUTO_OPEN_LOGIN=0 禁用自动打开。

2.Docker（自托管HTTP）

已发货 docker-compose.yml 使用强化默认值运行映像：非根UID 1001， read_only: true, cap_drop: ALL, no-new-privileges，tmpfs /tmp，和一个单一 ./data 绑定令牌+数据保护密钥的挂载。

cp .env.example .env   # fill in HALOPSA_URL + HALOPSA_CLIENT_ID
docker compose up -d

对于没有作曲的单次跑步：

docker run -d \
  --name halopsa-mcp \
  --user 1001:1001 \
  --read-only --tmpfs /tmp \
  --cap-drop ALL --security-opt no-new-privileges:true \
  -p 3000:3000 \
  -v ./data:/app/data \
  -e HALOPSA_URL=https://your-tenant.halopsa.com \
  -e HALOPSA_CLIENT_ID=your-client-id \
  -e AUTH_BASE_URL=https://your-domain.com \
  -e HALOPSA_DPKEY_DIR=/app/data/dp-keys \
  redanthrax/halopsa-mcp:1.0.23

从以下位置固定到特定的semver标签 GitHub 发布 或使用 image.digest 在Kubernetes中。

如果你将其暴露给公共互联网，请使用TLS终止的反向代理（Caddy、Traefik、nginx）。对于Claude.ai组织连接器，请离开 MCP_DCR_INITIAL_ACCESS_TOKEN 未设置（或已设置 MCP_ALLOW_OPEN_DCR=1)并配置 MCP_CORS_ALLOWED_ORIGINS --看 helm/halopsa-mcp/values-claude-connector.example.yaml.

3.AKS/Kubernetes（Helm）

Helm图表位于 helm/halopsa-mcp/ 附带强化默认设置：只读根文件系统， seccompProfile: RuntimeDefault，没有自动挂载的SA令牌， 默认情况下启用网络策略，播客中断预算，以及为 dcrInitialAccessToken /客户端机密/Redis连接。

helm upgrade --install halopsa-mcp helm/halopsa-mcp/ \
  --namespace halopsa-mcp --create-namespace \
  --set halopsa.url=https://your-tenant.halopsa.com \
  --set halopsa.clientId=your-client-id \
  --set halopsa.authBaseUrl=https://halopsa-mcp.example.com \
  --set halopsa.publicBaseUrl=https://halopsa-mcp.example.com \
  --set ingress.enabled=true \
  --set ingress.hosts[0].host=halopsa-mcp.example.com \
  --set networkPolicy.enabled=true \
  --set dcrInitialAccessToken=$(openssl rand -hex 32)

对于机密客户端（客户端ID+机密方法），在不提交机密的情况下提供机密：

--set-file halopsa.clientSecret=./halopsa-client-secret.txt

对于多个副本（HA），请使用共享的Redis会话存储：

--set replicaCount=3 \
--set halopsa.tokenStore.backend=redis \
--set halopsa.redisConnection='redis-master:6379,password=...,ssl=true'

生产检查表：

• []TLS被入口终止（证书管理器或Azure应用程序网关）
• [ ] networkPolicy.enabled=true （如果不使用ingress nginx，请调整ingress命名空间）
• [ ] AUTH_BASE_URL / halopsa.authBaseUrl 匹配公共连接器URL
• []HaloPSA登录重定向URL包括 https://<host>/callback
• []公共发现终结点返回 200: /.well-known/oauth-* 和 /.well-known/mcp/schema
• []克劳德连接器：打开DCR+CORS+重定向允许列表(values-claude-connector.example.yaml)
• [ ] image.digest 着手 sha256:... （首选）或 image.tag 固定在SemVer上——不是 latest
• []从您的私有ACR（Docker Hub的镜像）中提取的映像
• []Azure密钥库支持的数据保护密钥（请参阅限制）
• [ ] halopsa.publicBaseUrl 设置为外部可访问的URL（例如。， https://your-domain.com)

Helm值参考

配置参考

到处都需要

可选的

模式

安全态势

• OAuth 2.1授权码+PKCE
• 不同的旋转刷新令牌(mcr_*)；持票人(mcp_*)在旋转过程中保持稳定
• 动态客户端注册可选地由初始访问令牌控制
• SQL列表(SqlGuard)on halopsa_query：仅 SELECT/WITH … SELECT，没有评论/;/DDL/DML/EXEC，8000个字符上限
• 在HTTP模式下启用HSTS+ForwardedHeaders
• 令牌+DCR注册通过ASP静态加密。NET数据保护
• 通过Redis在副本之间共享OAuth/DCR状态（或文件+观察器以获得最佳HA）
• 结构化的 tool_audit 每次MCP工具调用的记录行(user, tool, args_hash, traceId, status)
• 每个部署工具通过以下方式进行分配 MCP_ENABLED_TOOLS
• 门控 /metrics 端点时 MCP_METRICS_ENABLED=1
• 从日志中编辑的HaloPSA错误响应体
• 容器：非根UID 1001，无卷曲/wget，仅限K8s探头

局限性

• 文件后端是尽力而为的多副本。 默认 HALOPSA_TOKEN_STORE_BACKEND=file 使用本地加密的JSON文件+RWO PVC，并重新加载FileSystemWatcher。OAuth流状态和DCR注册遵循相同的模式。对于 replicaCount > 1，set halopsa.tokenStore.backend=redis 并提供 HALOPSA_REDIS_CONNECTION （或 HALOPSA_REDIS_CONNECTION_FILE)因此会话、OAuth状态和DCR是原子共享的。
• MCP流式HTTP会话在SDK中是本地进程 除非您启用无状态模式。随着 replicaCount > 1，set MCP_HTTP_STATELESS=1 （自动时 backend=redis)所以每个 POST /mcp 独立处理——这与Claude.ai的连接器后端在没有cookie关联的情况下调用工具的方式相匹配。用于状态模式(MCP_HTTP_STATELESS=0)，使用nginx upstream-hash-by: $http_mcp_session_id 或缩放到一个复制品。
• PVC上的数据保护键。 幸存的集群重建需要备份PVC或使用Azure密钥库进行包装。
• 每次部署一个HaloPSA租户。

威胁模型

此服务器设计用于 操作员控制部署 在这种情况下，组织信任自己的基础设施，但必须限制人工智能客户端可以对HaloPSA做什么。

信任假设

• OAuth用户同意是主要的关卡。 任何完成动态客户端注册并通过HaloPSA登录驱动用户的MCP客户端都会收到该用户HaloPSA权限范围内的会话。DCR是速率受限的；可选择用 MCP_DCR_INITIAL_ACCESS_TOKEN 用于私人部署。
• MCP服务器继承HaloPSA授权。 工具将HaloPSA称为经过身份验证的用户。为共享团队或组织范围的连接器提供专用的低权限OAuth应用程序，而不是重用超级管理应用程序。
• SqlGuard通过设计强制执行只读SQL。 halopsa_query 仅接受 SELECT / WITH … SELECT 与报告数据库相比，没有DDL、DML、注释或多语句批处理。其他工具使用类型化的REST端点；限制表面积 MCP_ENABLED_TOOLS.
• 秘密应该使用 *_FILE 在生产中安装。 更喜欢 HALOPSA_REDIS_CONNECTION_FILE 和 MCP_DCR_INITIAL_ACCESS_TOKEN_FILE 覆盖纯env变量，使值永远不会出现在 /proc/<pid>/environ 或 kubectl describe.
• 重定向URI在注册时被规范化 （小写主机，删除默认端口，删除尾部斜线）因此 /cb 和 /cb/ 比赛始终如一。可选择使用以下命令强制执行严格的回调分配列表 MCP_DCR_ALLOWED_REDIRECT_URIS.

超出范围/剩余风险

• 恶意但经过身份验证的用户可以使用自己的HaloPSA权限调用每个启用的工具（按设计）。
• 文件后端多副本同步最终是一致的；使用Redis实现严格的HA。
• 容器图像使用共同签名（无密钥、Sigstore）进行签名，并在OCI清单中包含SPDX SBOM；CycloneDX SBOM附加到GitHub发布版本中，用于准入策略验证（Approval/Kyverno）。

供应链

发布标签(v*)触发器 .github/workflows/docker-build.yml，其中：

1. 构建多拱形图像(linux/amd64, linux/arm64)
2. 将SPDX SBOM附加到OCI清单(sbom: true)
3. 使用共同签名无密钥签名（GitHub OIDC→ Sigstore）
4. 发布CycloneDX SBOM工件以进行离线验证

在部署时验证：

cosign verify redanthrax/halopsa-mcp:<version> --certificate-identity-regexp='.*' --certificate-oidc-issuer-regexp='.*'

可用工具

核心

门票

行动

时间表

目录

资产与知识

报告与调查

项目和进度安排

数据库目录

MCP服务器附带了HaloPSA报告数据库模式的离线转储 schema/catalog.json （845个表，15个域）。这些工具使MCP客户端在规划SQL钻取域时能够以低成本浏览它→ 表格→ 列，而不是将3MB转储到上下文中。

在构建/发布时，架构文件夹会自动复制到二进制文件旁边。用以下命令覆盖路径 HALOPSA_SCHEMA_PATH 如果你把它放在别处。

逃生舱口

故障排除

“未通过身份验证”:

1. 对于桌面stdio：运行 halopsa_setup 或打开 http://localhost:3000/ --在浏览器中使用登录URL
2. 登录后，在MCP主机中重试（无需重新启动）
3. 对于远程HTTP客户端：重新添加集成或启动新会话
4. 如果端口3000正在使用中，请检查MCP日志中的实际登录URL（临时端口回退）

查询返回0行:

1. 叫 halopsa_get_schema 首先验证表/列名
2. 检查日期时间筛选器是否使用UTC格式
3. 对于满意度调查，请使用 feedback 桌子与 halopsa_query
4. 对于时间表和操作分析，请使用架构中的关系助手
5. API报告可能需要HaloPSA中的特定权限

未找到时间表记录:

1. 使用 halopsa_query 要查找时间表ID: SELECT TSid, TSunum, TSdate FROM timesheet WHERE TSunum = <agent_id> AND TSdate >= '2026-03-04T00:00:00Z'
2. 如果该日期没有记录，请致电 halopsa_create_timesheet 更新前

表关系

该模式包括用于常见表关系的帮助程序：

• 故障 → 行动失误 （工单操作和更新）
• 故障 → 时间表.故障 （根据票记录的工作时间）
• 故障 → 反馈。Fb故障。 （客户满意度调查）
• 故障。请求类型 → 安魂曲。自动识别技术 （请求类型配置）

使用 halopsa_get_schema 查看连接这些表的示例查询。

需求

• .NET 10.0 SDK（用于本地开发）
• 已注册OAuth客户端的HaloPSA实例

贡献

看 贡献.md 和 代码_OF_CONDUCT.md.安全问题： 安全.md.

许可证

麻省理工学院——见 许可证.