HaloPSA MCPツール

HaloPSA API と対話するためのモデルコンテキストプロトコル (MCP) サーバー。

概要

このパッケージは、AIアシスタント（Claudeなど）がHaloPSA APIとやり取りできるようにするモデルコンテキストプロトコル（Model Context Protocol）サーバー実装を提供します。様々な構成で使用できます。

スタンドアロンサーバーとして
Claude Desktopと統合
Node.jsアプリケーションのライブラリとして

特徴

複数のトランスポートタイプ (stdio、http、tcp) をサポートする MCP サーバー
チケット、ユーザー、アセットなどとやり取りするためのツール
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 の設定 ([設定] > [拡張機能] > [MCP サーバーの追加]) で、この MCP サーバーを使用するように Claude Desktop を構成します。
- 名前: 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 サーバーで利用可能なすべてのツールを一覧表示します

クロードデスクトップ統合

このパッケージには、さまざまな MCP SDK バージョンで動作する Claude Desktop 統合の統合実装が含まれています。

統合実装の主な機能:

SDK 互換性レイヤーによるバージョン間の互換性
Claudeデスクトップ設定からの自動構成検出
堅牢なエラー処理とフォールバックメカニズム
包括的なログ記録とデバッグのサポート

トラブルシューティング

よくある問題

モジュールのインポート

インポートまたはモジュールシステムに関連するエラーが発生した場合:

SyntaxError: Cannot use import statement outside a module

解決策: プロジェクト設定に正しいインポート構文を使用していることを確認してください。このパッケージは主にCommonJSを使用しているため、 require()ステートメントを使用してください。

認証エラー

HaloPSA 認証に関連するエラーが表示された場合:

Error: Invalid client credentials

解決策: 環境変数または構成でクライアント ID とクライアントシークレットを確認します。

輸送問題

特定のトランスポートタイプでサーバーが起動に失敗した場合:

Error: Unsupported transport

解決策: サポートされているトランスポートタイプ (「stdio」、「http」、または「tcp」) のいずれかを使用していることを確認します。

クロードデスクトップ統合の問題

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