@audiodn/agent-kit - npm Package Compare versions

Comparing version 0.1.0 to 0.1.1

assets/content/instructions.md

@@ -29,2 +29,19 @@ # AudioDN integration guide for coding agents
 
+## MCP server (optional)
+
+If your assistant speaks the Model Context Protocol, you can call AudioDN through
+its MCP server instead of writing raw HTTP. It exposes the same API operations as
+tools plus offline, grounded documentation/knowledge tools, so the correct
+endpoints and fields come from the canonical spec rather than guesswork. Two ways
+to connect:
+
+- Hosted (remote): a public Streamable HTTP endpoint at
+  `https://mcp.audiodelivery.net/mcp`. Knowledge/doc tools work with no key; live
+  API tools activate when you send your AudioDN key as `Authorization: Bearer
+  adn_...` or `X-ADN-API-Key: adn_...`. Delete tools are never exposed there.
+- Local (stdio): `npx @audiodn/mcp` with `ADN_API_KEY` set to a server-side key.
+
+This does not replace the rules above — server API keys still stay server-side,
+and the same canonical OpenAPI remains the source of truth.
+
 ## Canonical references
@@ -36,2 +53,3 @@
 - AI-agent guide: https://audiodeliverynetwork.com/for-ai-agents
+- MCP server: https://www.npmjs.com/package/@audiodn/mcp
 
@@ -38,0 +56,0 @@ ## Validate your work

assets/content/partials/playback.md

@@ -11,5 +11,7 @@ ## Playback and delivery
   (HMAC-SHA256; the `verify` query param must be appended **last**). Skips play
-  sessions for public/entitled tracks. The signing secret is server-only.
+  sessions for public/entitled tracks. The signing secret is server-only. Build
+  the URL from the durable `track.base_url` returned at track creation, plus the
+  variant suffix and extension (e.g. `{base_url}_128.mp3`).
 
 For components, pass a Client-Side Player key or a server-provisioned play
 session ID to `<audiodn-player>`. See `references/playback.md` in the Skill.

assets/content/partials/upload.md

@@ -9,5 +9,6 @@ ## Upload flow (do not skip steps)
 2. **Create a track in the session** (no Bearer — the session ID authorizes it):
-   `POST /v1/upload/{upload_session_id}/track` -> returns `track_id` and a
-   per-track upload target in `track_upload.upload_url` (with `track_upload.method`).
-   Do this **once per file**.
+   `POST /v1/upload/{upload_session_id}/track` -> returns `track_id`, the full
+   `track` object (including the durable delivery prefix `track.base_path` /
+   `track.base_url`), and a per-track upload target in `track_upload.upload_url`
+   (with `track_upload.method`). Do this **once per file**.
 3. **Upload the bytes**: `PUT` the file to `track_upload.upload_url`.
@@ -18,2 +19,4 @@ 4. **Wait for readiness** before playback (see Processing).
 in a database, cache it, or treat it as a permanent link — mint a fresh track if
-it expires. See `references/upload-flow.md` in the Skill.
+it expires. `track.base_path` / `track.base_url` ARE durable — store them if you
+use signed delivery (each variant file is that prefix plus a suffix and
+extension, e.g. `{base_url}_128.mp3`). See `references/upload-flow.md` in the Skill.

assets/skill/references/playback.md

@@ -22,2 +22,6 @@ # Playback reference
 
