HaloITSM MCP

Halo ITSM MCP服务器

A. 模型上下文协议（MCP） 为AI助手提供访问权限的服务器 光环ITSM/PSA/CRM REST API这使得像Claude、GPT和其他大型语言模型（LLM）能够通过标准化协议与您的Halo实例进行交互。

目录

• 概述
• 特性
• 先决条件
• 安装
• 配置
• 用法

- stdio模式（本地） - SSE模式（远程/HTTP）

• 可用工具
• 建筑
• 发展
• 故障排除
• 许可证

______________________________________________________________________

概述

模型上下文协议（MCP）是一个开放标准，允许AI应用程序安全地连接到外部数据源和工具。此服务器实现了Halo ITSM的MCP，使AI助手能够：

• 查询票证、用户、客户端和其他实体 从您的Halo实例
• 创建和更新工单 以编程方式
• 管理资产、项目、约会等
• 运行报告并检索商业智能数据

Halo ITSM是什么？

光环ITSM （也称为HaloPSA和HaloCRM）是一个全面的IT服务管理平台，供MSP、IT部门和服务组织使用。它通过统一的平台提供票务、资产管理、项目管理、发票和CRM功能。

什么是MCP？

这 模型上下文协议 是一个开放协议，规范了人工智能应用程序如何连接到外部数据源和工具。它能够：

• 工具调用：AI可以使用参数调用特定函数
• 安全认证：凭据由MCP服务器管理，不向AI公开
• 结构化数据交换：响应的格式是为了实现最佳的AI消费

______________________________________________________________________

特性

18个资源组，包含60多种工具

此MCP服务器全面覆盖Halo ITSM API：

两种运输方式

1. stdio模式：通过命令行本地使用（npx，直接执行）
2. SSE模式：用于远程/web部署的带有服务器发送事件的HTTP服务器

身份验证支持

• 客户端凭据流：机器对机器身份验证（推荐）
• 密码授予流程：用户名/密码身份验证（回退）
• 自动令牌管理：令牌会自动缓存和刷新

______________________________________________________________________

先决条件

• Node.js v18.0.0或更高版本
• Halo ITSM实例 启用API访问
• API证书 （客户端ID+客户端密码，或用户名+密码）

获得Halo API证书

1. 以管理员身份登录Halo ITSM实例
2. 引导到 配置 → 集成 → 光环API
3. 创建新的API应用程序：

- 选择 客户端凭据 用于服务器到服务器集成 - 注意 客户端ID 和 客户端密钥

1. 为应用程序配置适当的API权限

______________________________________________________________________

安装

来源

# Clone the repository
git clone https://github.com/your-org/halo-mcp.git
cd halo-mcp

# Install dependencies
npm install

# Build the TypeScript code
npm run build

使用npx（即将推出）

npx halo-mcp

______________________________________________________________________

配置

服务器是通过环境变量配置的。创建一个 .env 在shell中文件或设置它们：

必需变量

身份验证变量（选择一组）

选项A：客户端凭据（推荐）

选项B：密码授予

可选变量

示例.env文件

# Halo Instance
HALO_BASE_URL=https://yourcompany.halopsa.com
HALO_TENANT=yourcompany

# Client Credentials Auth (recommended)
HALO_CLIENT_ID=your-client-id
HALO_CLIENT_SECRET=your-client-secret

# OR Password Grant Auth
# HALO_CLIENT_ID=your-client-id
# HALO_USERNAME=your-username
# HALO_PASSWORD=your-password

# Optional
HALO_SCOPE=all
PORT=3000

______________________________________________________________________

用法

stdio模式（本地）

stdio模式非常适合本地开发和与Claude Desktop等MCP客户端的直接集成。

直接运行

# Development (with hot reload)
npm run dev

# Production
npm run build
npm start

与MCP检查员一起

这 MCP检查员 适用于测试：

npx @modelcontextprotocol/inspector node dist/index.js

Claude桌面配置

添加到您的Claude桌面配置(claude_desktop_config.json):

