HaloPSA MCP 工具

用于与 HaloPSA API 交互的模型上下文协议 (MCP) 服务器。

概述

此软件包提供了一个模型上下文协议服务器实现，允许 AI 助手（如 Claude）与 HaloPSA API 交互。它可以在各种配置中使用：

作为独立服务器
与 Claude Desktop 集成
作为 Node.js 应用程序中的库

特征

MCP 服务器支持多种传输类型（stdio、http、tcp）
用于与票证、用户、资产等进行交互的工具
与 Claude Desktop 无缝集成
可配置的日志记录和错误处理
强大的安全检查
与 MCP SDK 跨版本兼容

安装

NPM 全局安装

npm install -g haloapi-mcp-tools

本地安装

npm install haloapi-mcp-tools

配置

使用以下环境变量在项目根目录中创建一个.env文件：

# Required HaloPSA API Configuration
HALO_API_URL=https://yourhalo.haloservicedesk.com/api
HALO_CLIENT_ID=your_client_id
HALO_CLIENT_SECRET=your_client_secret

# Optional Configuration
HALO_API_VERSION=v3
HALO_SCOPE=all
HALO_TENANT=your_tenant_id
TRANSPORT=stdio
PORT=3000
DEBUG=false

或者，如果该工具作为 Claude Desktop 集成运行，则可以使用 Claude Desktop 的配置。

用法

用作独立服务器

# Start the server using stdio transport (default)
haloapi-mcp-server

# Start with HTTP transport
TRANSPORT=http PORT=3000 haloapi-mcp-server

# Start with debug mode
DEBUG=true haloapi-mcp-server

# Command-line options are also available
haloapi-mcp-server --transport http --port 3000 --debug

与 Claude Desktop 一起使用

与 Claude Desktop 一起使用：

全局安装包：

npm install -g haloapi-mcp-tools

在 Claude Desktop 设置中配置 Claude Desktop 以使用此 MCP 服务器（设置 > 扩展 > 添加 MCP 服务器）：
- 名称：HaloPSA
- 命令：haloapi-desktop-mcp
- 环境变量（可选）：
  - HALO_API_URL：您的 HaloPSA API URL
  - HALO_CLIENT_ID：您的客户端 ID
  - HALO_CLIENT_SECRET：您的客户端密钥
开始在 Claude 对话中使用 HaloPSA 工具！

或者，如果您已经克隆了此存储库，则可以运行：

# Run the MCP server for Claude Desktop
npm run claude

# Run with debug logging
npm run claude:debug

# Or use the convenience script
./run-mcp.sh desktop

MCP 服务器将自动检测并使用您的 Claude Desktop 设置中的配置。

用作库

const { startServer } = require('haloapi-mcp-tools');

async function main() {
  const server = await startServer({
    transport: 'stdio', // or 'http', 'tcp'
    port: 3000,
    debug: true,
    haloBaseUrl: 'https://yourhalo.haloservicedesk.com/api',
    haloClientId: 'your_client_id',
    haloClientSecret: 'your_client_secret'
  });
  
  // Server is now running
  console.log('Server started successfully');
  
  // To shut down the server
  // await server.close();
}

main().catch(console.error);

结构

代码库采用以下结构组织：

src/core/ - 核心 MCP 服务器实现
src/tools/ - HaloPSA API 操作的工具定义
src/utils/ ——用于日志记录、验证等的实用函数。
src/services/ - HaloPSA API 操作的服务层
src/api/ - HaloPSA 的 API 客户端
bin/ ——可执行入口点
scripts/ ——用于开发和维护的实用脚本

MCP 工具

该软件包提供了几种与 HaloPSA 交互的工具，并实现了 Claude Desktop 所需的标准 MCP 协议方法：

票务工具

get-tickets ：获取带有可选筛选功能的票证列表
get-ticket ：获取特定票证的详细信息
create-ticket ：创建新票据
update-ticket ：更新现有票证
delete-ticket ：删除票证
get-ticket-comments ：获取特定票证的评论
add-comment ：向票证添加评论

用户工具

