@audiolabtools/mcp-server 0.2.0 → 0.3.1

package/README.md

@@ -1,90 +1,91 @@
-# @audiolabtools/mcp-server
-
-MCP ([Model Context Protocol](https://modelcontextprotocol.io)) server that gives any
-MCP-capable AI — Claude Desktop, Claude Code, Cursor, and others — eight audio-analysis
-tools, backed by the hosted **AudioLab** API. It is a thin HTTP client: **no local audio
-engine, no ffmpeg, nothing to compile.** It can analyse a **public URL** or a **local file**
-on your machine.
-
-## Install
-
-Point your MCP client at the package via `npx` (nothing to install globally):
-
-```json
-{
-  "mcpServers": {
-    "audiolab": {
-      "command": "npx",
-      "args": ["-y", "@audiolabtools/mcp-server"],
-      "env": { "AUDIOLAB_API_KEY": "al_live_yourkey" }
-    }
-  }
-}
-```
-
-Get a key: sign in at **https://audiolab.tools/account** and generate one (free tier available).
-
-## Requirements
-
-- **Node ≥ 18** — uses the built-in global `fetch` + `AbortSignal.timeout`.
-- An `AUDIOLAB_API_KEY`. No ffmpeg, no native dependencies.
-
-## Tools
-
-Every tool takes **one audio source** — a public `url` **or** a local `path`:
-
-- `{ url: "https://…" }` — a public https URL the API fetches server-side.
-- `{ path: "./mix.wav" }` — a file on the machine running this server. Files up to **4 MB**
-  are sent inline; larger files (up to **50 MB**) upload over a one-shot signed URL, are
-  analysed, and are then deleted. *(Local `path` works only in this stdio server, not the
-  remote `/mcp` endpoint.)*
-
-| Tool | Returns |
-|---|---|
-| `analyze_loudness` | Integrated LUFS (EBU R128 / BS.1770-4), true-peak (dBTP), LRA, crest factor, stereo correlation, mono compatibility, tonal balance |
-| `check_target` | Pass/fail vs a delivery target (`spotify` / `apple-music` / `youtube` / `tidal` / `amazon-music` / `podcast` / `ebu-broadcast` / `atsc-broadcast`, or `target:"custom"` + `lufs`+`tp`), with per-metric deltas and an ffmpeg loudnorm fix command |
-| `analyze_timeseries` | Short-term LUFS over time + downsampled waveform peaks (`waveformPoints?`) |
-| `get_spectrum` | FFT magnitude data + 7-band energies + dominant band |
-| `analyze_voice` | Voice QA: speech/silence ratio, speaking rate, SNR, noise floor, room echo, sibilance & clipping risk |
-| `get_speech_segments` | Voiced regions with start/end + per-segment RMS (auto-trim, chapters) |
-| `index_signal` | Content-type guess, tags, clipping/silence regions, brightness & dynamics buckets |
-| `compare_loudness` | A/B on two sources (`urlA`/`pathA` + `urlB`/`pathB`), returns both results |
-
-Example asks to your AI:
-
-- *“Analyze the loudness of https://example.com/track.wav”* → `analyze_loudness` with `url`
-- *“Run loudness on ./master.wav”* → `analyze_loudness` with `path`
-- *“Does ./mix.mp3 pass Spotify?”* → `check_target` with `path` + `target:"spotify"`
-
-## Configuration (env)
-
-| Var | Default | Purpose |
-|---|---|---|
-| `AUDIOLAB_API_KEY` | — (required) | Your API key. |
-| `AUDIOLAB_API_BASE` | `https://audiolab.tools/v1` | Override the API base (must be `https://`). |
-| `AUDIOLAB_TIMEOUT_MS` | `60000` | Per-request timeout in milliseconds. |
-
-## Privacy
-
-Analysis happens on the AudioLab API, so the audio **does reach `audiolab.tools`** — a `url`
-is fetched server-side, and a local `path` is sent to the API (small files inline; larger
-files via a private one-shot signed upload that is deleted right after analysis). The API
-returns **numbers only** and does not retain your audio (see https://audiolab.tools/privacy).
-This package has no telemetry and writes nothing to disk. If audio must never leave the
-machine, don't use a hosted analyser.
-
-## Limits
-
-- Local files: up to **50 MB** (host bigger ones at a public URL).
-- One file per call (agents loop for many); one-shot (no streaming/realtime).
-- Rate and monthly limits are enforced by the API, per key.
-
-## Smoke test
-
-```sh
-node hosted-server.mjs --selftest   # verifies the 8 tools + guards; no network
-```
-
-## License
-
-MIT © Nathan Renting
+# @audiolabtools/mcp-server
+
+MCP ([Model Context Protocol](https://modelcontextprotocol.io)) server that gives any
+MCP-capable AI — Claude Desktop, Claude Code, Cursor, and others — nine audio-analysis
+tools, backed by the hosted **AudioLab** API. It is a thin HTTP client: **no local audio
+engine, no ffmpeg, nothing to compile.** It can analyse a **public URL** or a **local file**
+on your machine.
+
+## Install
+
+Point your MCP client at the package via `npx` (nothing to install globally):
+
+```json
+{
+  "mcpServers": {
+    "audiolab": {
+      "command": "npx",
+      "args": ["-y", "@audiolabtools/mcp-server"],
+      "env": { "AUDIOLAB_API_KEY": "al_live_yourkey" }
+    }
+  }
+}
+```
+
+Get a key: sign in at **https://audiolab.tools/account** and generate one (free tier available).
+
+## Requirements
+
+- **Node ≥ 18** — uses the built-in global `fetch` + `AbortSignal.timeout`.
+- An `AUDIOLAB_API_KEY`. No ffmpeg, no native dependencies.
+
+## Tools
+
+Every tool takes **one audio source** — a public `url` **or** a local `path`:
+
+- `{ url: "https://…" }` — a public https URL the API fetches server-side.
+- `{ path: "./mix.wav" }` — a file on the machine running this server. Files up to **4 MB**
+  are sent inline; larger files (up to **50 MB**) upload over a one-shot signed URL, are
+  analysed, and are then deleted. *(Local `path` works only in this stdio server, not the
+  remote `/mcp` endpoint.)*
+
+| Tool | Returns |
+|---|---|
+| `analyze_loudness` | Integrated LUFS (EBU R128 / BS.1770-4), true-peak (dBTP), LRA, crest factor, stereo correlation, mono compatibility, tonal balance |
+| `check_target` | Pass/fail vs a delivery target (`spotify` / `apple-music` / `youtube` / `tidal` / `amazon-music` / `podcast` / `ebu-broadcast` / `atsc-broadcast`, or `target:"custom"` + `lufs`+`tp`), with per-metric deltas and an ffmpeg loudnorm fix command |
+| `analyze_timeseries` | Short-term LUFS over time + downsampled waveform peaks (`waveformPoints?`) |
+| `get_spectrum` | FFT magnitude data + 7-band energies + dominant band |
+| `analyze_voice` | Voice QA: speech/silence ratio, speaking rate, SNR, noise floor, room echo, sibilance & clipping risk |
+| `get_speech_segments` | Voiced regions with start/end + per-segment RMS (auto-trim, chapters) |
+| `index_signal` | Content-type guess, tags, clipping/silence regions, brightness & dynamics buckets |
+| `compare_loudness` | A/B on two sources (`urlA`/`pathA` + `urlB`/`pathB`), returns both results |
+| `analyze_batch` | One route over up to 20 sources in a single call (`urls` and/or `paths`), per-item ok/data/error. For folder QA, library indexing, or checking a whole release against a target. Each item meters as one call |
+
+Example asks to your AI:
+
+- *“Analyze the loudness of https://example.com/track.wav”* → `analyze_loudness` with `url`
+- *“Run loudness on ./master.wav”* → `analyze_loudness` with `path`
+- *“Does ./mix.mp3 pass Spotify?”* → `check_target` with `path` + `target:"spotify"`
+
+## Configuration (env)
+
+| Var | Default | Purpose |
+|---|---|---|
+| `AUDIOLAB_API_KEY` | — (required) | Your API key. |
+| `AUDIOLAB_API_BASE` | `https://audiolab.tools/v1` | Override the API base (must be `https://`). |
+| `AUDIOLAB_TIMEOUT_MS` | `60000` | Per-request timeout in milliseconds. |
+
+## Privacy
+
+Analysis happens on the AudioLab API, so the audio **does reach `audiolab.tools`** — a `url`
+is fetched server-side, and a local `path` is sent to the API (small files inline; larger
+files via a private one-shot signed upload that is deleted right after analysis). The API
+returns **numbers only** and does not retain your audio (see https://audiolab.tools/privacy).
+This package has no telemetry and writes nothing to disk. If audio must never leave the
+machine, don't use a hosted analyser.
+
+## Limits
+
+- Local files: up to **50 MB** (host bigger ones at a public URL).
+- One file per call (agents loop for many); one-shot (no streaming/realtime).
+- Rate and monthly limits are enforced by the API, per key.
+
+## Smoke test
+
+```sh
+node hosted-server.mjs --selftest   # verifies the 9 tools + guards; no network
+```
+
+## License
+
+MIT © Nathan Renting

package/hosted-server.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-// AudioLab HOSTED-mode MCP server. Exposes the 8 AudioLab tools to any MCP-capable
+// AudioLab HOSTED-mode MCP server. Exposes the 9 AudioLab tools to any MCP-capable
 // AI (Claude Desktop / Claude Code, Cursor, etc.) by calling the hosted API at
 // audiolab.tools/v1/*. It contains NO engine code, just HTTP calls, so it is safe to
 // distribute publicly without exposing the proprietary engine.
@@ -97,9 +97,9 @@ async function postRaw(route, buf, ct, extra, key) {
   });
 }
 
-// Larger local file → mint a signed upload URL, PUT the bytes to storage, then analyse by
-// objectPath. The objectPath is namespaced to this key server-side; only this key can read it.
-async function postUpload(route, buf, ct, fileName, extra, key) {
+// Mint a signed upload URL and PUT the bytes to storage; returns the objectPath.
+// The objectPath is namespaced to this key server-side; only this key can read it.
+async function uploadToStorage(buf, ct, key) {
   const k = requireKey(key);
   const origin = new URL(apiBase()).origin;
   const mint = await request(`${origin}/api/upload-url`, {
@@ -115,7 +115,46 @@ async function postUpload(route, buf, ct, fileName, extra, key) {
     throw new Error(`Upload to storage failed: ${String(e?.message || e)}`);
   }
   if (!put.ok) throw new Error(`Upload to storage failed (HTTP ${put.status}).`);
-  return call(route, { objectPath: mint.objectPath, fileName, ...extra }, k);
+  return mint.objectPath;
+}
+
+// Larger local file → upload to storage, then analyse by objectPath.
+async function postUpload(route, buf, ct, fileName, extra, key) {
+  const objectPath = await uploadToStorage(buf, ct, key);
+  return call(route, { objectPath, fileName, ...extra }, key);
+}
+
+// Read + size-check one local file for upload flows.
+async function readLocal(p) {
+  let buf;
+  try { buf = await readFile(p); }
+  catch (e) { throw new Error(`Could not read local file "${p}": ${e?.code || e?.message || e}`); }
+  if (!buf.length) throw new Error(`Local file is empty: "${p}".`);
+  if (buf.length > STORAGE_MAX) throw new Error(`"${p}" is ${(buf.length / 1048576).toFixed(1)} MB; max ${STORAGE_MAX / 1048576} MB per file. Host it at a public https URL instead.`);
+  return buf;
+}
+
+// Batch: one analysis route over many sources in a single /v1/batch call.
+// Local paths are uploaded to storage first (one-shot signed URLs), then the
+// whole set goes out as ONE call with urls + objectPaths. Max 20 combined,
+// matching the server-side cap; each item is metered as one call server-side.
+const BATCH_MAX = 20;
+async function batchSources({ urls = [], paths = [] }, endpoint, extra, key, local = false) {
+  if (paths.length && !local) throw new Error('Local file paths are only supported by the local (stdio) MCP server; use public https urls instead.');
+  const total = urls.length + paths.length;
+  if (!total) throw new Error('Provide urls (public https) and/or paths (local files).');
+  if (total > BATCH_MAX) throw new Error(`Batch too large: max ${BATCH_MAX} items per call. Split into smaller batches.`);
+  const objectPaths = [];
+  for (const p of paths) {
+    const buf = await readLocal(p);
+    objectPaths.push(await uploadToStorage(buf, ctForPath(p), key));
+  }
+  const args = Object.fromEntries(Object.entries(extra || {}).filter(([, v]) => v !== undefined && v !== null && v !== ''));
+  const body = { endpoint };
+  if (urls.length) body.urls = urls;
+  if (objectPaths.length) body.objectPaths = objectPaths;
+  if (Object.keys(args).length) body.args = args;
+  return call('batch', body, key);
 }
 
 // Resolve one audio source (url OR local path) to a route call. `local` gates path reads:
@@ -155,7 +194,7 @@ const sourceShape = (local) => local
   : { url: z.string().url().describe('Public https URL to the audio file.') };
 
 export function buildServer({ apiKey, local = false } = {}) {
-  const server = new McpServer({ name: 'audiolab', version: '0.2.0' }); // keep in sync with package.json
+  const server = new McpServer({ name: 'audiolab', version: '0.3.0' }); // keep in sync with package.json
   const toolNames = [];
   const tool = (name, def, handler) => { server.registerTool(name, def, handler); toolNames.push(name); };
   const src = sourceShape(local);
@@ -227,6 +266,25 @@ export function buildServer({ apiKey, local = false } = {}) {
     return { a, b };
   }));
 
+  // analyze_batch — one route over many sources, a single metered-per-item call.
+  const batchSrc = local
+    ? {
+        urls: z.array(z.string().url()).optional().describe('Public https URLs to audio files. Combined max 20 items with paths.'),
+        paths: z.array(z.string()).optional().describe('LOCAL audio file paths; each uploads over a one-shot signed URL, is analysed, then deleted. Combined max 20 items with urls.'),
+      }
+    : { urls: z.array(z.string().url()).min(1).max(20).describe('Public https URLs to audio files (max 20).') };
+  tool('analyze_batch', {
+    title: 'Batch: one analysis route over many files',
+    description: 'Run one analysis route over up to 20 audio sources in a single call. Returns per-item ok/data/error; each item is metered as one call. Routes: mixlab/analyze (default), mixlab/check-target, mixlab/timeseries, mixlab/spectrum, voicelab/qa, voicelab/segments, signallab/index. Use for folder QA, library indexing, or checking a whole release against a loudness target.' + (local ? ' Sources: public https urls and/or local file paths.' : ' Sources: public https urls.'),
+    inputSchema: {
+      ...batchSrc,
+      endpoint: z.string().optional().describe('Analysis route to run for every item (default mixlab/analyze).'),
+      target: z.string().optional().describe('For mixlab/check-target: preset id (spotify, ebu-broadcast, podcast, …) or "custom".'),
+      lufs: z.number().optional().describe('For target="custom": integrated LUFS target.'),
+      tp: z.number().optional().describe('For target="custom": max true-peak (dBTP).'),
+    },
+  }, wrap((i) => batchSources({ urls: i.urls || [], paths: i.paths || [] }, i.endpoint || 'mixlab/analyze', { target: i.target, lufs: i.lufs, tp: i.tp }, apiKey, local)));
+
   return { server, toolNames };
 }
 
@@ -236,9 +294,9 @@ const isMain = process.argv[1] && import.meta.url === pathToFileURL(process.argv
 
 if (isMain && process.argv.includes('--selftest')) {
   const assert = (await import('node:assert/strict')).default;
-  const expected = ['analyze_loudness', 'analyze_timeseries', 'analyze_voice', 'check_target', 'compare_loudness', 'get_spectrum', 'get_speech_segments', 'index_signal'];
-  assert.deepEqual(buildServer().toolNames.slice().sort(), expected, 'eight hosted tools (remote / url-only)');
-  assert.deepEqual(buildServer({ local: true }).toolNames.slice().sort(), expected, 'eight hosted tools (local / url+path)');
+  const expected = ['analyze_batch', 'analyze_loudness', 'analyze_timeseries', 'analyze_voice', 'check_target', 'compare_loudness', 'get_spectrum', 'get_speech_segments', 'index_signal'];
+  assert.deepEqual(buildServer().toolNames.slice().sort(), expected, 'nine hosted tools (remote / url-only)');
+  assert.deepEqual(buildServer({ local: true }).toolNames.slice().sort(), expected, 'nine hosted tools (local / url+path)');
 
   const prev = process.env.AUDIOLAB_API_KEY;
   delete process.env.AUDIOLAB_API_KEY;
@@ -249,9 +307,13 @@ if (isMain && process.argv.includes('--selftest')) {
   await assert.rejects(() => analyzeSource('mixlab/analyze', { path: '/etc/hostname' }, {}, 'al_live_selftest', false), /only supported by the local/, 'remote MCP never reads a server-side path');
   // url + path together is a usage error.
   await assert.rejects(() => analyzeSource('mixlab/analyze', { url: 'https://x/a.wav', path: '/tmp/a.wav' }, {}, 'al_live_selftest', true), /exactly one/, 'url+path together rejected');
+  // Batch guards fire BEFORE any network or filesystem work.
+  await assert.rejects(() => batchSources({ paths: ['/tmp/a.wav'] }, 'mixlab/analyze', {}, 'al_live_selftest', false), /only supported by the local/, 'remote batch never reads server-side paths');
+  await assert.rejects(() => batchSources({ urls: [], paths: [] }, 'mixlab/analyze', {}, 'al_live_selftest', true), /Provide urls/, 'empty batch rejected');
+  await assert.rejects(() => batchSources({ urls: Array.from({ length: 21 }, (_, n) => `https://x/${n}.wav`) }, 'mixlab/analyze', {}, 'al_live_selftest', false), /max 20/, 'oversized batch rejected before network');
   if (prev) process.env.AUDIOLAB_API_KEY = prev; else delete process.env.AUDIOLAB_API_KEY;
 
-  console.log('selftest ok · 8 tools (remote url-only + local url|path) + missing-key guard + remote-path refusal');
+  console.log('selftest ok · 9 tools (incl. analyze_batch) + missing-key guard + remote-path refusals + batch guards');
   process.exit(0);
 }
 

package/package.json

@@ -1,43 +1,47 @@
-{
-  "name": "@audiolabtools/mcp-server",
-  "version": "0.2.0",
-  "description": "MCP server for AudioLab — loudness (EBU R128 / BS.1770-4), true-peak, voice-quality, and signal analysis for AI agents (Claude, Cursor, any MCP client), via the AudioLab hosted API. No local audio engine required.",
-  "type": "module",
-  "bin": {
-    "audiolabtools-mcp-server": "hosted-server.mjs"
-  },
-  "files": ["hosted-server.mjs", "README.md"],
-  "keywords": [
-    "mcp",
-    "model-context-protocol",
-    "claude",
-    "audio",
-    "audio-analysis",
-    "loudness",
-    "lufs",
-    "ebu-r128",
-    "bs-1770",
-    "true-peak",
-    "voice-quality",
-    "audiolab"
-  ],
-  "homepage": "https://audiolab.tools/api",
-  "bugs": { "url": "https://audiolab.tools/api" },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/Audio-Launch/audiolab-tools.git",
-    "directory": "mcp"
-  },
-  "license": "MIT",
-  "author": "Nathan Renting",
-  "publishConfig": {
-    "access": "public"
-  },
-  "engines": {
-    "node": ">=18"
-  },
-  "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.29.0",
-    "zod": "^4.4.3"
-  }
-}
+{
+  "name": "@audiolabtools/mcp-server",
+  "version": "0.3.1",
+  "description": "MCP server for AudioLab \u2014 loudness (EBU R128 / BS.1770-4), true-peak, voice-quality, and signal analysis for AI agents (Claude, Cursor, any MCP client), via the AudioLab hosted API. No local audio engine required.",
+  "type": "module",
+  "bin": {
+    "audiolabtools-mcp-server": "hosted-server.mjs"
+  },
+  "files": [
+    "hosted-server.mjs",
+    "README.md"
+  ],
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "claude",
+    "audio",
+    "audio-analysis",
+    "loudness",
+    "lufs",
+    "ebu-r128",
+    "bs-1770",
+    "true-peak",
+    "voice-quality",
+    "audiolab"
+  ],
+  "homepage": "https://audiolab.tools/api",
+  "bugs": {
+    "url": "https://github.com/Audio-Launch/audiolab-mcp-server/issues"
+  },
+  "license": "MIT",
+  "author": "Nathan Renting",
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "zod": "^4.4.3"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Audio-Launch/audiolab-mcp-server.git"
+  }
+}