{
  "mcpServers": {
    "halo-itsm": {
      "command": "node",
      "args": ["/path/to/halo-mcp/dist/index.js"],
      "env": {
        "HALO_BASE_URL": "https://yourcompany.halopsa.com",
        "HALO_CLIENT_ID": "your-client-id",
        "HALO_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

SSE模式（远程/HTTP）

SSE（服务器发送事件）模式运行HTTP服务器，支持远程访问和基于浏览器的MCP客户端。

运行SSE服务器

# Development
npm run dev:sse

# Production
npm run build
npm run start:sse

服务器启动于 http://localhost:3000 默认情况下（可通过配置 PORT 有人）。

端点

与MCP检查员（SSE）连接

npx @modelcontextprotocol/inspector

然后连接到： http://localhost:3000/sse

SSE模式架构

┌─────────────────┐     GET /sse      ┌──────────────────┐
│   MCP Client    │ ─────────────────→│                  │
│  (Inspector,    │     SSE Stream    │   Halo MCP SSE   │
│   Browser, etc) │ ←─────────────────│     Server       │
│                 │                   │   (Express.js)   │
│                 │  POST /messages   │                  │
│                 │ ─────────────────→│                  │
└─────────────────┘                   └────────┬─────────┘
                                               │
                                               │ HTTPS
                                               ▼
                                      ┌──────────────────┐
                                      │   Halo ITSM API  │
                                      │  (Your Instance) │
                                      └──────────────────┘

______________________________________________________________________

可用工具

门票

操作（工单备注）

用户

客户

代理

团队

状态

票证类型

资产

站点

项目

机会（销售/CRM）

预约

附件

项目（目录）

发票

供应商

报告

______________________________________________________________________

建筑

项目结构

halo-mcp/
├── src/
│   ├── index.ts              # stdio mode entry point
│   ├── httpServer.ts         # SSE mode entry point
│   ├── config.ts             # Configuration loader
│   ├── auth/
│   │   └── haloAuth.ts       # OAuth authentication client
│   ├── api/
│   │   ├── httpClient.ts     # HTTP client with auth injection
│   │   ├── tickets.ts        # Tickets API wrapper
│   │   ├── users.ts          # Users API wrapper
│   │   ├── teams.ts          # Teams API wrapper
│   │   ├── agents.ts         # Agents API wrapper
│   │   ├── status.ts         # Status API wrapper
│   │   ├── actions.ts        # Actions API wrapper
│   │   ├── appointments.ts   # Appointments API wrapper
│   │   ├── assets.ts         # Assets API wrapper
│   │   ├── attachments.ts    # Attachments API wrapper
│   │   ├── clients.ts        # Clients API wrapper
│   │   ├── invoices.ts       # Invoices API wrapper
│   │   ├── items.ts          # Items API wrapper
│   │   ├── opportunities.ts  # Opportunities API wrapper
│   │   ├── projects.ts       # Projects API wrapper
│   │   ├── reports.ts        # Reports API wrapper
│   │   ├── sites.ts          # Sites API wrapper
│   │   ├── suppliers.ts      # Suppliers API wrapper
│   │   └── ticketTypes.ts    # Ticket Types API wrapper
│   └── mcp/
│       ├── server.ts         # MCP server setup
│       └── tools/
│           ├── ticketsTools.ts
│           ├── usersTools.ts
│           ├── teamsTools.ts
│           ├── agentsTools.ts
│           ├── statusTools.ts
│           ├── actionsTools.ts
│           ├── appointmentsTools.ts
│           ├── assetsTools.ts
│           ├── attachmentsTools.ts
│           ├── clientsTools.ts
│           ├── invoicesTools.ts
│           ├── itemsTools.ts
│           ├── opportunitiesTools.ts
│           ├── projectsTools.ts
│           ├── reportsTools.ts
│           ├── sitesTools.ts
│           ├── suppliersTools.ts
│           └── ticketTypesTools.ts
├── dist/                     # Compiled JavaScript
├── Documentation/
│   └── HaloApiDocs/          # Halo API reference documentation
├── package.json
├── tsconfig.json
└── README.md

组件层

┌─────────────────────────────────────────────────────────────────┐
│                        MCP Transport Layer                       │
│  ┌─────────────────────┐    ┌──────────────────────────────┐   │
│  │   stdio Transport   │    │     SSE Transport (HTTP)     │   │
│  │    (index.ts)       │    │     (httpServer.ts)          │   │
│  └─────────────────────┘    └──────────────────────────────┘   │
└───────────────────────────────┬─────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                         MCP Server Layer                         │
│                         (mcp/server.ts)                          │
│  - Tool registration                                             │
│  - Request routing                                               │
│  - Response formatting                                           │
└───────────────────────────────┬─────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                          Tools Layer                             │
│                    (mcp/tools/*.ts)                              │
│  - Input validation                                              │
│  - Parameter mapping                                             │
│  - Response transformation                                       │
└───────────────────────────────┬─────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                        API Wrappers Layer                        │
│                         (api/*.ts)                               │
│  - Resource-specific methods                                     │
│  - Type definitions                                              │
│  - Query building                                                │
└───────────────────────────────┬─────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                       HTTP Client Layer                          │
│                    (api/httpClient.ts)                           │
│  - Request execution                                             │
│  - Error handling                                                │
│  - Query serialization                                           │
└───────────────────────────────┬─────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                     Authentication Layer                         │
│                    (auth/haloAuth.ts)                            │
│  - Token acquisition                                             │
│  - Token caching                                                 │
│  - Automatic refresh                                             │
└─────────────────────────────────────────────────────────────────┘

身份验证流程

┌─────────────┐                    ┌─────────────┐                    ┌─────────────┐
│  MCP Tool   │                    │ Auth Client │                    │  Halo API   │
└──────┬──────┘                    └──────┬──────┘                    └──────┬──────┘
       │                                  │                                  │
       │ 1. Request (needs auth)          │                                  │
       │─────────────────────────────────→│                                  │
       │                                  │                                  │
       │                                  │ 2. Check cached token            │
       │                                  │────────┐                         │
       │                                  │        │                         │
       │                                  │←───────┘                         │
       │                                  │                                  │
       │                                  │ 3. Token expired?                │
       │                                  │    POST /auth/token              │
       │                                  │─────────────────────────────────→│
       │                                  │                                  │
       │                                  │ 4. New access_token              │
       │                                  │←─────────────────────────────────│
       │                                  │                                  │
       │                                  │ 5. Cache token                   │
       │                                  │────────┐                         │
       │                                  │        │                         │
       │                                  │←───────┘                         │
       │                                  │                                  │
       │ 6. Return access token           │                                  │
       │←─────────────────────────────────│                                  │
       │                                  │                                  │
       │ 7. API request with Bearer token                                    │
       │────────────────────────────────────────────────────────────────────→│
       │                                  │                                  │
       │ 8. API response                                                     │
       │←────────────────────────────────────────────────────────────────────│

______________________________________________________________________

发展

脚本

添加新资源

1. 创建API包装 在 src/api/.ts:

   export class ResourceApi {
     constructor(private http: HaloHttpClient) {}

     async list(params?: ListParams): Promise {
       return this.http.get("/Resource", params);
     }

     async getById(id: number): Promise {
       return this.http.get(`/Resource/${id}`);
     }
   }

1. 创建工具定义 在 src/mcp/tools/Tools.ts:

   export const listResourceTool = {
     name: "halo_list_resources",
     description: "List resources with optional filters",
     inputSchema: {
       type: "object" as const,
       properties: {
         // Define input properties
       },
       additionalProperties: false,
     },
     handler: async (input, api) => {
       const results = await api.list(input);
       return { resources: results };
     },
   };

1. 在服务器中注册 (src/mcp/server.ts):

- 导入API类和工具 - 创建API实例 - 添加工具 allTools 数组

MCP检验员测试

# stdio mode
npx @modelcontextprotocol/inspector node dist/index.js

# SSE mode
npm run dev:sse
# Then in another terminal:
npx @modelcontextprotocol/inspector
# Connect to http://localhost:3000/sse

______________________________________________________________________

故障排除

身份验证错误

“身份验证失败（401）”

• 验证您的 HALO_CLIENT_ID 和 HALO_CLIENT_SECRET 是正确的
• 检查API应用程序在Halo中是否具有适当的权限
• 确保在Halo实例上启用API

“缺少凭据”

• 提供其中之一 HALO_CLIENT_SECRET 或两者 HALO_USERNAME 和 HALO_PASSWORD

连接问题

“已节约”

• 验证 HALO_BASE_URL 正确且可访问
• 检查防火墙或网络限制
• 确保URL没有尾随斜线

SSE连接立即关闭

• 确保 req.body 传递给 handlePostMessage() （已在最新版本中修复）
• 检查浏览器控制台是否存在CORS错误

工具错误

“未知工具： "

• 验证该工具是否已在中注册 src/mcp/server.ts
• 重建与 npm run build

空结果

• 请检查您的API凭据是否具有访问资源的权限
• 验证过滤器是否正确（例如。， statusId 对比 status_id)

调试模式

通过检查服务器控制台输出启用详细日志记录。记录每个SSE连接和消息。

______________________________________________________________________

作者

• 米歇尔·布拉加·吉马良斯 -首席开发人员
• 克劳德代码 （Anthropic）-人工智能配对程序员

______________________________________________________________________

许可证

MIT许可证

______________________________________________________________________

贡献

欢迎投稿！拜托：

1. 分叉存储库
2. 创建要素分支
3. 进行更改
4. 提交拉取请求

资源

• Halo ITSM API文档
• 模型上下文协议规范
• MCP TypeScript SDK