SuperOps

SuperOps.ai MCP サーバー

GraphQL API を使用して SuperOps.ai PSA/RMM プラットフォームと連携するツールを提供する、Claude 向けの MCP サーバーです。

ワンクリックデプロイ

オペレーター向けメモ — GitHub Packages の認証。 このパッケージは GitHub Packages の @wyre-ai スコープに公開されています。インストールのたびに 認証トークンが必要です（GitHub Packages では、パブリックパッケージであっても匿名での読み取りは できません）。read:packages スコープを持つ GitHub Personal Access Token を作成し、 クラウドビルダーに渡してください。

• Cloudflare Workers — NODE_AUTH_TOKEN という名前のビルド変数に PAT を設定します。
• DigitalOcean App Platform — GITHUB_TOKEN という名前のビルド時シークレットに PAT を設定します。

ローカルにインストールする場合は、npm install の前に export NODE_AUTH_TOKEN=$(gh auth token) を実行してください。

機能

• 決定木アーキテクチャ：ドメイン（クライアント、チケット、アセット、技術者）に移動して、関連するツールを確認できます
• 遅延読み込み：ドメインモジュールを必要に応じて読み込み、起動を高速化します
• 完全な CRUD 操作：エンティティの一覧表示、取得、作成、更新ができます
• GraphQL サポート：高度な操作にはカスタムクエリを使用できます
• インタラクティブなチケットカード（MCP Apps）：チケットの結果は MCP Apps ホストでインタラクティブなカードとして表示されます。デフォルトではニュートラルなデザインで、window.__BRAND__ の注入または MCP_BRAND_* 環境変数によってブランド設定が可能です

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

superops_tickets_get は MCP Apps ホスト（Claude Desktop/web）でインタラクティブなカードとして表示されます。カード内の「Add note」操作では superops_tickets_add_note を介してやり取りを行い、常に内部専用のメモ（isPublic: false）を投稿します。他のホストでは、プレーン 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）によってブランド設定が可能です。再ビルドは不要です。

インストール

# The @wyre-ai scope lives on GitHub Packages and needs a token to install:
export NODE_AUTH_TOKEN=$(gh auth token)
npm install @wyre-ai/superops-mcp

設定

.env.example をコピーし、以下の変数を設定してください。この例では CONDUIT_S2S_SECRET を空のままにし、openssl rand -hex 32 を使って実際の値を生成してください。この値をコミットしないでください。

export SUPEROPS_API_TOKEN="your-api-token"
export SUPEROPS_SUBDOMAIN="yourcompany"
export SUPEROPS_REGION="us"  # or "eu" for EU region

変数	必須	説明
SUPEROPS_API_TOKEN	stdio および AUTH_MODE=env の場合	SuperOps.ai API トークン
SUPEROPS_SUBDOMAIN	stdio および AUTH_MODE=env の場合	SuperOps.ai のサブドメイン
SUPEROPS_REGION	いいえ	us（デフォルト）または eu
MCP_TRANSPORT	いいえ	stdio（デフォルト）または http
AUTH_MODE	いいえ	env（Docker の外ではデフォルト）または gateway。イメージと Compose のデフォルトは gateway です。Gateway モードでは、各 /mcp リクエストに X-SuperOps-API-Token と X-SuperOps-Subdomain が必要で、SUPEROPS_* へのフォールバックは行いません。
CONDUIT_S2S_SECRET	HTTP では必須	X-Gateway-S2S 用の HMAC シークレット。空の値や既知のプレースホルダー（replace-with-a-real-secret、your-s2s-secret、changeme など）が指定されると、エラーが記録され、ゼロ以外の終了コードで終了します。未設定の場合、Compose は起動しません。この値がログに記録されることはありません。
MCP_ALLOW_INSECURE_DEV	いいえ	CONDUIT_S2S_SECRET を設定せずに HTTP を起動する場合に限り、ローカル開発用として 1 に設定します。警告が記録され、X-Gateway-S2S は検証されず、127.0.0.1 のみにバインドされます。ループバック以外の MCP_HTTP_HOST が指定されている場合は起動を拒否します。このフラグを設定していても、既知のプレースホルダーシークレットは拒否されます。
MCP_HTTP_HOST	いいえ	実際の CONDUIT_S2S_SECRET が設定されている場合のバインドアドレス。デフォルトは 127.0.0.1 です。コンテナイメージでは 0.0.0.0 が設定されます。
MCP_HTTP_PORT	いいえ	HTTP ポート。デフォルトは 8080 です。

