@audiolabtools/mcp-server 0.4.1 → 0.4.3
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 +1 -1
- package/error-docs.mjs +34 -0
- package/hosted-server.mjs +19 -5
- package/package.json +2 -1
package/README.md
CHANGED
|
@@ -45,7 +45,7 @@ Every tool takes **one audio source**: a public `url` **or** a local `path`:
|
|
|
45
45
|
| `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 |
|
|
46
46
|
| `analyze_timeseries` | Short-term LUFS over time + downsampled waveform peaks (`waveformPoints?`) |
|
|
47
47
|
| `get_spectrum` | FFT magnitude data + 7-band energies |
|
|
48
|
-
| `analyze_voice` | Voice QA: speech/silence ratio, speaking rate, SNR, noise floor,
|
|
48
|
+
| `analyze_voice` | Voice QA: speech/silence ratio, speaking rate, SNR, noise floor, pause energy, sibilance & clipping risk |
|
|
49
49
|
| `get_speech_segments` | Voiced regions with start/end + per-segment RMS (auto-trim, chapters) |
|
|
50
50
|
| `index_signal` | Content-type guess, tags, clipping/silence regions, brightness & dynamics buckets |
|
|
51
51
|
| `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> |
|
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)
|
|
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
|
|
@@ -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,
|
|
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
|
|
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,
|
|
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
|
|
|
@@ -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.
|
|
3
|
+
"version": "0.4.3",
|
|
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": [
|