Alloy Navigator

Alloy Navigator MCP サーバー

Alloy Navigator の REST API 向け MCP サーバーです。IT 資産管理、ITSM、ネットワークインベントリのデータ（インシデント、作業指示、資産、ソフトウェアカタログ、消耗品など）を AI アシスタントおよび WYRE Conduit ゲートウェイで利用できます。

認証

Alloy Navigator は OAuth2 の client_credentials グラントを使用して、サードパーティアプリケーションを認証します。アプリケーションアカウントは Alloy Navigator Settings App の Services > API > Applications で登録し、そこで client ID と client secret が発行されます。このコネクターは、それらを <base URL>/api/token に POST してベアラーアクセストークンと交換し、その後のすべてのリクエストで Authorization: Bearer <token> を送信します。Alloy Navigator の公式ドキュメントによると、アクセストークンの有効期間は 8 時間です。このコネクターは認証情報の組み合わせごとにトークンをキャッシュし、有効期限が近づくと透過的に再認証します（src/auth.ts を参照）。

Alloy Navigator には固定のホスト型 API エンドポイントはありません。各インスタンス（オンプレミス、または顧客独自のセルフホスト型クラウドテナント）は、それぞれ独自のベース URL にデプロイされるため、このコネクターにはベース URL、クライアント ID、クライアントシークレットの3つすべてが必要です。ゲートウェイモードでは、リクエストごとに X-Alloy-Base-Url、X-Alloy-Client-Id、X-Alloy-Client-Secret ヘッダーで3つすべてを受け取ります。ローカル／stdio モードでは、ALLOY_BASE_URL、ALLOY_CLIENT_ID、ALLOY_CLIENT_SECRET から一度読み込みます。

Alloy Navigator の API モジュール（および、このコネクター固有のアプリケーションアカウントのグラントタイプ）を使用するには、対象インスタンスに API Module がインストールされ、有効になっている必要があります。client_credentials リクエストが認証エラーではなく接続エラーまたは 404 エラーを返す場合は、Alloy Navigator の公式インストールガイドの「Installing and Configuring the API Module」を参照してください。

認証情報のスコープ

ベンダーのドキュメントに記載されていますが、実際のアカウントで独自に検証したものではありません（その理由については、以下の「検証」を参照してください）。Alloy Navigator の API User's Guide では、アプリケーションアカウントは「サインイン中のユーザーがいない状態で実行されるサードパーティアプリケーション」が使用するアカウントとして説明されており、通常の技術者アカウント（ユーザー名／パスワード）とは区別されています。ただし、Alloy Navigator 独自のセキュリティ／ロール設定で、そのアカウントが閲覧を許可されているオブジェクトクラスやフィールドよりも狭く、アプリケーションアカウントの読み取りアクセスを制限する方法は記載されていません。実際には、読み取り専用の保証は認証情報自体ではなく、このコネクターのツール構成（GET のみで、ワークフローアクションを実行しない）によって担保されます。Alloy Navigator 独自のワークフローアクションモデルでは、技術的には「読み取り」の API 呼び出しであっても、他の場所で書き込み／ワークフローアクションの権限を付与されている可能性のある同一アカウントを介して実行されるためです。顧客は、このコネクター専用の最小権限のアプリケーションアカウントを作成してください。これは、API キーが作成者アカウントの全権限を引き継ぐ、このフリート内の他のベンダー（例：PRTG）が推奨する運用と同じです。

検証

このコネクターは、二次資料や命名規則ではなく、Alloy Navigator の公式 API User's Guide（docs.alloysoftware.com/alloynavigator/docs/api-userguide/）に直接基づいて構築されています。以下の各ツールは、実際にドキュメント化された GET 操作に対応しており、正確なクエリパラメーターとレスポンス形式は、ガイド内の実例と照合して検証されています（照合元の例については、src/client.ts にある各ツールの JSDoc を参照してください）。一方、実際の Alloy Navigator インスタンスを使った独自検証は行っていません。Alloy Navigator は、公開されたセルフサービス型のトライアル環境やサンドボックス環境を提供しておらず、環境の用意には、このビルド環境では完了できなかった実際の営業／ライセンス契約が必要です。これはビルド環境の制約であり、既存のライセンスを持つ顧客に対するベンダー側の承認要件ではありません。

設定

