KPN Grexx

kpn-mcp

Grexx がホストする KPN IRMA API 用 MCP サーバー（acceptatie：service-accept.grexx.today）です。MSP のヘルプデスクを対象としています。デフォルトでは、OAuth 2.0 クライアントクレデンシャルを使ったリアルタイム XML が提供されます。SDK はトークンエンドポイントに HTTP Basic を送信します。POST /realtime では Bearer トークンを使用します。

分割 v2 SDK （@modelcontextprotocol/server / /node / /client ^2.0.0-beta.5）を使い、MCP 2026-07-28 仕様に基づいて構築されています。2 世代のクライアントに対応しており、createMcpHandler({ legacy: 'stateless' }) の背後にある共有の McpServerFactory が、2025 世代の initialize ハンドシェイクを使うクライアントと最新の 2026-07-28 エンベロープを使うクライアントの両方に、同じツール一覧を提供します。配布形式は GHCR コンテナのみです（MCPB バンドルはありません）。 クライアントは @wyre-ai/node-kpn（Grexx エクスポート）です。 契約仕様：docs/GREXX.md。

ツール（15 個、フラット構成）

• kpn_grexx_test_connection：SDK が OAuth クライアントクレデンシャルのトークンを発行し、公開参照先住所 1012JS 1（ポートフォリオ All）を使って ZipCodeCheckRequest_V6 のプローブを送信します。成功すると、トークンエンドポイントと POST /realtime が Bearer トークンを受け付けたことを意味します。

• kpn_grexx_zipcode_check：オランダの住所における技術と速度 （ZipCodeCheckRequest_V6 → ZipCodeCheckResponse_V5）。

• kpn_grexx_prequalification：サプライヤーごとの住所および商品タイプの利用可否 （PrequalificationRequest_V2 → PrequalificationResponse_V1）。hasBroadband が true の場合、serviceId または referencePhoneNumber が必要です。

• kpn_grexx_order_data：注文 ID に対応する顧客 ID、商品コード、数量 （OrderDataRequest_V1 → OrderDataResponse_V1）。

• ポータルのリクエスト XSD から作成した、リアルタイムツールがほかに 11 個あります（docs/GREXX.md を参照）： kpn_grexx_carrier_info、kpn_grexx_radius_check、kpn_grexx_ras_check、kpn_grexx_start_line_diagnose、kpn_grexx_customer_data、kpn_grexx_order_summary、 kpn_grexx_get_sim、kpn_grexx_mobile_settings、kpn_grexx_mobile_usage、 kpn_grexx_mobile_orders、kpn_grexx_available_portings。start_line_diagnose は KPN でテストを開始するため、読み取り専用ではなく、再試行も行いません。SIM コードと RadiusCheck の PPP パスワードはマスクされます。

IRMA は XSD の要素順を厳格に適用し、不正なリクエストに HTTP 200 の NinaResponse で応答します。サーバーはその両方に対応しています。キューに登録された書き込みと Proxymodule 通知は公開されません。

KPN_LEGACY_DEVELOPER_API=1 を設定すると、以前の developer.kpn.com ツール 23 個 （障害情報、利用可否、SIM スワップ、MSM）も提供されます。これらはデフォルトの一覧には含まれません。 ツール一覧は docs/DESIGN.md を参照してください。ゲート付きの MSM 書き込みには、引き続き確認が必要です。

認証情報

Grexx のユーザー名とパスワードは、OAuth の client_id と client_secret です（scope=all）。 パートナーポータルからインターフェースのルート URL をコピーしてください（API Gegevens）。デフォルトの ベース URL はありません。acceptatie と本番環境では異なります。