get-users ：获取带有可选过滤的用户列表
get-user ：获取特定用户的详细信息
create-user ：创建新用户
update-user ：更新现有用户
delete-user ：删除用户
get-agents ：获取代理列表

资产工具

get-assets ：获取带有可选过滤的资产列表
get-asset ：获取特定资产的详细信息
create-asset ：创建新资产
update-asset ：更新现有资产
delete-asset ：删除资产
get-asset-types ：获取所有资产类型的列表

标准 MCP 方法

resources/list ：列出 MCP 服务器中所有可用资源
prompts/list ：列出 Claude Desktop 集成的所有可用提示
tools/list ：列出 MCP 服务器中所有可用的工具

Claude 桌面集成

该软件包包括适用于不同 MCP SDK 版本的 Claude Desktop 集成的统一实现。

统一实施的主要特点：

通过 SDK 兼容层实现跨版本兼容
从 Claude Desktop 设置中自动检测配置
强大的错误处理和回退机制
全面的日志记录和调试支持

故障排除

常见问题

模块导入

如果遇到与导入或模块系统相关的错误：

SyntaxError: Cannot use import statement outside a module

解决方案：检查项目配置中使用的导入语法是否正确。此包主要使用 CommonJS，因此请使用require()语句。

身份验证错误

如果您看到与 HaloPSA 身份验证相关的错误：

Error: Invalid client credentials

解决方案：在环境变量或配置中验证您的客户端 ID 和客户端密钥。

运输问题

如果服务器无法以特定传输类型启动：

Error: Unsupported transport

解决方案：确保您使用的是受支持的传输类型之一：“stdio”、“http”或“tcp”。

Claude 桌面集成问题

如果 Claude Desktop 无法连接到您的 MCP 服务器或显示有关不支持的方法的错误：

Error: Method not supported: tools/list

解决方案：确保您使用的是该软件包的最新版本，其中包括统一的 MCP 实现以及对 MCP 协议的强大支持。

JSON 解析错误

如果您在 MCP 服务器日志中看到类似 JSON 解析错误：

Error parsing JSON message: Unexpected non-whitespace character after JSON at position X

解决方案：最新版本增强了 JSON 处理功能，可自动修复常见的格式错误消息问题。如果您仍然遇到问题，请启用调试模式以查看更多详细信息：

DEBUG=true haloapi-mcp-server

调试

要启用详细的调试信息，请设置 DEBUG 环境变量：

DEBUG=true haloapi-mcp-server

您还可以增加日志级别以获取更详细的信息：

LOG_LEVEL=trace haloapi-mcp-server

对于 Claude Desktop 集成，您可以在以下位置找到日志：

macOS： ~/Library/Logs/Claude/mcp-server-halopsa.log
Windows： %APPDATA%\Claude\Logs\mcp-server-halopsa.log
Linux： ~/.local/share/claude/logs/mcp-server-halopsa.log

测试

您可以使用附带的测试脚本测试 MCP 服务器：

# Run the test script against a running server
npm run test:mcp

# Run the automated tests
npm test

交互式测试脚本允许您测试单个工具并检查其响应，这对于调试和开发很有用。

开发与扩展

代码库遵循几种设计模式和实践，在添加新功能或进行更改时应遵循这些模式和实践：

设计模式

兼容层模式：在src/sdk-compat.js中使用，以在不同的 SDK 版本之间提供一致的接口。
依赖注入：在整个代码库中使用，为模块提供依赖关系，使它们更易于测试和更加模块化。
模块模式：每个组件被组织成具有明确职责和接口的模块。
外观模式：主要入口点（ desktop-mcp-unified.js 、 standalone-mcp.js ）为底层功能提供了简化的接口。

添加新功能

向代码库添加新功能时，请遵循以下步骤：

将新的工具定义添加到src/tools/中的相应模块
在src/tools/index.js中注册新工具
将任何新的实用程序函数添加到src/utils/中的相应模块
在tests/目录中为新功能编写测试
更新文档以反映新功能

执照

贡献者

苏莱曼·曼吉（ @ssmanji89 ）

HaloPSA MCP Tools

Integrations