環境変数	説明
ALLOY_BASE_URL	Alloy Navigator サーバーのベース URL。例：https://alloy.example.com
ALLOY_CLIENT_ID	アプリケーションアカウントのクライアント ID。Settings App > Services > API > Applications で発行されます。
ALLOY_CLIENT_SECRET	アプリケーションアカウントのクライアントシークレット。クライアント ID とともに発行されます。
MCP_TRANSPORT	stdio（デフォルト）または http。
AUTH_MODE	env（デフォルト。上記の変数を読み込みます）または gateway（Conduit ゲートウェイによって挿入される X-Alloy-Base-Url / X-Alloy-Client-Id / X-Alloy-Client-Secret ヘッダーを介して、リクエストごとに認証情報を受け取ります）。Docker イメージと Compose ファイルのデフォルトは gateway です。ゲートウェイモードでは、これらのヘッダーのいずれかが欠落していると /mcp は 401 を返し、ALLOY_* へのフォールバックは行いません。
CONDUIT_S2S_SECRET	HTTP で必須です。サービス間シークレットです。空の場合、または既知のプレースホルダー（changeme、secret、placeholder、your-s2s-secret、replace-with-a-real-secret、および src/http.ts 内の同じリスト）の場合、HTTP サーバーはエラーをログに記録して 0 以外の終了コードで終了します。設定されていない場合、Compose は起動しません。実際の値をコミットしないでください。プロセスがこの値をログに記録することはありません。
MCP_ALLOW_INSECURE_DEV	CONDUIT_S2S_SECRET なしで HTTP を起動する場合に限り、ローカル開発用として 1 に設定します。プロセスは警告をログに記録し、X-Gateway-S2S を省略して、127.0.0.1 のみでリッスンします。より広い範囲を指定する MCP_HTTP_HOST は上書きされます。既知のプレースホルダーシークレットは引き続き拒否されます。
MCP_HTTP_HOST	MCP_TRANSPORT=http の場合のバインドアドレス。デフォルトは 127.0.0.1 です。CONDUIT_S2S_SECRET が設定されている場合、この値が適用されます。0.0.0.0 も指定できます。コンテナーイメージでは 0.0.0.0 が設定されています。シークレットがない場合、リスナーは 127.0.0.1 のみです。
MCP_HTTP_PORT	HTTP ポート。デフォルトは 8080 です。
LOG_LEVEL	debug | info（デフォルト）| warn | error。

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

HTTP 認証

MCP_TRANSPORT=http で CONDUIT_S2S_SECRET が設定されている場合、すべての /mcp リクエストに X-Gateway-S2S を含める必要があります。ヘッダーがないか無効な場合、ベンダーの認証情報が読み取られる前に 401 が返されます。

このヘッダーはシークレットのコピーではなく、HMAC の証明です。

t=<unix seconds>,v1=<hex hmac-sha256>

<hex hmac-sha256> は、ASCII 文字列 t=<unix seconds>（同じ t= プレフィックスと同じ 10 進数のタイムスタンプ）の HMAC-SHA256 です。キーには CONDUIT_S2S_SECRET を使用し、小文字の 16 進数でエンコードします。タイムスタンプはサーバーの時計と 300 秒以内の差である必要があります。

import { createHmac } from 'node:crypto';

const secret = process.env.CONDUIT_S2S_SECRET;
const t = Math.floor(Date.now() / 1000);
const v1 = createHmac('sha256', secret).update(`t=${t}`).digest('hex');
const xGatewayS2s = `t=${t},v1=${v1}`;

AUTH_MODE=gateway の場合、/mcp には X-Alloy-Base-Url、X-Alloy-Client-Id、X-Alloy-Client-Secret も必要です。そのリクエストの認証情報源は、これらのヘッダーのみです。

await fetch('http://127.0.0.1:8080/mcp', {
  method: 'POST',
  headers: {
    'content-type': 'application/json',
    accept: 'application/json, text/event-stream',
    'x-gateway-s2s': xGatewayS2s,
    'x-alloy-base-url': 'https://alloy.example.com',
    'x-alloy-client-id': 'application-client-id',
    'x-alloy-client-secret': 'application-client-secret',
  },
  body: JSON.stringify({ jsonrpc: '2.0', id: 1, method: 'tools/list' }),
});

ツール

Alloy Navigator の API は、オブジェクトの種類ごとに固定された REST パスを持つのではなく、クラス汎用です（たとえば PRTG の /devices、/sensors などとは異なります）。単一のオブジェクトクラスパラメーター（Incidents、Computers、Work Orders、Consumables、SoftwareCatalog、Purchase Order Items など）で、クエリ対象を選択します。このコネクターの 4 つのツールは、Alloy Navigator 自身の API に存在しないクラスごとのツールを新たに作るのではなく、この構造を忠実に反映しています。

オブジェクト

• alloy_list_objects - 指定したオブジェクトクラスのオブジェクトを、フィールド選択、並べ替え、ページング、フリーテキスト検索、フィールドごとのフィルターを使って一覧表示または検索します。
• alloy_get_object - OID（チケット番号）またはデータベースレコード GUID を指定して、単一オブジェクトのすべてのフィールドを取得します。

アクティビティ

• alloy_get_object_activities - 単一オブジェクトに記録されたアクティビティ／履歴ログのエントリー（ステータス変更、割り当て変更、システムメモ）を取得します。

ディクショナリー

