Dubber

dubber-mcp

适用于 Dubber 的 MCP 服务——通话录音上传／检索、合规元数据和标签、组／账户／用户管理、REST-hook（webhook）通知，以及 Dub.Point 电信系统（例如 BroadWorks）集成。

基于 MCP 2026-07-28 规范，通过拆分的 v2 SDK（@modelcontextprotocol/server / /node / /client ^2.0.0-beta.5）构建，支持双时代服务：一个共享的 McpServerFactory 位于 createMcpHandler({ legacy: 'stateless' }) 后，既能响应 2025 时代通过 initialize 握手的客户端（目前为 WYRE 网关），也能响应现代 2026-07-28 信封客户端，所有调用方看到的 37 个工具表面完全一致且确定。仅以 GHCR 容器形式发布（不提供 MCPB 包）。Dubber 客户端为 @wyre-ai/node-dubber。

工具（37 个，扁平）

• 核心：dubber_test_connection。
• 组：dubber_groups_get、dubber_groups_create_child、 dubber_groups_list_unidentified_recordings、dubber_groups_create_unidentified_recording。
• 账户：dubber_accounts_create、dubber_accounts_get、dubber_accounts_update。
• 录音：dubber_recordings_list、dubber_recordings_create、dubber_recordings_get、 dubber_recordings_get_waveform、dubber_recordings_update_metadata、 dubber_recordings_add_tags、dubber_recordings_initiate_multipart_upload、 dubber_recordings_get_upload_target、dubber_recordings_complete_upload。 受限工具：dubber_recordings_delete（⚠ 破坏性操作）、dubber_recordings_delete_tags （⚠ 影响重大）。 dubber_recordings_list 按最新优先列出，支持 limit（1–500，默认 100）、offset、 cursor、query、dubPointId/teamId 和 start_time 时间范围——请参阅 列出录音。
• 用户：dubber_users_list、dubber_users_create、dubber_users_get、 dubber_users_update。受限工具：dubber_users_delete（⚠ 破坏性操作）。
• 个人资料：dubber_profile_get。
• 通知（REST hooks）：dubber_notifications_list、dubber_notifications_create、 dubber_notifications_get、dubber_notifications_update、dubber_notifications_activate、 dubber_notifications_list_unclaimed。受限工具：dubber_notifications_delete（⚠ 影响重大）。
• Dub.Point：dubber_dub_points_list、dubber_dub_points_create、dubber_dub_points_get、 dubber_dub_points_find。
• OAuth：受限工具 dubber_oauth_revoke_token（⚠ 影响重大）。

凭据

需要提供全部四个值——它们都不是人工登录凭据（见下文“供应商特例”）。

环境变量（env 模式）	网关请求头（AUTH_MODE=gateway）	来源
DUBBER_CLIENT_ID	X-Dubber-Client-Id	Mashery 应用密钥（developer.dubber.net）
DUBBER_CLIENT_SECRET	X-Dubber-Client-Secret	Mashery 应用机密
DUBBER_AUTH_ID	X-Dubber-Auth-Id	Dubber 门户 → API 选项卡
DUBBER_AUTH_TOKEN	X-Dubber-Auth-Token	Dubber 门户 → API 选项卡
DUBBER_REGION（可选，默认值为 sandbox）	X-Dubber-Region	选择 api.dubber.net/<region>/v1
DUBBER_BASE_URL（可选）	无（特意如此）	仅限 env 模式的完整覆盖值

在网关模式下，如果请求缺少任何一个必需请求头，系统会在 MCP 处理程序运行前返回 401 （JSON-RPC 错误 -32001）。系统绝不会回退到环境变量凭据——同样也会完全拒绝由请求头控制的基础 URL（仅限 env 模式），因此调用方无法将客户端机密重定向到其他主机。空白或重复的请求头值会被视为缺失。

/health 和 /healthz 无需身份验证，也不会读取凭据。stdio 传输不使用 CONDUIT_S2S_SECRET。

