KPN Grexx

kpn-mcp

由 Grexx 托管的 KPN IRMA API MCP 服务（验收环境：service-accept.grexx.today），面向 MSP 帮助台。默认接口通过 OAuth 2.0 客户端凭据使用实时 XML。SDK 向令牌端点发送 HTTP Basic。POST /realtime 使用 Bearer 令牌。

基于 MCP 2026-07-28 规范，通过拆分版 v2 SDK （@modelcontextprotocol/server / /node / /client ^2.0.0-beta.5）构建，并支持双时代 服务：一个共享的 McpServerFactory 位于 createMcpHandler({ legacy: 'stateless' }) 后， 同时响应 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）。

• 另外 11 个根据门户请求 XSD 构建的实时工具（参见 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，也可提供以前的 23 个 developer.kpn.com 工具 （故障、可用性、SIM 换卡、MSM）。这些工具不会出现在默认列表中。 工具目录参见 docs/DESIGN.md。受限的 MSM 写入仍需确认。

凭据

Grexx 用户名和密码分别作为 OAuth client_id 和 client_secret（scope=all）。 从合作伙伴门户（API Gegevens）复制接口根 URL。没有默认基础 URL：验收环境和生产环境不同。

环境变量（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。无默认值。接口根 URL，不含 /realtime
KPN_GREXX_TOKEN_URL	X-Grexx-Token-Url（可选，每个连接单独设置）	否。默认值为 https://service-accept.grexx.today/oauth/access_token

示例（验收环境格式——请替换为 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 处理。使用任何其他标头名称的基础 URL 或令牌 URL（X-KPN-Grexx-Base-Url 等） 都会被拒绝（HTTP 400）。

在网关模式下，如果请求缺少 X-KPN-Grexx-Username 或 X-KPN-Grexx-Password，会在 MCP 处理程序运行前 返回 401（JSON-RPC 错误 -32001）。请求绝不会回退到环境凭据。

每连接 Grexx 环境（WYREAI-525）

在网关模式下，Conduit 可在每次调用时发送两个标头，将该连接指向另一个 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

• 必须同时提供或都不提供。 两者均缺失或为空时，sidecar 使用 KPN_GREXX_BASE_URL 和 KPN_GREXX_TOKEN_URL；即使发送了凭据标头，但未发送 URL 标头，也会如此。KPN_GREXX_BASE_URL 没有默认值，因此此时必须设置；KPN_GREXX_TOKEN_URL 是可选的，默认使用 acceptatie 令牌端点（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 请求前解析主机，并在套接字连接时再次解析（使用带防护 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 作为密钥，并以十六进制编码。时间戳与服务器时钟的偏差必须在 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 依赖

从 @wyre-ai/node-kpn（包根目录）导入 Grexx 客户端，不要从 /legacy 导入。

依赖使用已发布的版本范围 ^2.2.0（node-kpn#6 提供每连接 URL 和 SSRF 防护；Prequalification 和 OrderData 来自 node-kpn#5，标签为 v2.1.0）。令牌获取采用 node-kpn#4 中的 HTTP Basic 行为。/legacy 仍是 developer.kpn.com 客户端，仅用于 KPN_LEGACY_DEVELOPER_API=1。 此服务不会获取 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 law 使用 linux/amd64）。镜像在容器内监听 0.0.0.0，默认使用 AUTH_MODE=gateway。将端口发布到 loopback，并传入 S2S 密钥。每个请求都会通过标头传入 Grexx 用户名和密码。KPN_GREXX_BASE_URL 保留在环境变量中，因为调用方提供的 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，也不会读取凭据。

Legacy 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 处理；它会先发送 HTTP Basic，在遇到 HTTP 400/401 invalid_client 后可能回退为在表单正文中发送 client_id / client_secret。
• 不会在令牌端点调用中重试并省略 Bearer。HTTP 401 会在 SDK 内部触发一次重新签发令牌。
• IRMA 代码 108 和 HTTP 429 表示速率限制。代码 102 表示 IP 允许列表拒绝。
• 成功代码包括 Success（acceptatie 为 ZipCodeCheck 返回的代码）。

许可证

Apache-2.0 © WYRE Technology