環境変数（env モード）	ゲートウェイヘッダー（AUTH_MODE=gateway）	必須
KPN_GREXX_USERNAME	X-KPN-Grexx-Username	はい
KPN_GREXX_PASSWORD	X-KPN-Grexx-Password	はい
KPN_GREXX_BASE_URL	X-Grexx-Api-Url（任意、接続ごと）	リクエストに X-Grexx-Api-Url と X-Grexx-Token-Url が含まれていない場合は必須。デフォルト値なし。/realtime を含まないインターフェースのルート URL
KPN_GREXX_TOKEN_URL	X-Grexx-Token-Url（任意、接続ごと）	いいえ。デフォルトは https://service-accept.grexx.today/oauth/access_token

例（acceptatie の形式 — API Gegevens にあるインターフェース ID に置き換えてください）：

export KPN_GREXX_USERNAME="..."
export KPN_GREXX_PASSWORD="..."
export KPN_GREXX_BASE_URL="https://service-accept.grexx.today/interfaces/kpn/kpn_partners_acceptatieomgeving/<interface-id>/"
# export KPN_GREXX_TOKEN_URL="https://service-accept.grexx.today/oauth/access_token"

env.example を参照してください。トークンの発行、キャッシュ、Bearer の再試行は @wyre-ai/node-kpn が担います。別のヘッダー名（X-KPN-Grexx-Base-Url など）を使ったベース URL またはトークン URL は 拒否されます（HTTP 400）。

ゲートウェイモードでは、X-KPN-Grexx-Username または X-KPN-Grexx-Password が不足しているリクエストには、MCP ハンドラーの実行前に 401（JSON-RPC エラー -32001）が返されます。環境変数の認証情報にフォールバックすることはありません。

接続ごとの Grexx 環境（WYREAI-525）

ゲートウェイモードでは、Conduit は呼び出しごとに 2 つのヘッダーを送信して、その接続先を本番環境など別の Grexx 環境に指定できます。

ヘッダー	値	例
X-Grexx-Api-Url	ポータルの「API Gegevens」に記載されたインターフェースのルート。/realtime は付けません	https://service.grexx.today/interfaces/kpn/<interface-name>/<interface-id>
X-Grexx-Token-Url	OAuth トークンエンドポイント	https://service.grexx.today/oauth/access_token

• 両方指定するか、どちらも指定しないでください。 両方が存在しないか空の場合、サイドカーは KPN_GREXX_BASE_URL と KPN_GREXX_TOKEN_URL を使用します。認証情報ヘッダーのみが送信された場合も同様です。KPN_GREXX_BASE_URL にデフォルト値はなく、この場合は必須です。KPN_GREXX_TOKEN_URL は省略可能で、省略時はアクセプタンス環境のトークンエンドポイント（https://service-accept.grexx.today/oauth/access_token）が使用されます。URL ヘッダーが片方だけ指定されている場合は HTTP 400 になります。
• X-KPN-Grexx-Username／X-KPN-Grexx-Password と併せて指定した場合にのみ有効です。これらのヘッダーがない場合、リクエストは 401 になります。
• スキームとオーソリティ： https: のみ、ポートは 443 のみです。ユーザー情報、クエリー文字列、フラグメントは指定できません。
• ホストの完全一致許可リスト（@wyre-ai/node-kpn の GREXX_ALLOWED_HOSTS）：service.grexx.today と service-accept.grexx.today です。*.grexx.today のワイルドカードは使用できません。IP リテラルは一致しません。
• パス： トークン URL のパスは /oauth/access_token と完全一致する必要があります。API URL のパスは /interfaces/kpn/ で始まる必要があり、/realtime を付けないインターフェースのルートを指定します（SDK が追加します）。
• いずれかの条件に違反すると、HTTP 400（JSON-RPC -32600）になります。メッセージに URL が含まれることはありません。
• プライベート IP のブロック： URL ヘッダーがある場合、SDK はトークンの発行と /realtime への POST のたびにホストを解決します。また、ソケット接続時にも再度解決し（ガード付き Agent を使用する undici の fetch）、プライベート、ループバック、リンクローカル（169.254.169.254 を含む）、CGNAT、予約済み／ベンチマーク用、ULA、メタデータの各アドレスへのアクセスを拒否します。
• リダイレクトは拒否されます： 3xx はすべて呼び出しの失敗になります。
• その他の URL ヘッダー名（X-KPN-Grexx-Base-Url など）は引き続き HTTP 400 で拒否されます。