变量	必需	说明
CONDUIT_S2S_SECRET	HTTP 必需	服务间机密。如果该值为空或为已知占位符（changeme、secret、replace-me、replace-with-a-real-secret 及其他示例值），HTTP 服务端会记录错误并以非零状态码退出。使用 openssl rand -hex 32 生成。未设置此值时，Compose 不会启动。绝不会记录该值。
MCP_ALLOW_INSECURE_DEV	否	仅在本地开发时设为 1，即可在未设置 CONDUIT_S2S_SECRET 的情况下启动 HTTP。进程会记录警告，不会强制检查 X-Gateway-S2S，并且只绑定到 127.0.0.1。非环回地址的 MCP_HTTP_HOST（包括 0.0.0.0）会被忽略，并记录此覆盖情况。若使用已知占位符机密，仍会拒绝启动。
MCP_HTTP_HOST	否	设置了有效 CONDUIT_S2S_SECRET 时使用的绑定地址。未设置时使用 0.0.0.0，即沿用历史容器绑定地址。镜像和 Compose 会在容器内设置为 0.0.0.0。
MCP_HTTP_PORT	否	HTTP 端口。默认为 8080。
AUTH_MODE	否	gateway（Docker 镜像和 Compose）或 env。网关模式要求每个 /mcp 请求都带有四个 X-Dubber-* 凭据请求头，且绝不回退到 DUBBER_*。env 模式仅在 S2S 身份验证成功后使用这些环境变量。未设置时默认为 env（stdio 和镜像外的单租户 HTTP）。

HTTP 身份验证

设置了 MCP_TRANSPORT=http 和 CONDUIT_S2S_SECRET 时，除 /health 和 /healthz 外的每个请求都必须包含 X-Gateway-S2S。该检查由 src/s2s-verify.ts 中的 verifyS2sHeader 执行：请求头的值为 t=<unix seconds>,v1=<hex>， 其中 hex 是以 CONDUIT_S2S_SECRET 为密钥，对字面字符串 t=<unix seconds> 计算得到的 HMAC-SHA256（64 个小写十六进制字符）。时间戳与服务器时钟的偏差必须在 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-Dubber-Client-Id: $DUBBER_CLIENT_ID" \
  -H "X-Dubber-Client-Secret: $DUBBER_CLIENT_SECRET" \
  -H "X-Dubber-Auth-Id: $DUBBER_AUTH_ID" \
  -H "X-Dubber-Auth-Token: $DUBBER_AUTH_TOKEN" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

在 AUTH_MODE=gateway 模式下，/mcp 还要求提供 X-Dubber-Client-Id、X-Dubber-Client-Secret、 X-Dubber-Auth-Id 和 X-Dubber-Auth-Token（X-Dubber-Region 为可选项）。这些请求头是该请求唯一的凭据来源。AUTH_MODE=env 仍要求提供已签名的 X-Gateway-S2S 请求头，然后使用环境中的 DUBBER_*。

运行

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 set
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_TRANSPORT=http MCP_ALLOW_INSECURE_DEV=1 node dist/index.js
npm run smoke                             # proves both protocol eras serve the same tools

Docker（根据 fleet law 使用 linux/amd64）。镜像会在容器内的 0.0.0.0（MCP_HTTP_HOST）上监听，默认使用 AUTH_MODE=gateway。请将端口发布到 loopback，并传入真实的 S2S 密钥。在网关模式下，每个请求都会通过请求头传入 Dubber 凭据；不会从环境变量中读取这些凭据。

docker build --platform linux/amd64 --build-arg GITHUB_TOKEN=$(gh auth token) -t dubber-mcp .
docker run \
  -e CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" \
  -p 127.0.0.1:8080:8080 \
  dubber-mcp

未设置 CONDUIT_S2S_SECRET 时，Compose 会拒绝启动。网关服务会设置 AUTH_MODE=gateway，不会注入 DUBBER_CLIENT_ID、DUBBER_CLIENT_SECRET、DUBBER_AUTH_ID 或 DUBBER_AUTH_TOKEN，并发布 127.0.0.1:8080:8080：

CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" docker compose up

单租户 HTTP（AUTH_MODE=env）仍需要 S2S 密钥，然后使用 DUBBER_* 变量。它与上述网关 Compose 服务相互独立。

docker run \
  -e CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" \
  -e AUTH_MODE=env \
  -e DUBBER_CLIENT_ID=... -e DUBBER_CLIENT_SECRET=... \
  -e DUBBER_AUTH_ID=... -e DUBBER_AUTH_TOKEN=... \
  -p 127.0.0.1:8080:8080 \
  dubber-mcp

征询与破坏性操作确认

每个受控工具在执行操作前都会征求确认。征询通过 SDK v2 MRTR 接口进行：处理程序会返回 input_required 结果，由 2026-07-28 客户端补充信息并重试；对于 2025 年前后的有状态连接（stdio），SDK 的旧版兼容层会在服务端补充信息。所有读取操作和确认都在唯一一次会修改数据的 Dubber 调用之前完成。

