@audiolabtools/mcp-server 0.3.2 → 0.4.0

package/README.md

@@ -1,91 +1,95 @@
-# @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
+# @audiolabtools/mcp-server
+
+MCP ([Model Context Protocol](https://modelcontextprotocol.io)) server that gives any
+MCP-capable AI (Claude Desktop, Claude Code, Cursor, and others) ten 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 |
+| `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 |
+| `analyze_profile` | One named question, `voice`, `master`, `provenance`, `dataset`, `environment`, `broadcast` or `loop`, answered with only the lenses it needs. These seven need a paid plan; the free tier gets the `basic` profile, keyed by stable lens id. Add `series:true` for the curves, per-block lanes and per-phrase values. Carries a `note` when the profile’s voice lenses land on non-speech material. Full catalogue: <https://audiolab.tools/lenses> |
+| `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`
+- *“Is this take usable?”* → `analyze_profile` with `profile:"voice"`
+- *“Has this file been re-encoded, and is it all one source?”* → `analyze_profile` with `profile:"provenance"`
+- *“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` | `330000` | Per-request timeout in milliseconds (long files and batches stream server-side and can legitimately take minutes). |
+
+## 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).
+- Duration: loudness routes (`analyze_loudness`, `check_target`, `analyze_timeseries`, `get_spectrum`) handle **long files** (podcast episodes, full sets, up to ~3 h) via server-side streaming; voice/signal routes are limited to ~7 minutes.
+- 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 10 tools + guards; no network
+```
+
+## License
+
+MIT © Nathan Renting

package/hosted-server.mjs

@@ -1,16 +1,16 @@
 #!/usr/bin/env node
-// AudioLab HOSTED-mode MCP server. Exposes the 9 AudioLab tools to any MCP-capable
+// AudioLab HOSTED-mode MCP server. Exposes the 10 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.
 //
 // Two consumers share buildServer():
 //   1. This file run directly = a stdio server (the npm package @audiolabtools/mcp-server),
-//      reading the key from AUDIOLAB_API_KEY. Started with { local: true } — so it can also
+//      reading the key from AUDIOLAB_API_KEY. Started with { local: true }, so it can also
 //      analyse a LOCAL file via `{ path }` (small files POST raw; larger files are PUT to
 //      storage via a signed URL and analysed by objectPath). Nothing is exposed publicly.
 //   2. api/mcp.mjs = the remote streamable-HTTP endpoint at /mcp, which passes the
-//      per-request Bearer key via buildServer({ apiKey }). local defaults to FALSE there —
+//      per-request Bearer key via buildServer({ apiKey }). local defaults to FALSE there,
 //      a remote server must NEVER read a path off its own filesystem, so `{ path }` is
 //      rejected and only `{ url }` is accepted.
 //
@@ -21,7 +21,7 @@
 //       "env": { "AUDIOLAB_API_KEY": "al_live_yourkey" } } } }
 //
 // Env: AUDIOLAB_API_KEY (required at call time for stdio mode), AUDIOLAB_API_BASE
-// (default https://audiolab.tools/v1, must be https), AUDIOLAB_TIMEOUT_MS (default 60000).
+// (default https://audiolab.tools/v1, must be https), AUDIOLAB_TIMEOUT_MS (default 330000).
 // Smoke test (no network): node hosted-server.mjs --selftest
 
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
@@ -36,11 +36,21 @@ import { z } from 'zod';
 // package.json" comment next to it. It drifted anyway: the package shipped 0.3.1
 // while every initialize response still announced 0.3.0. Read it instead, so the
 // comment cannot be ignored and the two cannot disagree.
-const { version: PKG_VERSION } = createRequire(import.meta.url)('./package.json');
+// ponytail: the npm package always ships package.json, the Vercel bundle of api/mcp.mjs
+// never does (includeFiles skips it too). A throw here took the remote /mcp down at load
+// time from 11 Aug to 14 Sep, so the hosted copy reports 'hosted' instead of crashing.
+const PKG_VERSION = (() => {
+  try { return createRequire(import.meta.url)('./package.json').version; } catch { return 'hosted'; }
+})();
 
 // Vercel serverless caps a raw request body at ~4.5 MB, so small files POST directly and
 // larger ones go through the signed-URL storage flow. The bucket policy caps at 50 MB.
 const RAW_MAX = 4 * 1024 * 1024;
+// Dit bestand is het ENIGE dat npm meestuurt, dus het mag niets buiten zijn eigen map
+// importeren. `MAX_STORAGE_BYTES` uit ../lib/limits.mjs stond hier even, en daarmee
+// crashte het gepubliceerde pakket bij de eerste import: die map wordt niet meegeleverd.
+// De waarde staat daarom weer hier, en de zelfcheck hieronder houdt hem tegen limits.mjs aan
+// zolang die bereikbaar is, dus in de monorepo faalt drift alsnog.
 const STORAGE_MAX = 50 * 1024 * 1024;
 
 // Read env at CALL time (not module load) so the key can be injected by the MCP host
@@ -52,7 +62,10 @@ const apiBase = () => {
   return base;
 };
 
-const timeoutMs = () => Number(process.env.AUDIOLAB_TIMEOUT_MS) || 60_000;
+// Just above the API's own 300 s ceiling: since long files stream server-side
+// (a 25-min track ≈ 10-30 s, batches of them add up), a 60 s client default
+// made the client give up while the server was still happily working.
+const timeoutMs = () => Number(process.env.AUDIOLAB_TIMEOUT_MS) || 330_000;
 
 function requireKey(key) {
   const k = key || process.env.AUDIOLAB_API_KEY;
@@ -196,7 +209,7 @@ const wrap = (fn) => async (input) => {
 const sourceShape = (local) => local
   ? {
       url: z.string().url().optional().describe('Public https URL to the audio file. Provide exactly one of url or path.'),
-      path: z.string().optional().describe('Path to a LOCAL audio file on this machine — analysed without hosting it publicly (files up to 4 MB are sent inline; larger ones up to 50 MB upload over a one-shot signed URL). Provide exactly one of url or path.'),
+      path: z.string().optional().describe('Path to a LOCAL audio file on this machine, analysed without hosting it publicly (files up to 4 MB are sent inline; larger ones up to 50 MB upload over a one-shot signed URL). Provide exactly one of url or path.'),
     }
   : { url: z.string().url().describe('Public https URL to the audio file.') };
 
@@ -227,7 +240,7 @@ export function buildServer({ apiKey, local = false } = {}) {
 
   tool('get_spectrum', {
     title: 'FFT spectrum data',
-    description: 'Frequency-domain magnitude data (paired frequency/magnitude arrays) plus energies in 7 standard bands (sub/bass/lowMid/mid/highMid/presence/air) and the dominant band. For spectrum-analyzer UIs and tonal-balance analysis.' + srcDoc,
+    description: 'Frequency-domain magnitude data (paired frequency/magnitude arrays) plus energies in 7 standard bands (sub/bass/lowMid/mid/highMid/presence/air). There is no dominant-band field in the response. For spectrum-analyzer UIs and tonal-balance analysis.' + srcDoc,
     inputSchema: src,
   }, wrap((i) => analyzeSource('mixlab/spectrum', i, {}, apiKey, local)));
 
@@ -247,9 +260,37 @@ export function buildServer({ apiKey, local = false } = {}) {
     title: 'Index a signal (SignalLab)',
     description: 'A metadata index for any audio file: content-type guess (voice/music/mixed/noise/silence) with confidence, brightness & dynamics buckets, dominant band, clipping/silence regions, and tag suggestions. For triage or auto-tagging a library.' + srcDoc,
     inputSchema: src,
-  }, wrap((i) => analyzeSource('signallab/index', i, {}, apiKey, local)));
+  }, wrap((i) => analyzeSource('signallab', i, {}, apiKey, local)));
+
+  // analyze_profile: the lens registry as one tool. A model that knows what it
+  // is looking for names the question, not forty field names; a model that does
+  // not can read the profiles here and pick one.
+  tool('analyze_profile', {
+    title: 'Analyse against a profile',
+    description:
+      'Measure a file against a named working set of lenses and get back only what that question needs. '
+      + 'Profiles: voice (is this take usable, and which phrase is the problem), '
+      + 'master (will this translate to real platforms and speakers), '
+      + 'provenance (what has been done to this file, and is it all one source), '
+      + 'dataset (which of these files are good enough, and why not the rest), '
+      + 'environment (what is in this space, and what kind of noise is it), '
+      + 'broadcast (does this file meet the delivery spec), '
+      + 'loop (is this loop clean, on the grid, and safe to drop in a DAW). '
+      + 'basic is the free tier; the other seven need a paid plan. '
+      + 'Results are keyed by stable lens id. Only the analysis passes the profile needs are run. '
+      + 'Set series:true to also get the curves, the per-block lanes and the per-phrase values,'
+      + 'a much larger payload, so leave it off unless you are going to read them.'
+      + srcDoc,
+    inputSchema: {
+      ...src,
+      profile: z.enum(['basic', 'voice', 'master', 'provenance', 'dataset', 'environment', 'broadcast', 'loop'])
+        .describe('Which question to answer.'),
+      series: z.boolean().optional()
+        .describe('Include time series, per-block lanes and per-phrase arrays. Off by default.'),
+    },
+  }, wrap((i) => analyzeSource('analyze/profile', i, { profile: i.profile, series: i.series === true }, apiKey, local)));
 
-  // compare_loudness — two independent sources, each a url or (local only) a path.
+  // compare_loudness: two independent sources, each a url or (local only) a path.
   const cmp = local
     ? {
         urlA: z.string().url().optional().describe('First source URL (e.g. master). Provide urlA or pathA.'),
@@ -273,7 +314,7 @@ export function buildServer({ apiKey, local = false } = {}) {
     return { a, b };
   }));
 
-  // analyze_batch — one route over many sources, a single metered-per-item call.
+  // 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.'),
@@ -301,9 +342,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_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 expected = ['analyze_batch', 'analyze_loudness', 'analyze_profile', 'analyze_timeseries', 'analyze_voice', 'check_target', 'compare_loudness', 'get_spectrum', 'get_speech_segments', 'index_signal'];
+  assert.deepEqual(buildServer().toolNames.slice().sort(), expected, 'ten hosted tools (remote / url-only)');
+  assert.deepEqual(buildServer({ local: true }).toolNames.slice().sort(), expected, 'ten hosted tools (local / url+path)');
 
   const prev = process.env.AUDIOLAB_API_KEY;
   delete process.env.AUDIOLAB_API_KEY;
@@ -326,7 +367,17 @@ if (isMain && process.argv.includes('--selftest')) {
   assert.equal(typeof PKG_VERSION, 'string', 'version resolves from package.json');
   assert.match(PKG_VERSION, /^\d+\.\d+\.\d+/, 'version looks like a semver');
 
-  console.log(`selftest ok · v${PKG_VERSION} · 9 tools (incl. analyze_batch) + missing-key guard + remote-path refusals + batch guards`);
+  // De opslaggrens staat hier hardgecodeerd omdat het pakket zichzelf moet kunnen draaien.
+  // In de monorepo is limits.mjs er wel, en dan moet hij gelijk zijn; in het gepubliceerde
+  // pakket ontbreekt hij en slaan we over. Zo kan de waarde niet stil uit elkaar lopen.
+  try {
+    const { MAX_STORAGE_BYTES } = await import('../lib/limits.mjs');
+    assert.equal(STORAGE_MAX, MAX_STORAGE_BYTES, 'STORAGE_MAX loopt uit de pas met lib/limits.mjs');
+  } catch (e) {
+    if (e?.code !== 'ERR_MODULE_NOT_FOUND') throw e;
+  }
+
+  console.log(`selftest ok · v${PKG_VERSION} · ${expected.length} tools (incl. analyze_profile) + missing-key guard + remote-path refusals + batch guards`);
   process.exit(0);
 }
 

package/package.json

@@ -1,48 +1,48 @@
-{
-  "name": "@audiolabtools/mcp-server",
-  "version": "0.3.2",
-  "mcpName": "tools.audiolab/audiolab",
-  "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"
-  }
-}
+{
+  "name": "@audiolabtools/mcp-server",
+  "version": "0.4.0",
+  "mcpName": "tools.audiolab/audiolab",
+  "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://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"
+  }
+}