@audiolabtools/mcp-server 0.4.4 → 0.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,5 +1,7 @@
1
1
  # @audiolabtools/mcp-server
2
2
 
3
+ [![Listed on mcpservers.org](https://mcpservers.org/badge.svg)](https://mcpservers.org/servers/audio-launch/audiolab-mcp-server)
4
+
3
5
  MCP ([Model Context Protocol](https://modelcontextprotocol.io)) server that gives any
4
6
  MCP-capable AI (Claude Desktop, Claude Code, Cursor, and others) ten audio-analysis
5
7
  tools, backed by the hosted **AudioLab** API. It is a thin HTTP client: **no local audio
@@ -9,26 +11,33 @@ and uploaded there (see [Privacy](#privacy)).
9
11
 
10
12
  ## Install
11
13
 
12
- Point your MCP client at the package via `npx` (nothing to install globally):
14
+ Point your MCP client at the package via `npx` (nothing to install globally). No account
15
+ needed for a first score:
13
16
 
14
17
  ```json
15
18
  {
16
19
  "mcpServers": {
17
20
  "audiolab": {
18
21
  "command": "npx",
19
- "args": ["-y", "@audiolabtools/mcp-server"],
20
- "env": { "AUDIOLAB_API_KEY": "al_live_yourkey" }
22
+ "args": ["-y", "@audiolabtools/mcp-server"]
21
23
  }
22
24
  }
23
25
  }
24
26
  ```
25
27
 
26
- Get a key: sign in at **https://audiolab.tools/account** and generate one (free tier available).
28
+ Without a key you are on the **keyless trial**: 20 calls a month and 3 a minute per IP address,
29
+ for single analyses of a URL or a local file up to 4 MB. Batches and larger files need a key.
30
+ A free key gives 1,000 calls and 2 GB a month, no card: sign in at **https://audiolab.tools/account**,
31
+ generate one, and add it:
32
+
33
+ ```json
34
+ "env": { "AUDIOLAB_API_KEY": "al_live_yourkey" }
35
+ ```
27
36
 
28
37
  ## Requirements
29
38
 
30
39
  - **Node ≥ 18**: uses the built-in global `fetch` + `AbortSignal.timeout`.
31
- - An `AUDIOLAB_API_KEY`. No ffmpeg, no native dependencies.
40
+ - Optionally an `AUDIOLAB_API_KEY` (see Install). No ffmpeg, no native dependencies.
32
41
 
33
42
  ## Tools
34
43
 
@@ -49,7 +58,7 @@ Every tool takes **one audio source**: a public `url` **or** a local `path`:
49
58
  | `analyze_voice` | Voice QA: speech/silence ratio, speaking rate, SNR, noise floor, pause energy, sibilance & clipping risk |
50
59
  | `get_speech_segments` | Voiced regions with start/end + per-segment RMS (auto-trim, chapters) |
51
60
  | `index_signal` | Content-type guess, tags, clipping/silence regions, brightness & dynamics buckets |
52
- | `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> |
61
+ | `analyze_profile` | One named question, `voice`, `master`, `provenance`, `dataset`, `environment`, `broadcast`, `loop`, `room` (reverberation from a clap, a pop, an impulse response or a sweep; pass `roomSource`), `chain` (lost packets) or `pitch` (where a voice sits and how clean it is), answered with only the lenses it needs. These ten 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> |
53
62
  | `compare_loudness` | A/B on two sources (`urlA`/`pathA` + `urlB`/`pathB`), returns both results |
54
63
  | `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 |
55
64
 
@@ -65,7 +74,7 @@ Example asks to your AI:
65
74
 
66
75
  | Var | Default | Purpose |
67
76
  |---|---|---|
68
- | `AUDIOLAB_API_KEY` | – (required) | Your API key. |
77
+ | `AUDIOLAB_API_KEY` | – (optional) | Your API key. Without it: the keyless trial (20 calls a month per IP, no batches, files up to 4 MB). |
69
78
  | `AUDIOLAB_API_BASE` | `https://audiolab.tools/v1` | Override the API base (must be `https://`). |
70
79
  | `AUDIOLAB_TIMEOUT_MS` | `330000` | Per-request timeout in milliseconds (long files and batches stream server-side and can legitimately take minutes). |
71
80
 
@@ -87,7 +96,7 @@ agents.
87
96
  - Local files: up to **150 MB** (host bigger ones at a public URL).
88
97
  - 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.
89
98
  - One file per call (agents loop for many); one-shot (no streaming/realtime).
90
- - Rate and monthly limits are enforced by the API, per key.
99
+ - Rate and monthly limits are enforced by the API, per key (per IP address on the keyless trial).
91
100
 
92
101
  ## Smoke test
93
102
 
package/error-docs.mjs CHANGED
@@ -6,9 +6,9 @@
6
6
  export const DOCS_ERRORS_URL = 'https://audiolab.tools/docs/errors';
7
7
 
8
8
  export const KNOWN_CODES = [
9
- 'invalid_api_key', 'rate_limited', 'quota_exceeded', 'data_quota_exceeded', 'profile_requires_paid_plan', 'file_too_large', 'track_too_long', 'unsupported_format',
9
+ 'invalid_api_key', 'rate_limited', 'quota_exceeded', 'data_quota_exceeded', 'profile_requires_paid_plan', 'file_too_large', 'track_too_long', 'unsupported_format', 'room_not_measurable',
10
10
  'url_not_allowed', 'url_fetch_failed', 'invalid_json', 'missing_input', 'invalid_parameter', 'batch_too_large', 'upload_not_found', 'unknown_endpoint', 'method_not_allowed',
11
- 'storage_unavailable', 'analysis_error', 'missing_api_key', 'api_timeout', 'api_unreachable', 'invalid_input',
11
+ 'storage_unavailable', 'analysis_error', 'missing_api_key', 'api_timeout', 'api_unreachable', 'voice_minutes_exhausted', 'service_paused', 'invalid_input',
12
12
  ];
13
13
 
14
14
  export const docsUrl = (code) => `${DOCS_ERRORS_URL}#${KNOWN_CODES.includes(code) ? code : 'analysis_error'}`;
package/hosted-server.mjs CHANGED
@@ -14,13 +14,16 @@
14
14
  // a remote server must NEVER read a path off its own filesystem, so `{ path }` is
15
15
  // rejected and only `{ url }` is accepted.
16
16
  //
17
- // Requires an API key (self-serve: sign in at https://audiolab.tools/account and generate one).
17
+ // Works without a key since 0.5.0 (27 Oct 2026): single analyses of a URL or a local file up to 4 MB go out
18
+ // without an Authorization header and land on the API's keyless trial (20 calls a month, 3 a minute, per IP),
19
+ // the same as a curl without a key. Batches and larger files need a key, because /v1/batch and the storage
20
+ // upload are tied to one. A free key (sign in at https://audiolab.tools/account) gives 1,000 calls a month.
18
21
  // Config in Claude Desktop's claude_desktop_config.json:
19
22
  // { "mcpServers": { "audiolab": {
20
23
  // "command": "npx", "args": ["-y", "@audiolabtools/mcp-server"],
21
24
  // "env": { "AUDIOLAB_API_KEY": "al_live_yourkey" } } } }
22
25
  //
23
- // Env: AUDIOLAB_API_KEY (required at call time for stdio mode), AUDIOLAB_API_BASE
26
+ // Env: AUDIOLAB_API_KEY (optional in stdio mode, see above), AUDIOLAB_API_BASE
24
27
  // (default https://audiolab.tools/v1, must be https), AUDIOLAB_TIMEOUT_MS (default 330000).
25
28
  // Smoke test (no network): node hosted-server.mjs --selftest
26
29
 
@@ -68,9 +71,15 @@ const apiBase = () => {
68
71
  // made the client give up while the server was still happily working.
69
72
  const timeoutMs = () => Number(process.env.AUDIOLAB_TIMEOUT_MS) || 330_000;
70
73
 
71
- function requireKey(key) {
72
- const k = key || process.env.AUDIOLAB_API_KEY;
73
- if (!k) throw new Error('AUDIOLAB_API_KEY is not set. Get a key at https://audiolab.tools/account.');
74
+ // The key if there is one. Without one, single analyses go to the keyless trial; the remote /mcp endpoint
75
+ // always passes a key (api/mcp.mjs refuses a request without one before it gets here).
76
+ const keyOf = (key) => key || process.env.AUDIOLAB_API_KEY || null;
77
+ const auth = (k) => (k ? { authorization: `Bearer ${k}` } : {});
78
+
79
+ // Batches and the storage upload are tied to a key server-side, so these refuse before any network call.
80
+ function requireKey(key, what) {
81
+ const k = keyOf(key);
82
+ if (!k) throw new Error(`AUDIOLAB_API_KEY is not set. ${what} need a key; a free one gives 1,000 calls a month: https://audiolab.tools/account. Single files up to 4 MB and URLs work without one.`);
74
83
  return k;
75
84
  }
76
85
 
@@ -102,9 +111,8 @@ async function request(url, { method = 'POST', headers = {}, body } = {}) {
102
111
 
103
112
  // key defaults to the env var (stdio mode); the remote endpoint passes a per-request key.
104
113
  export async function call(route, body, key = process.env.AUDIOLAB_API_KEY) {
105
- const k = requireKey(key);
106
114
  return request(`${apiBase()}/${route}`, {
107
- headers: { 'content-type': 'application/json', authorization: `Bearer ${k}` },
115
+ headers: { 'content-type': 'application/json', ...auth(keyOf(key)) },
108
116
  body: JSON.stringify(body),
109
117
  });
110
118
  }
@@ -112,12 +120,11 @@ export async function call(route, body, key = process.env.AUDIOLAB_API_KEY) {
112
120
  // Small local file → raw audio body straight to /v1 (fast, no storage round-trip).
113
121
  // Tool extras (target/lufs/tp/waveformPoints/fileName) ride along as query params.
114
122
  async function postRaw(route, buf, ct, extra, key) {
115
- const k = requireKey(key);
116
123
  const qs = new URLSearchParams();
117
124
  for (const [name, v] of Object.entries(extra || {})) if (v !== undefined && v !== null && v !== '') qs.set(name, String(v));
118
125
  const q = qs.toString();
119
126
  return request(`${apiBase()}/${route}${q ? `?${q}` : ''}`, {
120
- headers: { 'content-type': ct, authorization: `Bearer ${k}` },
127
+ headers: { 'content-type': ct, ...auth(keyOf(key)) },
121
128
  body: buf,
122
129
  });
123
130
  }
@@ -125,7 +132,7 @@ async function postRaw(route, buf, ct, extra, key) {
125
132
  // Mint a signed upload URL and PUT the bytes to storage; returns the objectPath.
126
133
  // The objectPath is namespaced to this key server-side; only this key can read it.
127
134
  async function uploadToStorage(buf, ct, key) {
128
- const k = requireKey(key);
135
+ const k = requireKey(key, 'Files over 4 MB');
129
136
  const origin = new URL(apiBase()).origin;
130
137
  const mint = await request(`${origin}/api/upload-url`, {
131
138
  headers: { 'content-type': 'application/json', authorization: `Bearer ${k}` },
@@ -169,6 +176,7 @@ async function batchSources({ urls = [], paths = [] }, endpoint, extra, key, loc
169
176
  const total = urls.length + paths.length;
170
177
  if (!total) throw new Error('Provide urls (public https) and/or paths (local files).');
171
178
  if (total > BATCH_MAX) throw new Error(`Batch too large: max ${BATCH_MAX} items per call. Split into smaller batches.`);
179
+ requireKey(key, 'Batches');
172
180
  const objectPaths = [];
173
181
  for (const p of paths) {
174
182
  const buf = await readLocal(p);
@@ -280,20 +288,25 @@ export function buildServer({ apiKey, local = false } = {}) {
280
288
  + 'dataset (which of these files are good enough, and why not the rest), '
281
289
  + 'environment (what is in this space, and what kind of noise is it), '
282
290
  + 'broadcast (does this file meet the delivery spec), '
283
- + 'loop (is this loop clean, on the grid, and safe to drop in a DAW). '
284
- + 'basic is the free tier; the other seven need a paid plan. '
291
+ + 'loop (is this loop clean, on the grid, and safe to drop in a DAW), '
292
+ + 'room (how long does this room ring per octave band, and is there a flutter echo; needs a recording of one clap, a balloon pop, an impulse response or a sweep), '
293
+ + 'chain (did this recording lose packets on its way: gaps of digital silence), '
294
+ + 'pitch (where does this voice sit, how much does it move, how clean is it). '
295
+ + 'basic is the free tier; the other ten need a paid plan. '
285
296
  + 'Results are keyed by stable lens id. Only the analysis passes the profile needs are run. '
286
297
  + 'Set series:true to also get the curves, the per-block lanes and the per-phrase values,'
287
298
  + 'a much larger payload, so leave it off unless you are going to read them.'
288
299
  + srcDoc,
289
300
  inputSchema: {
290
301
  ...src,
291
- profile: z.enum(['basic', 'voice', 'master', 'provenance', 'dataset', 'environment', 'broadcast', 'loop'])
302
+ profile: z.enum(['basic', 'voice', 'master', 'provenance', 'dataset', 'environment', 'broadcast', 'loop', 'room', 'chain', 'pitch'])
292
303
  .describe('Which question to answer.'),
293
304
  series: z.boolean().optional()
294
305
  .describe('Include time series, per-block lanes and per-phrase arrays. Off by default.'),
306
+ roomSource: z.enum(['clap', 'balloon', 'impulse', 'sweep']).optional()
307
+ .describe('For the room profile: how the recording was made. clap (default): one clap; balloon: one pop; impulse: the file is an impulse response; sweep: the file holds the sweep of the engine as the room returned it.'),
295
308
  },
296
- }, wrap((i) => analyzeSource('analyze/profile', i, { profile: i.profile, series: i.series === true }, apiKey, local)));
309
+ }, wrap((i) => analyzeSource('analyze/profile', i, { profile: i.profile, series: i.series === true, ...(i.roomSource ? { roomSource: i.roomSource } : {}) }, apiKey, local)));
297
310
 
298
311
  // compare_loudness: two independent sources, each a url or (local only) a path.
299
312
  const cmp = local
@@ -353,7 +366,21 @@ if (isMain && process.argv.includes('--selftest')) {
353
366
 
354
367
  const prev = process.env.AUDIOLAB_API_KEY;
355
368
  delete process.env.AUDIOLAB_API_KEY;
356
- await assert.rejects(() => call('mixlab/analyze', { url: 'https://example.com/a.wav' }), /AUDIOLAB_API_KEY/, 'refuses without a key (before any fetch)');
369
+ // Without a key: a single analysis goes out with no Authorization header (the keyless trial); a batch refuses before any fetch.
370
+ {
371
+ const realFetch = globalThis.fetch;
372
+ let sent;
373
+ globalThis.fetch = async (_url, init) => { sent = init.headers; return new Response('{"ok":true}', { status: 200 }); };
374
+ try {
375
+ await call('mixlab/analyze', { url: 'https://example.com/a.wav' });
376
+ assert.ok(sent && !('authorization' in sent), 'keyless call sends no Authorization header');
377
+ await call('mixlab/analyze', { url: 'https://example.com/a.wav' }, 'al_live_selftest');
378
+ assert.equal(sent.authorization, 'Bearer al_live_selftest', 'a key still goes out as Bearer');
379
+ sent = undefined;
380
+ await assert.rejects(() => batchSources({ urls: ['https://example.com/a.wav'] }, 'mixlab/analyze', {}, undefined, false), /AUDIOLAB_API_KEY is not set\. Batches need a key/, 'batch refuses without a key');
381
+ assert.equal(sent, undefined, 'the batch refusal happens before any fetch');
382
+ } finally { globalThis.fetch = realFetch; }
383
+ }
357
384
 
358
385
  // Elke fout die de gebruiker te zien krijgt draagt één regel Docs met een vaste code (mcp/error-docs.mjs; de uitleg staat op /docs/errors).
359
386
  {
@@ -391,7 +418,7 @@ if (isMain && process.argv.includes('--selftest')) {
391
418
  if (e?.code !== 'ERR_MODULE_NOT_FOUND') throw e;
392
419
  }
393
420
 
394
- console.log(`selftest ok · v${PKG_VERSION} · ${expected.length} tools (incl. analyze_profile) + missing-key guard + remote-path refusals + batch guards`);
421
+ console.log(`selftest ok · v${PKG_VERSION} · ${expected.length} tools (incl. analyze_profile) + keyless trial and batch-key guard + remote-path refusals + batch guards`);
395
422
  process.exit(0);
396
423
  }
397
424
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@audiolabtools/mcp-server",
3
- "version": "0.4.4",
3
+ "version": "0.5.0",
4
4
  "mcpName": "tools.audiolab/audiolab",
5
5
  "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.",
6
6
  "type": "module",