HTTP 認証

MCP_TRANSPORT=http の場合、CONDUIT_S2S_SECRET は必須です。空の場合、プロセスはエラーをログに記録して、ゼロ以外の終了コードで終了します。シークレットが出力されることはありません。既知のプレースホルダー（changeme、change-me、secret、placeholder、example、your-secret、your-s2s-secret、s2s-secret、replace-me、replace-with-a-real-secret）も、MCP_ALLOW_INSECURE_DEV=1 が設定されている場合を含め、同様に拒否されます。

MCP_ALLOW_INSECURE_DEV=1 はローカル開発専用です。プロセスは警告をログに記録し、X-Gateway-S2S の確認を行わず、127.0.0.1 のみでリッスンします。このモードでは、ループバック以外の MCP_HTTP_HOST（0.0.0.0 を含む）は無視され、その上書きがログに記録されます。

実際のシークレットが設定されている場合は、MCP_HTTP_HOST が有効になります。未設定の場合、バインド先は 0.0.0.0 のままです。シークレットを使うプロセスをループバックに限定するには、127.0.0.1 を設定します。コンテナーイメージでは 0.0.0.0 と AUTH_MODE=gateway が設定されています。

実際のシークレットがある場合、/health と /healthz を除くすべてのリクエストに、次のヘッダーを含める必要があります。

X-Gateway-S2S: t=<unix seconds>,v1=<hex hmac-sha256>

v1 は、文字列 t=<unix seconds>（ヘッダーの先頭と同じ t= プレフィックスを含む）の HMAC-SHA256 です。キーには CONDUIT_S2S_SECRET を使用し、16 進数でエンコードします。タイムスタンプはサーバーの時刻から 300 秒以内である必要があります。ヘッダーがない場合、または無効な場合は 401 になります。/health と /healthz は引き続き認証不要で、認証情報も読み取りません。stdio トランスポートでは CONDUIT_S2S_SECRET を使用しません。

# sign "t=$NOW" with the gateway-provisioned secret
NOW=$(date +%s)
SIG=$(printf 't=%s' "$NOW" | openssl dgst -sha256 -hmac "$CONDUIT_S2S_SECRET" | awk '{print $NF}')
curl -sS -D- http://127.0.0.1:8080/mcp \
  -H "X-Gateway-S2S: t=${NOW},v1=${SIG}" \
  -H "X-KPN-Grexx-Username: ..." \
  -H "X-KPN-Grexx-Password: ..." \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

SDK の依存関係

Grexx クライアントは /legacy ではなく、@wyre-ai/node-kpn（パッケージのルート）からインポートしてください。

依存関係は公開済みの範囲 ^2.2.0 です（接続ごとの URL と SSRF ガードは node-kpn#6、Prequalification と OrderData は node-kpn#5、タグ v2.1.0）。トークンの発行には、node-kpn#4 の HTTP Basic の動作を使用します。/legacy は、KPN_LEGACY_DEVELOPER_API=1 の場合に限り、developer.kpn.com クライアントとして引き続き使用できます。このサーバーが Grexx トークンを発行することはありません。

実行

export NODE_AUTH_TOKEN=$(gh auth token)   # GitHub Packages auth for @wyre-ai/*
npm install
npm run build
node dist/index.js                        # stdio (default)
# HTTP refuses to start until CONDUIT_S2S_SECRET is a real secret
CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" MCP_TRANSPORT=http node dist/index.js
# Local HTTP only, without a service-to-service secret (always binds 127.0.0.1)
MCP_ALLOW_INSECURE_DEV=1 MCP_TRANSPORT=http node dist/index.js
npm run smoke                             # both protocol eras serve the same Grexx tools