• alloy_get_dictionary - オブジェクトクラスのフィールドで使用できる参照値／分類値（例：有効な Status または Types の値）を取得します。

対象範囲

これは意図的に範囲を絞った読み取り専用の v1 サーフェスです。Alloy Navigator の汎用オブジェクトのクエリ、単一オブジェクトの読み取り、アクティビティ／履歴の読み取り、参照値の検索のみを対象とする 4 つの GET 操作で、それ以外は扱いません。 Alloy Navigator API ユーザーズガイドには、ワークフローアクションを中心とする、これより大幅に広いサーフェスが記載されています（Alloy Navigator ではオブジェクトを直接作成または更新せず、すべての変更はオブジェクトに対する名前付きワークフローアクションとして実行されます）。このコネクターは見落としではなく、設計上、これらをすべて対象外にしています。

対象外（オブジェクトの作成と変更 — Alloy Navigator の API モデルでは、すべての変更がワークフローアクションを通じて実行されます）— 実装しません： POST /object/<oid>/action/<actionId> — ワークフローアクションの実行（Alloy Navigator の「オブジェクトの作成」ドキュメントで、新しいインシデント、作業指示、資産、その他あらゆるオブジェクトの作成に使うと説明されている仕組み）は、定義上書き込みであり、完全に対象外です。これには、顧客のインスタンスで無害そうな名前（例：「確認」や「クローズ」）が付けられているワークフローアクションも含まれます。このコネクターには、読み取りを目的とするアクションと実際に状態を変更するアクションを見分ける方法がないため、いずれも公開しません。

対象外（冗長な POST ベースの取得）— 実装しません： Alloy Navigator のガイドには、オブジェクト一覧およびオブジェクトアクティビティの GET エンドポイント（POST /<objectClass>、POST /Activities/<oid>）の POST 版も記載されています。これは、呼び出し側が URL を手動で組み立てる際に、URL クエリの長さ制限を回避するためのものです。このコネクターでは、手入力の URL ではなく構造化されたツール引数を使って、すべてのリクエストをサーバー側で構築します。そのため、POST 版が回避する長さ制限はここでは適用されません。これを実装しても、動作が同じで、独自の読み取り／書き込みの区別もないコードパスがもう 1 つ増えるだけなので、対象範囲の境界ではなく、冗長であることを理由に除外しています。

対象外（ユーザー／セッション／アプリケーションの管理 — ITSM／資産データではなく、ID と認証情報の管理）— 実装しません： 技術者（ユーザー名／パスワード）認証グラント（grant_type=password を指定する POST /api/token）。このコネクターでは、無人のサービス統合を目的とする形式のアプリケーションアカウント用 client_credentials グラントのみを使用します。また、アプリケーションアカウント、技術者アカウント、またはセッション自体を管理するエンドポイントも対象外です。

対象外（ITSM／資産データの範囲外）— 実装しません： GET /api/v2/GetAppConfig — 登録済みのモバイルスキャナーアプリケーション（Settings App > Services > Mobile Applications）の設定です。IT 資産／ITSM レコードデータとは無関係であり、そもそも顧客がモバイルアプリを登録している必要があります。

需要があれば、範囲を慎重に決定したうえで、既定ではなく、後続対応として追加できます。

開発

npm install
npm run build
npm test
npm run lint   # tsc --noEmit

Docker

イメージはコンテナー内の 0.0.0.0（MCP_HTTP_HOST）でリッスンし、既定では AUTH_MODE=gateway になります。ポートをループバックに公開し、S2S シークレットを渡してください。ゲートウェイモードでは、Alloy Navigator の認証情報はリクエストごとに X-Alloy-* ヘッダーで渡されます。イメージは認証情報を環境から読み取りません。

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

Compose は CONDUIT_S2S_SECRET が未設定の場合、起動を拒否します。また、AUTH_MODE=gateway を設定し、127.0.0.1:8080:8080 を公開しますが、ALLOY_* 変数は渡しません。

CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" docker compose up

単一テナントの HTTP（AUTH_MODE=env）でも S2S シークレットが必要です。その後、ALLOY_BASE_URL、ALLOY_CLIENT_ID、ALLOY_CLIENT_SECRET を使用します。

docker run \
  -e CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" \
  -e AUTH_MODE=env \
  -e ALLOY_BASE_URL=https://alloy.example.com \
  -e ALLOY_CLIENT_ID=your-client-id \
  -e ALLOY_CLIENT_SECRET=your-client-secret \
  -p 127.0.0.1:8080:8080 \
  alloy-navigator-mcp

シークレットなしのローカル HTTP は、開発用途に限られます。127.0.0.1 にバインドし、警告をログに記録します。MCP_HTTP_HOST にループバック以外の値を指定した場合は、127.0.0.1 に上書きされます。

MCP_TRANSPORT=http MCP_ALLOW_INSECURE_DEV=1 npm run start:http