Audio Delivery Network

@audiodn/mcp

AudioDN 用の Model Context Protocol サーバーです。

AudioDN REST API を MCP ツールとして公開するため、AI エージェント（Cursor、Claude Desktop、 Claude Code、VS Code、Codex など）はユーザーに代わってオーディオホスティングを設定できます。また、 AudioDN の正式な OpenAPI 仕様とドキュメントに基づく、オフラインで利用可能な読み取り専用のナレッジツールも備えているため、エージェントは推測することなく正しいエンドポイントを参照できます。

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	いいえ	off	1 に設定すると、破壊的な adn_delete_* ツールを公開します。
ADN_MCP_LIVE_DOCS	いいえ	off	1 に設定すると、公開サイトからバンドル済みドキュメントを更新します（オフラインの場合はバンドル版を使用します）。
ADN_MCP_TIMEOUT_MS	いいえ	30000	リクエストごとのタイムアウト（ミリ秒）です。

安全性モデル

• 読み取りツールとナレッジツールには読み取り専用の注釈が付与され、常に利用できます。
• 作成／更新ツールは API キーを使用しますが、MCP クライアントが承認を求められるよう注釈が付与されています。クライアントが人間による確認の役割を担います。
• 2 つの削除ツール（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 （または使用 OS に応じた同等のファイル）を編集し、アプリを再起動してください。

{
  "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 で使用する

stdio 経由で 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	1 つの operationId に関する OpenAPI 定義の全体。
adn_get_guide	標準ガイド（認証、アップロード、処理、再生、ウェブフック、バリアントタイプ、セキュリティ、互換性）。
adn_list_variant_types	7 種類のバリアントタイプと、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}。

フローの例

ポッドキャストのホスティングをユーザーに支援するエージェントは、次のように呼び出します。

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. コードで音声バイト列を track_upload.upload_url に PUT します。
6. track_status_id === "ready" になるまで adn_get_track({ track_id }) をポーリングします。
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 は、wrangler.toml の routes エントリーに基づいて Cloudflare により設定されます（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 エージェント向けガイド：https://audiodeliverynetwork.com/for-ai-agents