+Build the URL from the durable `track.base_url` returned at track creation (a
+prefix on the organization's unique `audiodelivery.net` subdomain): append the
+variant suffix and extension (e.g. `{base_url}_128.mp3`), then sign.
+
 ## Components
@@ -29,3 +33,3 @@
 Canonical: https://audiodeliverynetwork.com/docs/api/play-sessions and
-`/docs/integration/signed-delivery`.
+`/docs/integration/playback?option=signed-delivery`.
 OpenAPI operationIds: `createPlaySession`, `getPlayTrack`, `downloadPlayTrackVariant`.

assets/skill/references/upload-flow.md

@@ -12,5 +12,13 @@ # Upload-flow reference
 2. **Create a track in the session** (no Bearer)
-   `POST /v1/upload/{upload_session_id}/track` with `{ file_name }`.
-   Returns `track_id` and `track_upload` = `{ method, upload_url }`.
-   Do this once per file.
+   `POST /v1/upload/{upload_session_id}/track` with `{ file_name }` (plus the
+   same optional track fields as `POST /v1/track`: `organization_index`,
+   `metadata`, `player_title`, `player_subtitle`, `player_color`,
+   `is_cover_overridable`, `is_theme_overridable`).
+   Returns `track_id`, the full `track` object — including the durable delivery
+   prefix `track.base_path` / `track.base_url` (each variant file is that prefix
+   plus a suffix and extension, e.g. `{base_url}_128.mp3`) — and
+   `track_upload` = `{ method, upload_url }`.
+   Do this once per file. All three track creators (`POST /v1/track`, the nested
+   `track` on `POST /v1/upload_session`, and this endpoint) return the same
+   `track` shape.
 
@@ -28,4 +36,7 @@ 3. **Upload the bytes**
 - The session-create step does NOT return `upload_url` — do not expect one.
+- `track.base_path` / `track.base_url` ARE durable — store them (with `track_id`)
+  if you use signed delivery. `base_url` lives on the organization's unique
+  `audiodelivery.net` subdomain. Never upload to it.
 
 Canonical: https://audiodeliverynetwork.com/docs/api/upload-sessions
 OpenAPI operationIds: `createUploadSession`, `createUploadSessionTrack`.

assets/skill/SKILL.md

@@ -34,2 +34,8 @@ ---
 
+MCP-capable assistants can also call AudioDN via its MCP server instead of raw
+HTTP - hosted at `https://mcp.audiodelivery.net/mcp` (bring-your-own-key header)
+or local via `npx @audiodn/mcp` - which exposes the API plus grounded doc tools.
+The same non-negotiable rules apply (server keys stay server-side; verify against
+the canonical OpenAPI).
+
 ## Framework templates
@@ -36,0 +42,0 @@

assets/snapshots/llms-full.txt

@@ -343,6 +343,53 @@ # AudioDN — Full LLM-readable site dump
 
-## 14. Contact
+## 14. AudioDN Agent Kit (coding-agent setup)
 
+If you are an AI coding agent working in a developer's repository, do not guess at the API —
+install AudioDN's own guidance and a validator. The kit is published independently on npm as
+@audiodn/agent-kit (https://www.npmjs.com/package/@audiodn/agent-kit).
+
+- `npx @audiodn/agent-kit init` — installs merge-safe guidance in the formats agents read:
+  AGENTS.md, CLAUDE.md, .github/copilot-instructions.md, .cursor/rules/audiodn.mdc, and a portable
+  Skill under .agents/skills/audiodn/ (SKILL.md + auth/upload/processing/playback/webhooks/security
+  references + framework templates). Idempotent; never clobbers existing content; supports
+  --dry-run, --force, --formats, and uninstall.
+- `npx @audiodn/agent-kit validate .` — scans a project for eight common mistakes: server key in
+  client code, invented endpoints (checked against the bundled OpenAPI), missing per-track upload
+  request, treating an upload URL as permanent, playback before `ready`, hardcoded secrets,
+  incorrect API origin (marketing host instead of api.audiodelivery.net), and obsolete doc URLs.
+
+The guidance and endpoint list derive from this site's canonical OpenAPI and llms-full.txt via a
+one-way sync, so the kit stays consistent with the API without the site depending on it.
+
+## 15. AudioDN MCP server (Model Context Protocol)
+
+For assistants that speak the Model Context Protocol (Cursor, Claude Desktop, Claude Code, VS Code,
+Codex, and others), the AudioDN MCP server lets the assistant call the API and look up canonical
+endpoints directly. There are two ways to connect:
+
+- Hosted (remote): a public Streamable HTTP endpoint at https://mcp.audiodelivery.net/mcp. It stores no
+  secrets — knowledge/doc tools work with no key, and live API tools activate when the client sends an
+  AudioDN API key on each request as `Authorization: Bearer adn_...` or `X-ADN-API-Key: adn_...`. Delete
+  tools are never exposed on the hosted endpoint. (The root https://mcp.audiodelivery.net/ serves an info
+  page; /health returns JSON.)
+- Local (stdio): published independently on npm as @audiodn/mcp
+  (https://www.npmjs.com/package/@audiodn/mcp) and run via `npx @audiodn/mcp`.
+
+- Configure the local server with `ADN_API_KEY` (a server-side, full-access API key). Optional env:
+  `ADN_API_BASE_URL`, `ADN_MCP_ALLOW_DELETE=1`, `ADN_MCP_LIVE_DOCS=1`, `ADN_MCP_TIMEOUT_MS`.
+- Live API tools: creators, collections, tracks, upload sessions, per-track upload URLs, play sessions,
+  and variants. Reads are annotated read-only; create/update tools are annotated so the client can
+  prompt for approval.
+- Destructive delete tools (adn_delete_creator, adn_delete_collection) are hidden and refuse to run
+  unless the server is started with `ADN_MCP_ALLOW_DELETE=1`.
+- Offline, read-only knowledge tools grounded in bundled canonical snapshots (OpenAPI + llms-full):
+  adn_search_docs, adn_list_operations, adn_get_operation, adn_get_guide, adn_list_variant_types,
+  adn_about. Canonical docs are also exposed as MCP resources (audiodn://openapi.json,
+  audiodn://llms-full.txt, audiodn://guide/{topic}).
+
+The bundled snapshots derive from this site's canonical OpenAPI and llms-full.txt via a one-way sync.
+
+## 16. Contact
+
 - Sales: [e-mail]
 - Support: [e-mail]
 - Security: [e-mail]

assets/snapshots/sources.json

 {
   "openapiVersion": "1.0.0",
   "generatedBy": "scripts/sync-canonical.mjs",
-  "note": "Seeded from the canonical monorepo openapi.json (ahead of the current public deploy). scripts/sync-canonical.mjs refreshes from https://audiodeliverynetwork.com once redeployed.",
   "sources": [
@@ -9,3 +8,3 @@ {
       "url": "https://audiodeliverynetwork.com/openapi.json",
-      "fetchedAt": "2026-07-13",
+      "fetchedAt": "2026-07-14",
       "sha256": "e1554673a4d7287a15460bdc2761e0bbc38286b4e101df26b00fc5e9205e2deb"
@@ -16,6 +15,6 @@ },
       "url": "https://audiodeliverynetwork.com/llms-full.txt",
-      "fetchedAt": "2026-07-13",
-      "sha256": "41980ad7654d997132683399b6a4ab38fce87944ebb9c5cf1779daea996d18af"
+      "fetchedAt": "2026-07-14",
+      "sha256": "5374d9eaa65c8b7641fa8881db814484e178fbd9620d6f7be22ae3ef56349b65"
     }
   ]
 }

package.json

 {
   "name": "@audiodn/agent-kit",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Install AudioDN coding-agent guidance (AGENTS.md, CLAUDE.md, Copilot, Cursor, Skill) and validate AudioDN integrations.",
@@ -5,0 +5,0 @@ "type": "module",

README.md

@@ -25,3 +25,3 @@ # @audiodn/agent-kit
 ```
-<!-- AUDIODN:BEGIN v0.1.0 (managed by @audiodn/agent-kit — do not edit inside) -->
+<!-- AUDIODN:BEGIN v0.1.1 (managed by @audiodn/agent-kit — do not edit inside) -->
 ...
@@ -28,0 +28,0 @@ <!-- AUDIODN:END -->

No alert changes

Improved metrics

Total package byte prevSize

155797

3.85%

Worsened metrics

Lines of code

2469

-0.04%

No dependency changes