@audiolabtools/mcp-server 0.2.0 → 0.3.0

package/README.md

@@ -82,7 +82,7 @@ machine, don't use a hosted analyser.
 ## Smoke test
 
 ```sh
-node hosted-server.mjs --selftest   # verifies the 8 tools + guards; no network
+node hosted-server.mjs --selftest   # verifies the 9 tools + guards; no network
 ```
 
 ## License

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,43 @@
-{
-  "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.0",
+  "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://audiolab.tools/contact"
+  },
+  "license": "MIT",
+  "author": "Nathan Renting",
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "zod": "^4.4.3"
+  }
+}