使用说明

Halo ITSM MCP服务器

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

概述

模型上下文协议（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：

资源	工具	描述
门票	4	列出、获取、创建、更新门票
行动	4	列出、获取、创建、删除工单操作/注释
用户	4	列表、获取、通过电子邮件查找、获取当前用户
客户	4	列出、获取、创建、更新客户端
代理	2	列出，获取代理
团队	2	列出，获得团队
状态	2	列出、获取票证状态
票证类型	2	列出、获取门票类型
资产	4	列出、获取、创建、删除资产
站点	4	列出、获取、创建、更新网站
项目	4	列出、获取、创建、更新项目
机会	4	列出、获取、创建、更新机会
预约	3	列出、获取、创建、删除约会
附件	3	列出、获取、删除附件
物品	3	列出、获取、创建目录项
发票	3	列出、获取、作废发票
供应商	4	列出、获取、创建、更新供应商
报告	3	列出、获取、运行报告

两种运输方式

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

身份验证支持

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

先决条件

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

获得Halo API证书

以管理员身份登录Halo ITSM实例
引导到配置 → 集成 → 光环API
创建新的API应用程序：
- 选择 客户端凭据 用于服务器到服务器集成
- 注意 客户端ID 和 客户端密钥
为应用程序配置适当的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中文件或设置它们：

必需变量

变量	描述	示例
`HALO_BASE_URL`	您的Halo实例URL	`https://yourcompany.halopsa.com`
`HALO_CLIENT_ID`	API客户端ID	`abc123-def456-...`

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

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

变量	描述
`HALO_CLIENT_SECRET`	API客户端机密

选项B：密码授予

变量	描述
`HALO_USERNAME`	光环用户名
`HALO_PASSWORD`	光环密码

可选变量

变量	描述	默认值
`HALO_TENANT`	租户标识符（用于托管/多租户）	（无）
`HALO_SCOPE`	OAuth作用域	`all`
`PORT`	HTTP服务器端口（仅限SSE模式）	`3000`

示例.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 有人）。

端点

端点	方法	描述
`/sse`	GET	SSE连接端点（建立会话）
`/messages`	POST	JSON-RPC消息端点

与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) │
                                      └──────────────────┘

可用工具

门票

工具	说明
`halo_list_tickets`	列出带有过滤器的票证（搜索、客户端、状态、代理、分页）
`halo_get_ticket`	通过身份证获得一张包含完整详细信息的单程票
`halo_create_ticket`	创建新票证
`halo_update_ticket`	更新现有工单

操作（工单备注）

工具	说明
`halo_list_actions`	列出门票上的行动/注意事项
`halo_get_action`	按ID获取单个操作
`halo_create_action`	在工单中添加注释/操作
`halo_delete_action`	删除操作

用户

工具	说明
`halo_list_users`	列出具有筛选器的用户
`halo_get_user`	按ID获取用户
`halo_find_user_by_email`	通过电子邮件地址查找用户
`halo_get_me`	获取当前经过身份验证的用户

客户

工具	说明
`halo_list_clients`	列出客户/顾客
`halo_get_client`	通过ID获取客户端
`halo_create_client`	创建新客户端
`halo_update_client`	更新现有客户端

代理

工具	说明
`halo_list_agents`	列出所有代理
`halo_get_agent`	通过ID获取代理

团队

工具	说明
`halo_list_teams`	列出所有团队
`halo_get_team`	按ID获取团队

状态

工具	说明
`halo_list_statuses`	列出所有票证状态
`halo_get_status`	按ID获取状态

票证类型

工具	说明
`halo_list_ticket_types`	列出所有门票类型
`halo_get_ticket_type`	按ID获取门票类型

资产

工具	说明
`halo_list_assets`	列出带有过滤器的资产
`halo_get_asset`	按ID获取资产
`halo_create_asset`	创建新资产
`halo_delete_asset`	删除资产

站点

工具	说明
`halo_list_sites`	列出网站
`halo_get_site`	按ID获取网站
`halo_create_site`	创建新网站
`halo_update_site`	更新现有网站

项目

工具	说明
`halo_list_projects`	列出项目
`halo_get_project`	按ID获取项目
`halo_create_project`	创建新项目
`halo_update_project`	更新现有项目

机会（销售/CRM）

工具	说明
`halo_list_opportunities`	列出销售机会
`halo_get_opportunity`	通过ID获得机会
`halo_create_opportunity`	创造新机会
`halo_update_opportunity`	更新现有商机

预约

工具	说明
`halo_list_appointments`	列出约会
`halo_get_appointment`	凭身份证预约
`halo_create_appointment`	创建新约会
`halo_delete_appointment`	删除约会

附件

工具	说明
`halo_list_attachments`	列出票证的附件
`halo_get_attachment`	按ID获取附件元数据
`halo_delete_attachment`	删除附件

项目（目录）

工具	说明
`halo_list_items`	列出目录项
`halo_get_item`	按ID获取项目
`halo_create_item`	创建新的目录项

发票

工具	说明
`halo_list_invoices`	列出发票
`halo_get_invoice`	按ID获取发票
`halo_void_invoice`	作废发票

供应商

工具	说明
`halo_list_suppliers`	列出供应商
`halo_get_supplier`	通过ID获取供应商
`halo_create_supplier`	创建新供应商
`halo_update_supplier`	更新现有供应商

报告

工具	说明
`halo_list_reports`	列出可用报告
`halo_get_report`	按ID获取报告元数据
`halo_run_report`	执行报告并获得结果

建筑

项目结构

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                                                     │
       │←────────────────────────────────────────────────────────────────────│

发展

脚本

脚本	描述
`npm run build`	将TypeScript编译为JavaScript
`npm run dev`	在开发模式下运行stdio服务器
`npm run dev:sse`	以开发模式运行SSE服务器
`npm start`	运行stdio服务器（生产）
`npm run start:sse`	运行SSE服务器（生产）
`npm run typecheck`	运行TypeScript类型检查

添加新资源

创建API包装 在 src/api/<resource>.ts:

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

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

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

创建工具定义 在 src/mcp/tools/<resource>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 };
  },
};

在服务器中注册 (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许可证

贡献

欢迎投稿！拜托：

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