Printix

Printix MCP サーバー

Printix の Cloud Print API（現在は Tungsten Automation の一部）を利用する MCP サーバーです。AI アシスタントや WYRE Conduit ゲートウェイ向けに、プリンター／キュー、サイト、ワークステーション、および読み取り専用のユーザー／グループ検索を提供します。

認証

Printix は、Printix Administrator ダッシュボードから取得する client_id／client_secret のペアを テナントごとに発行します。WYRE 全体で共通の統合用認証情報はありません。MSP が管理する顧客テナントごとにそれぞれのペアが必要で、各テナントで一度に有効にできるペアは 1 つだけです（新しいペアを発行すると、以前のペアは無効になります）。

このペアは、POST https://auth.printix.net/oauth/token（grant_type=client_credentials、client_id／client_secret はフォーム本文に指定）を使って、有効期間の短い（約 1 時間）OAuth アクセストークンと交換されます。このサーバーは交換を内部で処理し、トークンの期限切れまたは拒否時には同じ方法で再認証します。Printix はリフレッシュトークンをサポートしていません（2024-12-17 に削除。ドキュメントでは従来のリフレッシュトークン方式を「標準的な OAuth2 ではない」と説明しています）。

呼び出し元が指定する必要があるのは、以下の有効期間の長い 2 つの値だけです。有効期間の短いアクセストークンは不要です。

Printix の Cloud Print API にあるすべてのリソースは、テナントパス（/cloudprint/tenants/{tenantId}/...）の下にあります。このサーバーは、API ルート（GET /cloudprint。アクセス可能なテナントへのリンク一覧を返すと説明されている、ドキュメント記載の HATEOAS エントリーポイント）を呼び出して、認証情報のペアごとにテナント ID を一度解決し、アクセストークンと一緒にキャッシュします。

設定

.env.example をコピーし、以下の変数を設定してください。

環境変数	説明
PRINTIX_CLIENT_ID	Printix Administrator ダッシュボードで取得したクライアント ID です。stdio と、AUTH_MODE=env の場合の HTTP で使用されます。
PRINTIX_CLIENT_SECRET	クライアント ID に対応するクライアントシークレットです。stdio と、AUTH_MODE=env の場合の HTTP で使用されます。
MCP_TRANSPORT	stdio（デフォルト）または http です。
AUTH_MODE	env（デフォルト。PRINTIX_* を読み込みます）または gateway（認証情報はリクエストごとに X-Printix-Client-ID と X-Printix-Client-Secret で渡され、環境変数へのフォールバックは行われません）です。Docker イメージと Compose ファイルでは gateway がデフォルトです。
CONDUIT_S2S_SECRET	HTTP トランスポートの起動に必須です。/mcp の X-Gateway-S2S と照合する HMAC シークレットです。openssl rand -hex 32 で生成してください。空の場合、または既知のプレースホルダー（例：replace-with-a-real-secret）の場合、プロセスはエラーをログに記録して、ゼロ以外の終了コードで終了します。この値がログに記録されることはありません。未設定の場合、Compose は起動しません。
MCP_ALLOW_INSECURE_DEV	CONDUIT_S2S_SECRET なしで HTTP を起動するには、ローカル開発時に限り 1 を設定してください。プロセスは警告をログに記録し、X-Gateway-S2S を検証せず、127.0.0.1 のみでバインドします。ループバック以外の MCP_HTTP_HOST（0.0.0.0 を含む）は無視され、上書きがログに記録されます。既知のプレースホルダーシークレットは引き続き拒否されます。
MCP_HTTP_HOST	有効な CONDUIT_S2S_SECRET が設定されている場合のバインドアドレスです。未設定時のデフォルトは 127.0.0.1 です。コンテナーイメージでは 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 を含める必要があります。チェック処理は src/s2s-verify.ts の verifyS2sHeader です。ヘッダー値は t=<unix seconds>,v1=<hex> で、hex は CONDUIT_S2S_SECRET をキーとして、文字列 t=<unix seconds> そのものに対して計算した HMAC-SHA256（64 文字の小文字の 16 進数）です。タイムスタンプはサーバーの時計から 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}" \
  -H 'X-Printix-Client-ID: your-client-id' \
  -H 'X-Printix-Client-Secret: your-client-secret' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