/health は引き続き認証不要で、認証情報を読み取りません。stdio トランスポートでは CONDUIT_S2S_SECRET を使用しません。

HTTP 認証

MCP_TRANSPORT=http の場合、CONDUIT_S2S_SECRET が設定されていると、すべての /mcp リクエストに X-Gateway-S2S を含める必要があります。ヘッダーの値は t=<unix seconds>,v1=<hex> です。ここで、hex は CONDUIT_S2S_SECRET をキーとして、文字列 t=<unix seconds> をそのまま HMAC-SHA256 で処理した値（小文字の16進数64文字）です。タイムスタンプはサーバー時刻から300秒以内でなければなりません。ヘッダーがない、または無効な場合は、ベンダーの認証情報を読み取る前に HTTP 401 が返されます。

TS=$(date +%s)
SIG=$(printf 't=%s' "$TS" | openssl dgst -sha256 -hmac "$CONDUIT_S2S_SECRET" -hex | awk '{print $NF}')
curl -sS http://127.0.0.1:8080/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "X-Gateway-S2S: t=${TS},v1=${SIG}" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

AUTH_MODE=gateway の場合は、X-SuperOps-API-Token と X-SuperOps-Subdomain も追加してください。認証情報のヘッダーがない場合は HTTP 401 が返され、環境変数の SUPEROPS_* へのフォールバックは行われません。AUTH_MODE=env の場合、署名付きリクエストではプロセス環境のこれらの変数が使われます。

リクエストに署名できないスタンドアロンのローカル利用の場合：

MCP_TRANSPORT=http MCP_ALLOW_INSECURE_DEV=1 npm start

起動時に警告がログに記録され、S2S チェックはスキップされ、127.0.0.1 のみでバインドされます。このポートをループバックの外部に公開しないでください。

API トークンの取得

1. SuperOps.ai にログインします
2. 設定アイコンをクリックし、「My Profile」を選択します
3. 「API token」タブに移動します
4. 「Generate token」をクリックします
5. トークンをコピーし、安全に保管します

Claude Desktop での使用

claude_desktop_config.json に追加します：

{
  "mcpServers": {
    "superops": {
      "command": "npx",
      "args": ["@wyre-ai/superops-mcp"],
      "env": {
        "SUPEROPS_API_TOKEN": "your-api-token",
        "SUPEROPS_SUBDOMAIN": "yourcompany",
        "SUPEROPS_REGION": "us"
      }
    }
  }
}

利用可能なドメインとツール

ナビゲーション

• superops_navigate - ドメインに移動します
• superops_back - メインメニューに戻ります
• superops_test_connection - API 接続をテストします

クライアントドメイン

• superops_clients_list - フィルターを指定してクライアントを一覧表示します
• superops_clients_get - クライアントの詳細を取得します
• superops_clients_search - 名前でクライアントを検索します

チケットドメイン

• superops_tickets_list - フィルターを指定してチケットを一覧表示します
• superops_tickets_get - チケットの詳細を取得します
• superops_tickets_create - 新しいチケットを作成します
• superops_tickets_update - チケットのステータス／担当を更新します
• superops_tickets_add_note - チケットにメモを追加します
• superops_tickets_log_time - チケットに作業時間を記録します

アセットドメイン

• superops_assets_list - アセット／エンドポイントを一覧表示します
• superops_assets_get - アセットの詳細を取得します
• superops_assets_software - ソフトウェアインベントリを取得します
• superops_assets_patches - パッチのステータスを取得します

技術者ドメイン

• superops_technicians_list - 技術者を一覧表示します
• superops_technicians_get - 技術者の詳細を取得します
• superops_technicians_groups - 技術者グループを一覧表示します

カスタムドメイン

• superops_custom_query - カスタム GraphQL クエリを実行します
• superops_custom_mutation - カスタム GraphQL ミューテーションを実行します

使用例

User: What tools are available?
Claude: Use superops_navigate to select a domain...

User: Navigate to tickets
Claude: [calls superops_navigate with domain: "tickets"]
Now in tickets domain. Available tools: superops_tickets_list, superops_tickets_get...

User: Show open high priority tickets
Claude: [calls superops_tickets_list with status: ["Open"], priority: ["High"]]
Here are the open high priority tickets...

Docker

イメージはコンテナ内の 0.0.0.0（MCP_HTTP_HOST）でリッスンし、デフォルトで AUTH_MODE=gateway を使用します。また、CONDUIT_S2S_SECRET に実際のシークレットが設定されていない場合は起動を拒否します。ポートはループバックにバインドして公開してください。ゲートウェイモードでは、SuperOps の認証情報はリクエストごとにヘッダーで渡され、環境からは読み取られません。

