@audiolabtools/mcp-server 0.4.2 → 0.4.4

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/LICENSE CHANGED
@@ -1,21 +1,21 @@
1
- MIT License
2
-
3
- Copyright (c) 2026 Nathan Renting
4
-
5
- Permission is hereby granted, free of charge, to any person obtaining a copy
6
- of this software and associated documentation files (the "Software"), to deal
7
- in the Software without restriction, including without limitation the rights
8
- to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
- copies of the Software, and to permit persons to whom the Software is
10
- furnished to do so, subject to the following conditions:
11
-
12
- The above copyright notice and this permission notice shall be included in all
13
- copies or substantial portions of the Software.
14
-
15
- THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
- IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
- FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
- AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
- LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
- OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
- SOFTWARE.
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Nathan Renting
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -3,8 +3,9 @@
3
3
  MCP ([Model Context Protocol](https://modelcontextprotocol.io)) server that gives any
4
4
  MCP-capable AI (Claude Desktop, Claude Code, Cursor, and others) ten audio-analysis
5
5
  tools, backed by the hosted **AudioLab** API. It is a thin HTTP client: **no local audio
6
- engine, no ffmpeg, nothing to compile.** It can analyse a **public URL** or a **local file**
7
- on your machine.
6
+ engine, no ffmpeg, nothing to compile.** It can measure a **public URL** or a **local file**
7
+ on your machine, but the measuring always happens on the hosted API: the file is read here
8
+ and uploaded there (see [Privacy](#privacy)).
8
9
 
9
10
  ## Install
10
11
 
@@ -71,11 +72,15 @@ Example asks to your AI:
71
72
  ## Privacy
72
73
 
73
74
  Analysis happens on the AudioLab API, so the audio **does reach `audiolab.tools`**: a `url`
74
- is fetched server-side, and a local `path` is sent to the API (small files inline; larger
75
- files via a private one-shot signed upload that is deleted right after analysis). The API
76
- returns **numbers only** and does not retain your audio (see https://audiolab.tools/privacy).
77
- This package has no telemetry and writes nothing to disk. If audio must never leave the
78
- machine, don't use a hosted analyser.
75
+ is fetched server-side, and a local `path` is read here and uploaded to the API (small
76
+ files in the request body; larger files via a private one-shot signed upload into EU
77
+ storage). The API returns **numbers only** and does not keep your audio: a direct request
78
+ is decoded and discarded inside the request, and a signed upload is swept from storage
79
+ within the hour (see https://audiolab.tools/privacy). This package has no telemetry and
80
+ writes nothing to disk. There is no offline mode, and the engine is not published as an
81
+ installable package. If audio must never leave the machine, don't use a hosted analyser;
82
+ the in-browser labs on the website measure on-device, but they are for people, not for
83
+ agents.
79
84
 
80
85
  ## Limits
81
86
 
package/error-docs.mjs ADDED
@@ -0,0 +1,34 @@
1
+ // De foutcodes van AudioLab voor de MCP-servers, met de link naar de uitleg.
2
+ //
3
+ // De bron is lib/error-codes.mjs in de site-repo (daar staat per code de oorzaak en de oplossing, en daaruit komt de pagina /docs/errors). Dit bestand moet in het npm-pakket zelf zitten,
4
+ // want een pakket importeert niets buiten mcp/. scripts/error-docs-check.mjs bewaakt dat de twee lijsten gelijk blijven.
5
+
6
+ export const DOCS_ERRORS_URL = 'https://audiolab.tools/docs/errors';
7
+
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',
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',
12
+ ];
13
+
14
+ export const docsUrl = (code) => `${DOCS_ERRORS_URL}#${KNOWN_CODES.includes(code) ? code : 'analysis_error'}`;
15
+
16
+ /** De code bij een fout: die van de API als hij er is, anders uit de tekst van de fout. Onbekend wordt analysis_error. */
17
+ export function codeFor(e) {
18
+ if (e?.code && KNOWN_CODES.includes(e.code)) return e.code;
19
+ const m = String(e?.message || e || '');
20
+ if (/AUDIOLAB_API_KEY is not set/i.test(m)) return 'missing_api_key';
21
+ if (/timed out/i.test(m)) return 'api_timeout';
22
+ if (/Could not reach the AudioLab API/i.test(m)) return 'api_unreachable';
23
+ if (/Upload to storage failed|Could not prepare the upload/i.test(m)) return 'storage_unavailable';
24
+ if (/Batch too large/i.test(m)) return 'batch_too_large';
25
+ if (/Unknown target|AUDIOLAB_API_BASE must/i.test(m)) return 'invalid_parameter';
26
+ if (/file too large|; max \d+(\.\d+)? MB per file/i.test(m)) return 'file_too_large';
27
+ if (/Could not read local file|Local file is empty|Local file paths are only supported|Provide (a url|urls|exactly one)/i.test(m)) return 'invalid_input';
28
+ if (/could not decode|decode failed|Invalid data found/i.test(m)) return 'unsupported_format';
29
+ if (/could not fetch|ENOTFOUND/i.test(m)) return 'url_fetch_failed';
30
+ return 'analysis_error';
31
+ }
32
+
33
+ /** De fouttekst voor een tool-resultaat: de melding zoals hij was, met één regel Docs eronder. */
34
+ export const withDocs = (message, e) => `${message}\nDocs: ${docsUrl(codeFor(e))}`;
package/hosted-server.mjs CHANGED
@@ -31,6 +31,7 @@ import { basename } from 'node:path';
31
31
  import { pathToFileURL } from 'node:url';
32
32
  import { createRequire } from 'node:module';
33
33
  import { z } from 'zod';
34
+ import { withDocs } from './error-docs.mjs';
34
35
 
35
36
  // The version reported over MCP used to be a literal with a "keep in sync with
36
37
  // package.json" comment next to it. It drifted anyway: the package shipped 0.3.1
@@ -91,7 +92,11 @@ async function request(url, { method = 'POST', headers = {}, body } = {}) {
91
92
  let json;
92
93
  try { json = JSON.parse(text); }
93
94
  catch { throw new Error(res.ok ? 'AudioLab API returned a non-JSON response.' : `AudioLab API error ${res.status}.`); }
94
- if (!res.ok) throw new Error(String(json?.error?.message || json?.error || `API returned ${res.status}`));
95
+ if (!res.ok) {
96
+ const err = new Error(String(json?.error?.message || json?.error || `API returned ${res.status}`));
97
+ if (json?.error?.code) err.code = json.error.code; // de vaste foutcode van de API; error-docs.mjs maakt er de Docs-regel van
98
+ throw err;
99
+ }
95
100
  return json;
96
101
  }
97
102
 
@@ -201,7 +206,7 @@ async function analyzeSource(route, { url, path } = {}, extra = {}, key, local =
201
206
  const asContent = (obj) => ({ content: [{ type: 'text', text: JSON.stringify(obj) }] });
202
207
  const wrap = (fn) => async (input) => {
203
208
  try { return asContent(await fn(input)); }
204
- catch (e) { return { isError: true, content: [{ type: 'text', text: String(e?.message || e) }] }; }
209
+ catch (e) { return { isError: true, content: [{ type: 'text', text: withDocs(String(e?.message || e), e) }] }; }
205
210
  };
206
211
 
207
212
  // Input source shape. Remote (url-only) keeps the original required url; local adds an
@@ -209,7 +214,7 @@ const wrap = (fn) => async (input) => {
209
214
  const sourceShape = (local) => local
210
215
  ? {
211
216
  url: z.string().url().optional().describe('Public https URL to the audio file. Provide exactly one of url or path.'),
212
- 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 150 MB upload over a signed URL). Provide exactly one of url or path.'),
217
+ path: z.string().optional().describe('Path to a LOCAL audio file on this machine. It is read here and uploaded to the AudioLab API for measuring, so you do not need to host it publicly (files up to 4 MB go in the request body; larger ones, up to 150 MB, upload over a signed URL and are swept from storage within the hour). Provide exactly one of url or path.'),
213
218
  }
214
219
  : { url: z.string().url().describe('Public https URL to the audio file.') };
215
220
 
@@ -246,19 +251,19 @@ export function buildServer({ apiKey, local = false } = {}) {
246
251
 
247
252
  tool('analyze_voice', {
248
253
  title: 'Analyze voice quality (VoiceLab)',
249
- description: 'Speech-quality QA for a voice recording: speech/silence ratio, speaking-rate label, signal-to-noise, noise floor, pause energy, sibilance risk, clipping severity. Gates a voice take.' + srcDoc,
254
+ description: 'Speech-quality QA for a voice recording: speech/silence ratio, speaking-rate label, signal-to-noise, noise floor, pause energy, sibilance risk, clipping severity. Gates a voice take. Status: levels, SNR, noise floor and clipping are validated against known signals; speaking rate, background scene and intelligibility are proxies, and the pause-energy field is not a reverb measure (https://audiolab.tools/lenses).' + srcDoc,
250
255
  inputSchema: src,
251
256
  }, wrap((i) => analyzeSource('voicelab/qa', i, {}, apiKey, local)));
252
257
 
253
258
  tool('get_speech_segments', {
254
259
  title: 'Speech segments (VoiceLab)',
255
- description: 'List voiced speech regions with start/end timestamps and per-segment RMS. For auto-trim, chapter generation, and speaker-turn detection. RMS-based voice-activity detection, not speaker diarization.' + srcDoc,
260
+ description: 'List voiced speech regions with start/end timestamps and per-segment RMS. For auto-trim and chapter generation. RMS-based voice-activity detection: it finds where speech is, not who is speaking, and it does not detect speaker turns. Status: a proxy, the speech gate is not measured against labelled speech.' + srcDoc,
256
261
  inputSchema: src,
257
262
  }, wrap((i) => analyzeSource('voicelab/segments', i, {}, apiKey, local)));
258
263
 
259
264
  tool('index_signal', {
260
265
  title: 'Index a signal (SignalLab)',
261
- 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,
266
+ description: 'A metadata index for any audio file: content-type guess (voice/music/mixed/noise/silence) with confidence, brightness & dynamics buckets, a rough band label, clipping/silence regions, and tag suggestions. For triage or auto-tagging a library. Status: content type, regions and confidence come from a frame classifier that is a proxy, not validated on a labelled corpus of real recordings; the tags describe the signal only, never the speaker (https://audiolab.tools/lenses).' + srcDoc,
262
267
  inputSchema: src,
263
268
  }, wrap((i) => analyzeSource('signallab', i, {}, apiKey, local)));
264
269
 
@@ -318,7 +323,7 @@ export function buildServer({ apiKey, local = false } = {}) {
318
323
  const batchSrc = local
319
324
  ? {
320
325
  urls: z.array(z.string().url()).optional().describe('Public https URLs to audio files. Combined max 20 items with paths.'),
321
- 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.'),
326
+ paths: z.array(z.string()).optional().describe('LOCAL audio file paths; each is read here and uploaded over a one-shot signed URL, measured by the API, and swept from storage within the hour. Combined max 20 items with urls.'),
322
327
  }
323
328
  : { urls: z.array(z.string().url()).min(1).max(20).describe('Public https URLs to audio files (max 20).') };
324
329
  tool('analyze_batch', {
@@ -350,6 +355,15 @@ if (isMain && process.argv.includes('--selftest')) {
350
355
  delete process.env.AUDIOLAB_API_KEY;
351
356
  await assert.rejects(() => call('mixlab/analyze', { url: 'https://example.com/a.wav' }), /AUDIOLAB_API_KEY/, 'refuses without a key (before any fetch)');
352
357
 
358
+ // 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
+ {
360
+ const { withDocs, codeFor } = await import('./error-docs.mjs');
361
+ assert.equal(withDocs('AUDIOLAB_API_KEY is not set.', new Error('AUDIOLAB_API_KEY is not set. Get a key at https://audiolab.tools/account.')), 'AUDIOLAB_API_KEY is not set.\nDocs: https://audiolab.tools/docs/errors#missing_api_key', 'de ontbrekende sleutel wijst naar zijn uitleg');
362
+ assert.equal(codeFor(Object.assign(new Error('x'), { code: 'quota_exceeded' })), 'quota_exceeded', 'de code van de API wint van de tekst');
363
+ assert.equal(codeFor(new Error('iets onverwachts')), 'analysis_error', 'onbekend valt terug op analysis_error');
364
+ assert.equal(codeFor(new Error('AudioLab API timed out after 5 ms.')), 'api_timeout');
365
+ }
366
+
353
367
  process.env.AUDIOLAB_API_KEY = 'al_live_selftest';
354
368
  // A remote server (local=false) must refuse a path BEFORE any filesystem read.
355
369
  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');
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@audiolabtools/mcp-server",
3
- "version": "0.4.2",
3
+ "version": "0.4.4",
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",
@@ -9,6 +9,7 @@
9
9
  },
10
10
  "files": [
11
11
  "hosted-server.mjs",
12
+ "error-docs.mjs",
12
13
  "README.md"
13
14
  ],
14
15
  "keywords": [