Dicker Data

Dicker Data MCP 服务

面向 AI 助手和 WYRE Conduit 网关的 MCP 服务，用于访问 Dicker Data 的 B2B 合作伙伴／经销商 REST API，查询价格和库存、下单和跟踪订单，以及查询发票。

身份验证

Dicker Data 不提供自助 API 注册。请联系 [email protected] 或 [email protected] 申请访问权限，以获取一组长期有效的 AccountCode 和 AccessToken。

每次实际 API 调用还需要一个短期有效的 AccessKey，通过 POST /api/AccessKeyRequest 交换 AccountCode／AccessToken 获取。此服务会在内部处理该交换（并在密钥过期时刷新），调用方只需提供长期有效的凭据。

配置

复制 .env.example，并设置以下变量。

变量	必填	描述
DICKERDATA_ACCOUNT_CODE	用于 stdio 和 AUTH_MODE=env	Dicker Data 签发的长期有效账户代码。网关模式不会读取此变量。
DICKERDATA_ACCESS_TOKEN	用于 stdio 和 AUTH_MODE=env	Dicker Data 签发的长期有效访问令牌。网关模式不会读取此变量。
MCP_TRANSPORT	否	stdio（默认）或 http。
AUTH_MODE	否	gateway（Docker 镜像和 Compose 的默认值）或 env。网关模式要求每个 /mcp 请求都包含 X-DickerData-Account-Code 和 X-DickerData-Access-Token，且绝不会回退到 DICKERDATA_*。env 模式会在 S2S 身份验证成功后使用这些变量。
CONDUIT_S2S_SECRET	HTTP 模式下必填	服务间密钥。若此变量为空或为已知占位值，HTTP 服务会记录错误并以非零状态码退出。未设置此变量时，Compose 不会启动。切勿提交真实密钥。
MCP_ALLOW_INSECURE_DEV	否	仅用于本地开发，必须精确设为 1，以便在未设置 CONDUIT_S2S_SECRET 时启动 HTTP。进程会记录警告，不会强制要求 X-Gateway-S2S，且只绑定到 127.0.0.1。若设置了非环回地址的 MCP_HTTP_HOST，该值会被覆盖并记录日志。即使设置了占位密钥，服务仍会拒绝启动。
MCP_HTTP_HOST	否	已配置密钥时的绑定地址。未设置时为 0.0.0.0。容器镜像会将其设为 0.0.0.0。启用不安全开发绕过选项时，此变量会被忽略，绑定地址改为 127.0.0.1。
MCP_HTTP_PORT	否	HTTP 端口。默认为 8080。
LOG_LEVEL	否	debug、info（默认）、warn 或 error。

/health 无需身份验证，也不要求 X-Gateway-S2S，且不会读取供应商凭据。stdio 传输不使用 CONDUIT_S2S_SECRET。

HTTP 身份验证

设置 MCP_TRANSPORT=http 和 CONDUIT_S2S_SECRET 后，每个 /mcp 请求都必须包含 X-Gateway-S2S。其值为 t=<unix seconds>,v1=<hex hmac-sha256>。十六进制摘要是使用 CONDUIT_S2S_SECRET 作为密钥，对精确的 ASCII 字符串 t=<unix seconds>（即标头中出现的相同前缀）计算 HMAC-SHA256 得到的，并编码为 64 个小写十六进制字符。时间戳与服务器时钟的偏差必须在 300 秒以内。缺少或无效的标头会返回 401。密钥绝不会写入日志或响应中。

X-Gateway-S2S: t=1710000000,v1=<64 lowercase hex chars>

已知占位值会在启动时被拒绝，且不视为已配置密钥：changeme、change-me、secret、example、placeholder、replace-me、your-secret、your-s2s-secret、s2s-secret、replace-with-a-real-secret。使用 openssl rand -hex 32 生成密钥。

在 AUTH_MODE=gateway 模式下，/mcp 还要求包含 X-DickerData-Account-Code 和 X-DickerData-Access-Token。这些标头是该请求唯一使用的 Dicker Data 凭据。缺少任一标头的请求会返回 401，且不会回退到 DICKERDATA_ACCOUNT_CODE／DICKERDATA_ACCESS_TOKEN。

工具

价格

• dickerdata_get_pricing - 实时查询一个或多个产品代码的价格和现有库存。
• dickerdata_get_price - 按指定数量查询单个产品代码的详细价格。

订单

• dickerdata_create_order - 下达采购订单。
• dickerdata_get_order_details - 查询单个订单。
• dickerdata_list_orders - 列出与账户代码 / 订单 / 预购订单 / PO 编号匹配的订单。
• dickerdata_get_order_serials - 获取订单已发货商品的序列号。
• dickerdata_get_consignment_status - 查询货运的配送 / 跟踪状态。

账户

• dickerdata_list_invoices - 查询指定日期范围内的发票。
• dickerdata_get_invoice_details - 获取销售订单 / 发票的行项目详情。

范围

这是一个 v1 / MVP 功能范围，涵盖分销商的核心工作流（定价、下单、跟踪、开票）。目前明确不在范围内的功能：Microsoft CSP/ESD 订阅管理、Autodesk 订阅和年金订单端点——这些功能面向特定供应商，与核心分销业务不同，规模也大得多。如有需求，可在后续添加。

开发

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

Docker

镜像在容器内通过 MCP_HTTP_HOST 监听 0.0.0.0，并默认使用 AUTH_MODE=gateway。将端口发布到环回地址，并传入 S2S 密钥。在网关模式下，账户代码和访问令牌会随每个请求通过 X-DickerData-Account-Code 和 X-DickerData-Access-Token 传入；不会从环境中读取这些值。

docker build -t dicker-data-mcp .
docker run \
  -e CONDUIT_S2S_SECRET="$(openssl rand -hex 32)" \
  -p 127.0.0.1:8080:8080 \
  dicker-data-mcp

不要传入 your-s2s-secret 或 changeme 等已知占位值。启动时会将这些值视为未设置并退出。若未设置 CONDUIT_S2S_SECRET，Compose 将拒绝启动；它会设置 AUTH_MODE=gateway，不会传入 DICKERDATA_ACCOUNT_CODE 或 DICKERDATA_ACCESS_TOKEN，并发布 127.0.0.1:8080:8080。项目 .env 仅用于变量插值——不要为网关服务添加 env_file。

CONDUIT_S2S_SECRET="$(openssl rand -hex 32)" docker compose up

单租户 HTTP（AUTH_MODE=env）仍需要 S2S 密钥，然后使用 DICKERDATA_ACCOUNT_CODE 和 DICKERDATA_ACCESS_TOKEN：

docker run \
  -e CONDUIT_S2S_SECRET="$(openssl rand -hex 32)" \
  -e AUTH_MODE=env \
  -e DICKERDATA_ACCOUNT_CODE=your-account-code \
  -e DICKERDATA_ACCESS_TOKEN=your-access-token \
  -e MCP_HTTP_HOST=0.0.0.0 \
  -p 127.0.0.1:8080:8080 \
  dicker-data-mcp

不使用密钥的本地 HTTP 仅限开发环境。它会绑定到 127.0.0.1 并记录警告。若 MCP_HTTP_HOST 不是环回地址（包括 0.0.0.0），该值会被覆盖，且会记录此次覆盖：

MCP_ALLOW_INSECURE_DEV=1 npm run start:http

已签名的网关请求：

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: $X_GATEWAY_S2S" \
  -H "x-dickerdata-account-code: $DICKERDATA_ACCOUNT_CODE" \
  -H "x-dickerdata-access-token: $DICKERDATA_ACCESS_TOKEN" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'