Audio Delivery Network

@audiodn/mcp

AudioDN 的模型上下文协议服务。

将 AudioDN REST API 作为 MCP 工具提供，使 AI Agent（Cursor、Claude Desktop、 Claude Code、VS Code、Codex 等）能够代表用户配置音频托管；此外，还提供离线、只读的知识工具，其内容基于权威的 AudioDN OpenAPI 规范和文档，让 Agent 查找正确的端点，而不是靠猜测。

在 Cursor 中安装

一键安装（托管端点，无需设置——知识/文档工具可立即使用）：

要启用实时 API 工具，请在启动 Cursor 前于环境中设置 ADN_API_KEY（从控制面板获取的 adn_... 密钥）；托管端点会从 Authorization 请求头中读取它。更倾向于使用本地 stdio 服务？请改用此按钮：

两种方式都对应此插件附带的 mcp.json。手动设置请参阅 Cursor 的 MCP 文档。

安装

npm install -g @audiodn/mcp
# or run on demand
npx @audiodn/mcp

配置

设置 AudioDN 服务端 API 密钥（在 https://account.audiodeliverynetwork.com 的 Settings → API Keys 中创建）。

export ADN_API_KEY="adn_..."
# Optional overrides:
# export ADN_API_BASE_URL="https://api.audiodelivery.net"  # default
# export ADN_MCP_ALLOW_DELETE=1     # enable destructive delete tools (off by default)
# export ADN_MCP_LIVE_DOCS=1        # refresh bundled docs from the public site at startup
# export ADN_MCP_TIMEOUT_MS=30000   # per-request timeout

环境变量

变量	必需	默认值	用途
ADN_API_KEY	是	–	服务端全权限 API 密钥，用于所有实时 API 工具。
ADN_API_BASE_URL	否	https://api.audiodelivery.net	覆盖 API 主机。
ADN_MCP_ALLOW_DELETE	否	关闭	设置为 1 以启用具有破坏性的 adn_delete_* 工具。
ADN_MCP_LIVE_DOCS	否	关闭	设置为 1，从公开网站刷新内置文档（离线时回退到内置文档）。
ADN_MCP_TIMEOUT_MS	否	30000	每个请求的超时时间，单位为毫秒。

安全模型

• 读取和知识工具均标注为只读，且始终可用。
• 创建/更新工具使用 API 密钥运行，但会进行标注，以便 MCP 客户端请求批准；客户端负责实现人在环路中的审批。
• 两个删除工具（adn_delete_creator、adn_delete_collection）默认隐藏，除非启动服务时设置 ADN_MCP_ALLOW_DELETE=1，否则会拒绝运行。设置一次即可启用。

托管（远程）端点

除了上文的本地 npx stdio 服务，AudioDN 还在 Cloudflare Workers 上通过托管的 Streamable HTTP 端点运行相同的工具集，因此支持远程 MCP 服务的客户端无需安装即可连接。

• URL： https://mcp.audiodelivery.net/mcp —— MCP 端点。根路径 / 在浏览器中提供人类可读的落地页（也为工具提供 JSON），而 /health 返回机器可读的服务信息。
• **身份验证——使用你自己的密钥：**该端点公开访问，且不存储任何密钥。 知识/文档工具无需密钥即可使用。要启用实时 API 工具，请在每个请求中通过以下任一请求头发送你的 AudioDN API 密钥：

Authorization: Bearer adn_...
# or
X-ADN-API-Key: adn_...

• 删除工具在托管端点上始终不可用，与密钥无关。

客户端配置示例（适用于支持远程/HTTP MCP URL 的客户端）：

{
  "mcpServers": {
    "audiodn": {
      "url": "https://mcp.audiodelivery.net/mcp",
      "headers": { "Authorization": "Bearer adn_..." }
    }
  }
}

托管 Worker 位于 worker/ 中，并通过 Wrangler 部署 （npm run deploy）；它不属于已发布的 npm 包。

在 Cursor 中使用

Settings → Tools & Integrations → MCP（或编辑 ~/.cursor/mcp.json）：

{
  "mcpServers": {
    "audiodn": {
      "command": "npx",
      "args": ["-y", "@audiodn/mcp"],
      "env": { "ADN_API_KEY": "adn_..." }
    }
  }
}

在 Claude Desktop 中使用

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json （或你的操作系统中的对应文件），然后重启应用：

{
  "mcpServers": {
    "audiodn": {
      "command": "npx",
      "args": ["-y", "@audiodn/mcp"],
      "env": { "ADN_API_KEY": "adn_..." }
    }
  }
}

在 Claude Code 中使用