AUTH_MODE=gateway の場合、/mcp には X-Printix-Client-ID と X-Printix-Client-Secret も必要です。これらのヘッダーのみが、そのリクエストの認証情報ソースになります。いずれかのヘッダーがないリクエストには 401 を返し、プロセス環境内の PRINTIX_CLIENT_ID／PRINTIX_CLIENT_SECRET にはフォールバックしません。

AUTH_MODE=env（シングルテナント HTTP）の場合も、/mcp には有効な X-Gateway-S2S ヘッダーが必要です。ベンダーの認証情報は PRINTIX_CLIENT_ID と PRINTIX_CLIENT_SECRET から取得します。

ツール

テナント

• printix_get_tenant - この認証情報のペアが対象とするテナント（テナント ID と API ルートリンク）を取得します。

プリンター／キュー

• printix_list_printers - 必要に応じてフィルターとページ指定を行い、印刷キュー／プリンターを一覧表示します。
• printix_get_printer - 個別のプリンター／キューと、そのプロパティ／機能を取得します。

サイト

• printix_list_sites - サイト（物理的な場所）をページ指定して一覧表示します。
• printix_get_site - 個別のサイトの詳細を取得します。

ワークステーション

• printix_list_workstations - ワークステーションの監視データをページ指定して一覧表示します。
• printix_get_workstation - 個別のワークステーションの詳細を取得します。

ユーザー（読み取り専用）

• printix_list_users - 必要に応じてクエリ／ロールでフィルターを行い、ユーザーをページ指定して一覧表示します。
• printix_get_user - ID で個別のユーザーを検索します。

グループ（読み取り専用）

• printix_list_groups - グループをページ指定して一覧表示／検索します。
• printix_get_group - 個別のグループの詳細を取得します。

対象範囲

これは v1 の機能範囲であり、Printix の Cloud Print API における MSP 向けのフリート監視／管理に関する価値を対象としています。エンドユーザーの印刷ジョブのワークフローは対象外です。現時点で明示的に対象外とする機能は以下のとおりです。

• Print Jobs（送信／取得／削除）- エンドユーザー向けの印刷ワークフローであり、MSP 管理向けの機能ではありません。
• Cards（登録／検索／削除）- 特定の認証カード ID 機能です。
• Networks と SNMP Configurations - プロビジョニングの比重が大きく、書き込み操作のリスクも高い機能です。
• ユーザーとグループの変更（作成／削除）- ライセンスやアクセス権の削除など、実際のアカウント管理に影響します。どちらも読み取り（一覧表示／取得）のみを公開しています。今後、別途慎重に判断する価値があります。

MSP のワークフローに明確なニーズが生じた場合、後続の機能として追加できます。

このサーバーは、日常的なフリート管理ではなくテナントのプロビジョニングを対象とする、より範囲の狭い Partner API（printix.bitbucket.io）ではなく、Cloud Print API（printix.github.io）を対象に構築されています。

開発

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

# HTTP refuses to start until CONDUIT_S2S_SECRET is set
CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" npm run start:http

Docker

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

# Generate the secret first: openssl rand -hex 32
docker build -t printix-mcp .
docker run \
  -e CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" \
  -p 127.0.0.1:8080:8080 \
  printix-mcp

CONDUIT_S2S_SECRET が未設定の場合、Compose は起動を拒否します。チェックイン済みのサービスは gateway モードです。PRINTIX_CLIENT_ID や PRINTIX_CLIENT_SECRET を設定せず、env_file も使用しないため、プロジェクトの .env から静的なベンダー認証情報がコンテナーに渡されることはありません。127.0.0.1:8080:8080 でポートを公開します。

CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" docker compose up

シングルテナント HTTP（AUTH_MODE=env）でも S2S シークレットが必要で、その後 PRINTIX_CLIENT_ID と PRINTIX_CLIENT_SECRET を使用します。これは gateway の Compose サービスでは使用しないでください。

docker run \
  -e CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" \
  -e AUTH_MODE=env \
  -e PRINTIX_CLIENT_ID=your-client-id \
  -e PRINTIX_CLIENT_SECRET=your-client-secret \
  -p 127.0.0.1:8080:8080 \
  printix-mcp

シークレットを設定しないローカル HTTP は、開発専用です。127.0.0.1 のみでバインドし（より広い範囲を指定する MCP_HTTP_HOST は上書きされ、その旨がログに記録されます）、警告をログに出力します。

MCP_ALLOW_INSECURE_DEV=1 npm run start:http