无法征求确认的调用方（包括无状态旧版 HTTP 请求，WYRE Conduit 网关正是通过这种方式连接）会默认拒绝操作：除非调用中传入 "confirm_destructive_action": true，否则受控工具不会运行。只有在无法弹出确认提示时才会检查此参数；它不会跳过交互用户本应看到的确认。

列出录音和时间范围

Dubber 的录音端点仅支持 count（最大值 100）、page（最多 5 页）、before_id 游标和 query——不支持 limit/offset 和日期筛选，且会静默忽略未知参数。因此，dubber_recordings_list 会自行分页读取 Dubber 数据（count=100，串联 before_id），并在服务端应用其余筛选条件：

• limit（1–500，默认值 100）：最多返回的匹配录音数。offset（≥0）：跳过的新近优先排序的匹配录音数。
• startTimeFrom（包含）/startTimeTo（不包含日期时间；仅日期值会包含整天）：使用 ISO 8601 格式，不带时区偏移量时按 UTC 处理。获取数据后，根据每条录音的 start_time 进行筛选；无法解析 start_time 的录音会被排除，并计入 excludedUnparseableStartTime。墨尔本夏令时（AEDT，+11:00）下的每周拉取（周一至周五）：startTimeFrom=2026-10-19T00:00:00+11:00、startTimeTo=2026-10-24T00:00:00+11:00、limit=500。
• dubPointId / teamId（可选，去除首尾空格后不能为空；每次分页请求都会分别作为 Dubber 的 dub_point / team 参数发送，并回显在 filters 中）：每次调用只能指定一个 dub point 或一个团队——Dubber 禁止同时传入二者，因此同时传入会报错。Dubber 不支持直接按用户筛选录音：如需获取某位技术人员一周内的录音，请使用 dubber_dub_points_list 查找其 dub point id（每个 dub point 的 user 都是一个以 /users/<USER_ID> 结尾的 URL），然后针对每个 dub point 分别调用。cursor 必须与相同的 dubPointId/teamId 配合使用。
• 每次调用最多发出 25 个 Dubber 请求（扫描 2,500 条录音）。如果达到此上限或 limit 导致扫描提前停止，则 hasMore 为 true，且会设置 nextCursor：请使用 cursor=<nextCursor>、offset=<remainingOffset>（除非扫描上限触发时仍在跳过记录，否则为 0）以及相同的筛选条件再次调用，以便继续扫描，避免遗漏或重复。scanCapReached 表示是否因达到扫描上限而停止。设置了 startTimeFrom 时，如果整页录音的开始时间都早于该值，扫描就会停止。
• 结果：{ recordings, returned, hasMore, nextCursor, remainingOffset, scanned, requests, scanCapReached, filters, note }。

处理程序通过对 @wyre-ai/node-dubber 1.0.0 执行一次类型转换来发送 Dubber 参数（该版本的类型化参数为 {limit, offset}）；采用包含 count/before_id/query 类型定义的 SDK 版本后，请移除该类型转换。

此处编码的供应商特性

• 使用密码授权，但不需要真人密码。 OAuth 令牌请求中的 username/password 是门户 API 选项卡中的 Dubber Auth ID / Dubber Auth Token 这一对凭据，而非个人登录凭据。参见 docs/DESIGN.md §3。
• 主机按区域划分，没有统一的生产环境默认值。 sandbox 免费且可自行注册使用；生产环境地址为 https://api.dubber.net/<region>/v1，其中区域需由 Dubber 确认——若使用了错误的地址，系统会在不发出提示的情况下连接到错误的租户。
• 没有可下载的 API 规范。 所有端点和身份验证流程均已通过在线 /io-docs 控制台和官方 Getting Started Guide 验证；node-dubber 的 src/types/index.ts 中完整的响应正文结构只是有据可查的尽力说明下限，而非声称的上限。参见 docs/DESIGN.md §4 和 CONTRIBUTING.md。
• 未实现刷新令牌流程。 Dubber 的响应包含 refresh_token，但其约定没有任何可验证的文档说明——此客户端只会在令牌过期时使用相同的密码授权重新获取令牌，这与 node-kpn 在相同限制下的现有选择一致。

许可证

Apache-2.0 © WYRE Technology