docker build -t superops-mcp .
docker run \
  -e CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" \
  -p 127.0.0.1:8080:8080 \
  superops-mcp

Compose は CONDUIT_S2S_SECRET が未設定の場合に起動を拒否し、AUTH_MODE=gateway を設定して、127.0.0.1:8080:8080 を公開します。また、SUPEROPS_API_TOKEN や SUPEROPS_SUBDOMAIN をコンテナに渡しません：

CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" docker compose up

HTTP 認証と同じ方法で /mcp に署名します。ゲートウェイモードの呼び出しでは、ベンダーのヘッダーも送信します：

curl -sS http://127.0.0.1:8080/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "X-Gateway-S2S: t=${TS},v1=${SIG}" \
  -H "X-SuperOps-API-Token: $SUPEROPS_API_TOKEN" \
  -H "X-SuperOps-Subdomain: $SUPEROPS_SUBDOMAIN" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

シングルテナント HTTP（AUTH_MODE=env）でも S2S シークレットが必要です。その後、SUPEROPS_API_TOKEN と SUPEROPS_SUBDOMAIN が使われます。DigitalOcean のワンクリックテンプレートはこのモードです。CONDUIT_S2S_SECRET をランタイムシークレットとして設定してください。

レート制限

SuperOps.ai API のレート制限は、API トークンごとに1分あたり800リクエストです。

ページネーション

SuperOps はカーソルではなく、ページベースのページネーションを使用します。一覧表示ツールは page （1始まり、デフォルトは1）と pageSize（デフォルトは50、最大は100）を受け取り、 page、pageSize、totalCount、hasMore を含む listInfo ブロックを返します。

hasMore は3つの状態を取ります： 次のページがある場合は true、 ない場合は null です。false にはなりません。hasMore === true の間ループするか、 totalCount を基にページを進めてください。hasMore === false になるまでループしても 終了しません。

フィルタリング

フィルターは { attribute, operator, value } のcondition句で、組み合わせて使えます。{ joinOperator: "and" | "or", operands: [ … ] } のように再帰的にネストできます。 本番テナントで検証済みの演算子は次のとおりです。

演算子	値
is, isNot, contains, notContains, startsWith, endsWith	文字列
includes, notIncludes	配列

equals と in は API に拒否されます。includes は値全体に一致し、contains は部分文字列に一致します。そのため、OS プラットフォームを includes: ["Windows"] でフィルタリングしても何も一致しません。SuperOps では "Microsoft Windows 10 Pro" として保存されているためです。

エラーが報告されないため、知っておくべき点が2つあります。

• フィールドの実際の値の範囲外の値でフィルタリングすると、エラーではなく行が0件返されます。結果が空の場合、テナントにデータがないのではなく、値が不正な可能性があります。
• JSON 列（software）そのものを対象にフィルタリングしても、その中のパス（software.name）を対象にしない場合、エラーなしで行が0件返されます。

標準ツールでは表現できないフィルターの条件には、superops_custom_query を使用してください。

スキーマへの準拠

schema/superops.graphql は、SuperOps GraphQL スキーマをベンダーから取り込んだコピーです。

# Authoritative — generated from live introspection
SUPEROPS_API_TOKEN=... SUPEROPS_SUBDOMAIN=... node scripts/fetch-schema.mjs

# No credentials? Falls back to scraping the published API reference
node scripts/fetch-schema.mjs

イントロスペクションを優先してください。コミット済みのスキーマは、すでにイントロスペクションしたものです。公開ドキュメントでは276の型、76のクエリ、63のミューテーションが記載されていますが、ライブ API では404 / 116 / 83です。また、非推奨項目は一切記載されておらず、ライブ環境には存在しない型（FieldType、TicketType）が2つ記載されています。これらのドキュメントに対して検証すると、API が拒否するドキュメントも通過してしまいます。

src/domains/graphql-schema.test.ts は、各 npm test の実行時に src/ 内のすべての GraphQL ドキュメントをこのスキーマに対して検証します。そのため、SuperOps に定義されていないフィールドを参照するクエリがあると、実行時ではなく CI で失敗します。SuperOps API に変更があった場合は、スキーマを再生成してテストを再実行してください。

ライセンス

Apache-2.0

サポート

問題の報告や機能リクエストについては、GitHub リポジトリをご覧ください。