claude mcp add audiodn --env ADN_API_KEY=adn_... -- npx -y @audiodn/mcp

与 VS Code (Copilot) / Codex / Windsurf 搭配使用

任何通过标准输入/输出使用 MCP 的客户端都使用相同的命令。对于 VS Code，请添加到 .vscode/mcp.json：

{
  "servers": {
    "audiodn": {
      "command": "npx",
      "args": ["-y", "@audiodn/mcp"],
      "env": { "ADN_API_KEY": "adn_..." }
    }
  }
}

对于 Codex CLI（~/.codex/config.toml）：

[mcp_servers.audiodn]
command = "npx"
args = ["-y", "@audiodn/mcp"]
env = { ADN_API_KEY = "adn_..." }

工具

知识工具（只读、离线、无需 API 密钥）

工具	说明
adn_about	服务版本、内置 OpenAPI 版本、文档来源、API 基础 URL。
adn_search_docs	在内置文档和 OpenAPI 摘要中进行关键词搜索。
adn_list_operations	列出所有 REST 操作（operationId、方法、路径）。
adn_get_operation	获取某个 operationId 的完整 OpenAPI 定义。
adn_get_guide	获取规范指南（身份验证、上传、处理、播放、webhook、variant-types、安全、兼容性）。
adn_list_variant_types	七种变体类型，以及哪些可通过 API 创建。

实时 API 工具

工具	说明	注释
adn_list_creators / adn_get_creator	读取创作者	只读
adn_create_creator / adn_update_creator	创建/更新创作者	写入
adn_delete_creator	删除创作者	破坏性操作（受限）
adn_list_collections / adn_get_collection	读取合集	只读
adn_create_collection / adn_update_collection	创建/更新合集	写入
adn_delete_collection	删除合集及其音轨	破坏性操作（受限）
adn_list_tracks / adn_get_track	读取音轨；adn_get_track 会轮询就绪状态	只读
adn_create_upload_session / adn_get_upload_session	管理上传会话	写入 / 只读
adn_create_track_in_upload_session	注册音轨并获取 track_upload.upload_url	写入
adn_create_play_session / adn_get_play_session	创建/读取播放会话（范围：合集、音轨）	写入 / 只读
adn_list_variants	列出组织的交付变体	只读

资源

该服务还通过 MCP 资源公开规范文档，供直接附加上下文的客户端使用：audiodn://openapi.json、audiodn://llms-full.txt，以及每份指南对应的 audiodn://guide/{topic}。

示例流程

帮助用户托管播客的 Agent 可能会调用：

1. adn_get_guide({ topic: "upload" }) — 了解规范的多步骤流程。
2. adn_create_collection({ title: "My Podcast" })
3. adn_create_upload_session({ collection_id })
4. adn_create_track_in_upload_session({ upload_session_id, file_name: "ep1.mp3" })
5. 你的代码通过 PUT 将音频字节上传到 track_upload.upload_url。
6. 轮询 adn_get_track({ track_id })，直到 track_status_id === "ready"。
7. adn_create_play_session({ scope: "track", track_id }) — 返回一个可直接嵌入的签名播放 URL。

从源代码构建

npm install
npm run build
npm test           # vitest
npm run smoke      # build + spawn the real binary over stdio
node dist/index.js

部署托管端点

worker/ 中的 Cloudflare Worker 通过 Streamable HTTP 提供相同的工具。

npx wrangler login
npm run dev:worker        # local: http://localhost:8787/mcp and /health
npm run deploy            # publish -> https://mcp.audiodelivery.net (custom domain)
curl https://mcp.audiodelivery.net/health

自定义域名 mcp.audiodelivery.net 由 Cloudflare 根据 wrangler.toml 中的 routes 条目配置（audiodelivery.net 区域必须位于同一个 Cloudflare 账户中）。

要在官方 MCP 注册表中登记（注册表名称为 net.audiodelivery/mcp，必须与 package.json 中的 mcpName 匹配）：使用 mcp-publisher login dns --domain audiodelivery.net 验证域名一次（添加显示的 TXT 记录），确认 server.json 中的 remotes[0].url 指向已部署的 URL，然后运行 mcp-publisher publish。

保持文档更新

内置快照位于 assets/snapshots/。使用 npm run sync 从公共网站刷新；发布前，prepublishOnly 会验证这些快照是否一致。

参考

• API 文档：https://audiodeliverynetwork.com/docs/api
• OpenAPI 规范：https://audiodeliverynetwork.com/openapi.json
• 面向 AI Agent 的指南：https://audiodeliverynetwork.com/for-ai-agents