HaloPSA

HaloPSA MCP サーバー

HaloPSA と連携するための Model Context Protocol（MCP）サーバーです。効率的にツールを読み込めるよう、決定木アーキテクチャを採用しています。

ワンクリックデプロイ

重要

クリックする前に： このサーバーは @wyre-technology/node-halopsa に依存しています。このパッケージは GitHub Packages の npm レジストリでホストされています。GitHub Packages には匿名アクセスがありません。パッケージは公開されていますが、npm install ごとにトークンが必要です。クラウドビルダーが代わりに npm install を実行するため、トークンを渡す必要があります。そうしないと、ビルドは npm error 401 Unauthorized ... npm.pkg.github.com で失敗します。

1. read:packages スコープを持つ GitHub Personal Access Token を作成します（classic token）。 GitHub アカウントはどれでも使えます。公開パッケージを読み取るために wyre-technology 組織のメンバーである必要はありません。
2. デプロイフローで求められたら、ビルド変数としてトークンを追加します。
   • Cloudflare Workers → NODE_AUTH_TOKEN という名前のビルド変数に PAT を設定します（Workers → Settings → Build → Variables and Secrets）。
   • DigitalOcean App Platform → スコープを Build Time にした暗号化環境変数 GITHUB_TOKEN に PAT を設定します（.do/app.yaml ではすでに宣言されています）。

メモ

DigitalOcean のターゲットは Docker イメージ全体をビルドし、MCP サーバー全体を HTTP 経由で実行します。オペレーターにはこちらを推奨します。Cloudflare Workers のターゲットは現在、薄いエントリーポイントにすぎません（Workers のトランスポートアダプターが実装されるまでは /mcp ルートが 501 を返します）。ゲートウェイ型のデプロイに適しています。完全なセルフホスト可能なサーバーを使う場合は、DigitalOcean またはビルド済みコンテナーイメージ（ghcr.io/wyre-ai/halopsa-mcp）をおすすめします。

アーキテクチャ

この MCP サーバーは、すべてのツールを最初から公開するのではなく、階層型のツール読み込み方式を採用しています。

1. ナビゲーションフェーズ：最初はナビゲーションツール（halopsa_navigate）のみを公開します。
2. ドメインの選択：ユーザーがドメイン（tickets、clients、assets、agents、invoices、categories）を選択します。
3. ドメインツール：選択後、サーバーがドメイン固有のツールを公開します。
4. 遅延読み込み：ドメインハンドラーと HaloPSA クライアントは必要に応じて読み込まれます。

このアーキテクチャには、次の利点があります。

• 認知負荷を軽減します（選択するツールが少なくなります）。
• 初期読み込み時間を短縮します。
• 関連する操作をより適切に整理できます。
• ナビゲーション状態が明確になります。

インタラクティブなチケットカード（MCP Apps）

halopsa_tickets_get は、MCP Apps ホスト（Claude Desktop/web）ではインタラクティブなカードとして表示されます。カード内の「Add note」から halopsa_tickets_add_action を呼び出す一連のやり取りにも対応しています。他のホストでのプレーン JSON の動作に変更はありません。 カードはデフォルトではニュートラルなデザインで、window.__BRAND__ の注入、または MCP_BRAND_* 環境変数（MCP_BRAND_NAME、MCP_BRAND_LOGO_URL、MCP_BRAND_PRIMARY_COLOR、MCP_BRAND_ACCENT_COLOR、MCP_BRAND_BG、MCP_BRAND_TEXT）でブランド設定できます。再ビルドは不要です。

インストール

このパッケージは GitHub Packages の npm レジストリで公開されており、公開パッケージであってもトークンが必要です。一度認証してからインストールします。

# Authenticate npm to GitHub Packages (token needs the read:packages scope)
export NODE_AUTH_TOKEN=$(gh auth token)   # or a PAT with read:packages

npm install @wyre-ai/halopsa-mcp

リポジトリの .npmrc では、すでに @wyre-technology スコープを GitHub Packages に向け、トークンを NODE_AUTH_TOKEN から読み込むように設定されているため、追加の設定は不要です。

設定

以下の環境変数を設定します。