Docker（fleet の仕様により linux/amd64）。イメージはコンテナー内の 0.0.0.0 でリッスンし、デフォルトで AUTH_MODE=gateway を使用します。ポートをループバックに公開し、S2S シークレットを渡してください。Grexx のユーザー名とパスワードは、リクエストごとにヘッダーとして渡されます。呼び出し元から指定された URL は拒否されるため、KPN_GREXX_BASE_URL は環境変数に設定したままにしてください。

docker build --platform linux/amd64 --build-arg GITHUB_TOKEN=$(gh auth token) -t kpn-mcp .
docker run \
  -e CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" \
  -e KPN_GREXX_BASE_URL="https://service-accept.grexx.today/interfaces/kpn/kpn_partners_acceptatieomgeving/<interface-id>/" \
  -p 127.0.0.1:8080:8080 \
  kpn-mcp

CONDUIT_S2S_SECRET が設定されていない場合、Compose は起動を拒否します。127.0.0.1:8080:8080 を公開しますが、KPN_GREXX_USERNAME や KPN_GREXX_PASSWORD は注入しません。

CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" \
KPN_GREXX_BASE_URL="https://service-accept.grexx.today/interfaces/kpn/kpn_partners_acceptatieomgeving/<interface-id>/" \
GITHUB_TOKEN=$(gh auth token) \
docker compose up --build

シングルテナント HTTP（AUTH_MODE=env）でも S2S シークレットが必要です。そのうえで、KPN_GREXX_USERNAME と KPN_GREXX_PASSWORD を使用します。

docker run \
  -e CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" \
  -e AUTH_MODE=env \
  -e KPN_GREXX_USERNAME=... \
  -e KPN_GREXX_PASSWORD=... \
  -e KPN_GREXX_BASE_URL=... \
  -p 127.0.0.1:8080:8080 \
  kpn-mcp

/health は簡易的な稼働確認プローブです。Grexx への呼び出しや認証情報の読み取りは行いません。

従来の developer.kpn.com ツール

KPN_LEGACY_DEVELOPER_API=1 を設定すると、プロセスは kpn_test_connection、kpn_disturbances_check、kpn_availability_check、kpn_sim_swap_get_date と、MSM の読み取り／書き込みツールも登録します。認証情報は KPN_CLIENT_ID／KPN_CLIENT_SECRET（ゲートウェイの場合は X-KPN-Client-Id／X-KPN-Client-Secret）と、任意の MSM 認証情報ペアです。KPN_BASE_URL は環境変数にのみ設定してください。MSM の認証情報が片方だけ設定されている場合は拒否されます。MSM の書き込みは引き続き注文を作成し、再試行されません。また、確認が必要です（クライアントで確認を求められない場合は confirm_destructive_action を使用してください）。

ここに反映されているベンダー固有の仕様

• OAuth client_credentials、scope=all。SDK はトークンエンドポイントへのリクエストに HTTP Basic を使用し、その後 POST /realtime では Bearer を使用します（Content-Type: text/xml）。 プレーン XML であり、SOAP エンベロープはありません。POST /realtime では Basic Auth を送信しません。
• このサーバーはトークンの発行を GrexxClient に委ねています。GrexxClient は最初に HTTP Basic を送信し、HTTP 400／401 と invalid_client が返された場合は、フォーム本文の client_id／client_secret にフォールバックすることがあります。
• トークンエンドポイントへのリクエストは再試行されず、Bearer なしで呼び出すこともありません。HTTP 401 の場合、SDK 内でトークンを一度だけ再発行します。
• IRMA コード 108 と HTTP 429 はレート制限です。コード 102 は IP 許可リストによる拒否です。
• 成功コードには Success（ZipCodeCheck で acceptatie が返した値）が含まれます。

ライセンス

Apache-2.0 © WYRE Technology