変数	必須	説明
HALOPSA_CLIENT_ID	はい	OAuth 2.0 クライアント ID
HALOPSA_CLIENT_SECRET	はい	OAuth 2.0 クライアントシークレット
HALOPSA_TENANT	いずれか	テナント名（例：yourcompany）
HALOPSA_BASE_URL	以下	明示的なベース URL（例：https://yourcompany.halopsa.com）

使用方法

単独で実行する

# Set credentials
export HALOPSA_CLIENT_ID="your-client-id"
export HALOPSA_CLIENT_SECRET="your-client-secret"
export HALOPSA_TENANT="yourcompany"

# Run the server
npx @wyre-ai/halopsa-mcp

Claude Desktop の設定

Claude Desktop の claude_desktop_config.json に追加します。

{
  "mcpServers": {
    "halopsa": {
      "command": "npx",
      "args": ["@wyre-ai/halopsa-mcp"],
      "env": {
        "HALOPSA_CLIENT_ID": "your-client-id",
        "HALOPSA_CLIENT_SECRET": "your-client-secret",
        "HALOPSA_TENANT": "yourcompany"
      }
    }
  }
}

Docker

docker build -t halopsa-mcp .
docker run -e HALOPSA_CLIENT_ID=xxx -e HALOPSA_CLIENT_SECRET=xxx -e HALOPSA_TENANT=yourcompany halopsa-mcp

利用可能なドメイン

チケット

サポートチケットの管理、新しいチケットの作成、ステータスの更新、アクションやメモの追加を行います。

ツール：

• halopsa_tickets_list - フィルターを指定してチケットを一覧表示します（category_1 のみ対応。category_2～category_4 は拒否されます）
• halopsa_tickets_get - チケットの詳細を取得します
• halopsa_tickets_create - 新しいチケットを作成します（category_1～category_4 は任意）
• halopsa_tickets_update - 既存のチケットを更新します（category_1～category_4 は任意）
• halopsa_tickets_add_action - チケットにメモやアクションを追加します

カテゴリー

Halo のチケットカテゴリーを検索し、トリアージで category_1～category_4 を割り当てられるようにします（カテゴリー名は該当するレベルに一致します）。

ツール：

• halopsa_categories_list - チケットカテゴリーの1ページ分を一覧表示します（limit の既定値は50、page_no は1から始まります）
• halopsa_categories_get - ID でカテゴリーを取得します

クライアント

HaloPSA の会社やクライアントを管理します。

ツール：

• halopsa_clients_list - クライアントを一覧表示します
• halopsa_clients_get - クライアントの詳細を取得します
• halopsa_clients_create - 新しいクライアントを作成します
• halopsa_clients_search - 名前でクライアントを検索します

資産

構成アイテムや資産を管理します。

ツール：

• halopsa_assets_list - フィルターを指定して資産を一覧表示します
• halopsa_assets_get - 資産の詳細を取得します
• halopsa_assets_search - 資産を検索します
• halopsa_assets_list_types - 利用可能な資産タイプを一覧表示します

エージェント

技術者とチームを表示します。

ツール：

• halopsa_agents_list - エージェントや技術者を一覧表示します
• halopsa_agents_get - エージェントの詳細を取得します
• halopsa_teams_list - チームを一覧表示します

請求書

請求情報と請求書を表示します。

ツール：

• halopsa_invoices_list - フィルターを指定して請求書を一覧表示します
• halopsa_invoices_get - 請求書の詳細を取得します

ナビゲーションツール

常に利用できます：

• halopsa_navigate - 作業するドメインを選択します
• halopsa_status - 現在の状態と認証情報の状態を表示します
• halopsa_back - メインメニューに戻ります（ドメイン内にいる場合）

ワークフローの例

User: Check my tickets
Claude: [calls halopsa_navigate with domain="tickets"]
       -> Navigated to tickets domain. Available tools: ...

User: List open tickets
Claude: [calls halopsa_tickets_list with open_only=true]
       -> [ticket list results]

User: Now show me clients
Claude: [calls halopsa_back]
       -> Navigated back to main menu.
       [calls halopsa_navigate with domain="clients"]
       -> Navigated to clients domain.

レート制限

HaloPSA のレート制限は、3分間あたり500リクエストです。基盤となる @asachs01/node-halopsa クライアントが、リクエストのスロットリングによって自動的にこの制限に対応します。

ライセンス

Apache-2.0