@audiolabtools/mcp-server 0.4.5 → 0.5.1
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 +18 -10
- package/error-docs.mjs +1 -1
- package/hosted-server.mjs +42 -16
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -11,26 +11,33 @@ and uploaded there (see [Privacy](#privacy)).
|
|
|
11
11
|
|
|
12
12
|
## Install
|
|
13
13
|
|
|
14
|
-
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:
|
|
15
16
|
|
|
16
17
|
```json
|
|
17
18
|
{
|
|
18
19
|
"mcpServers": {
|
|
19
20
|
"audiolab": {
|
|
20
21
|
"command": "npx",
|
|
21
|
-
"args": ["-y", "@audiolabtools/mcp-server"]
|
|
22
|
-
"env": { "AUDIOLAB_API_KEY": "al_live_yourkey" }
|
|
22
|
+
"args": ["-y", "@audiolabtools/mcp-server"]
|
|
23
23
|
}
|
|
24
24
|
}
|
|
25
25
|
}
|
|
26
26
|
```
|
|
27
27
|
|
|
28
|
-
|
|
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
|
+
```
|
|
29
36
|
|
|
30
37
|
## Requirements
|
|
31
38
|
|
|
32
39
|
- **Node ≥ 18**: uses the built-in global `fetch` + `AbortSignal.timeout`.
|
|
33
|
-
-
|
|
40
|
+
- Optionally an `AUDIOLAB_API_KEY` (see Install). No ffmpeg, no native dependencies.
|
|
34
41
|
|
|
35
42
|
## Tools
|
|
36
43
|
|
|
@@ -45,21 +52,22 @@ Every tool takes **one audio source**: a public `url` **or** a local `path`:
|
|
|
45
52
|
| Tool | Returns |
|
|
46
53
|
|---|---|
|
|
47
54
|
| `analyze_loudness` | Integrated LUFS (EBU R128 / BS.1770-4), true-peak (dBTP), LRA, crest factor, stereo correlation, mono compatibility, tonal balance |
|
|
48
|
-
| `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
|
|
55
|
+
| `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; passes within ±0.5 LU of the target with true peak at most 0.5 dB above it. On a fail it adds a single-pass ffmpeg loudnorm command as a starting point: measure the output again, single-pass can miss the margin |
|
|
49
56
|
| `analyze_timeseries` | Short-term LUFS over time + downsampled waveform peaks (`waveformPoints?`) |
|
|
50
57
|
| `get_spectrum` | FFT magnitude data + 7-band energies |
|
|
51
58
|
| `analyze_voice` | Voice QA: speech/silence ratio, speaking rate, SNR, noise floor, pause energy, sibilance & clipping risk |
|
|
52
59
|
| `get_speech_segments` | Voiced regions with start/end + per-segment RMS (auto-trim, chapters) |
|
|
53
|
-
| `index_signal` | Content-type guess, tags, clipping/silence regions, brightness & dynamics buckets |
|
|
60
|
+
| `index_signal` | Content-type guess, tags, clipping/silence regions, brightness & dynamics buckets. Add `bandLimit:true` for `bandLimit.upsampled`: `yes`, `no` or `cannot-say`, with the reason in plain words (guide: <https://audiolab.tools/docs/start/is-my-audio-upsampled>) |
|
|
54
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> |
|
|
55
62
|
| `compare_loudness` | A/B on two sources (`urlA`/`pathA` + `urlB`/`pathB`), returns both results |
|
|
56
|
-
| `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 |
|
|
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; with `endpoint:"signallab/index"` it takes `bandLimit:true` too. Each item meters as one call |
|
|
57
64
|
|
|
58
65
|
Example asks to your AI:
|
|
59
66
|
|
|
60
67
|
- *“Analyze the loudness of https://example.com/track.wav”* → `analyze_loudness` with `url`
|
|
61
68
|
- *“Is this take usable?”* → `analyze_profile` with `profile:"voice"`
|
|
62
69
|
- *“Has this file been re-encoded, and is it all one source?”* → `analyze_profile` with `profile:"provenance"`
|
|
70
|
+
- *“Which of these recordings were upsampled?”* → `analyze_batch` with `endpoint:"signallab/index"` and `bandLimit:true`
|
|
63
71
|
- *“Run loudness on ./master.wav”* → `analyze_loudness` with `path`
|
|
64
72
|
- *“Does ./mix.mp3 pass Spotify?”* → `check_target` with `path` + `target:"spotify"`
|
|
65
73
|
|
|
@@ -67,7 +75,7 @@ Example asks to your AI:
|
|
|
67
75
|
|
|
68
76
|
| Var | Default | Purpose |
|
|
69
77
|
|---|---|---|
|
|
70
|
-
| `AUDIOLAB_API_KEY` | – (
|
|
78
|
+
| `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). |
|
|
71
79
|
| `AUDIOLAB_API_BASE` | `https://audiolab.tools/v1` | Override the API base (must be `https://`). |
|
|
72
80
|
| `AUDIOLAB_TIMEOUT_MS` | `330000` | Per-request timeout in milliseconds (long files and batches stream server-side and can legitimately take minutes). |
|
|
73
81
|
|
|
@@ -89,7 +97,7 @@ agents.
|
|
|
89
97
|
- Local files: up to **150 MB** (host bigger ones at a public URL).
|
|
90
98
|
- 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.
|
|
91
99
|
- One file per call (agents loop for many); one-shot (no streaming/realtime).
|
|
92
|
-
- Rate and monthly limits are enforced by the API, per key.
|
|
100
|
+
- Rate and monthly limits are enforced by the API, per key (per IP address on the keyless trial).
|
|
93
101
|
|
|
94
102
|
## Smoke test
|
|
95
103
|
|
package/error-docs.mjs
CHANGED
|
@@ -6,7 +6,7 @@
|
|
|
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', 'room_not_measurable',
|
|
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', 'incomplete_file',
|
|
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
11
|
'storage_unavailable', 'analysis_error', 'missing_api_key', 'api_timeout', 'api_unreachable', 'voice_minutes_exhausted', 'service_paused', 'invalid_input',
|
|
12
12
|
];
|
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
|
-
//
|
|
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 (
|
|
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
|
-
|
|
72
|
-
|
|
73
|
-
|
|
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',
|
|
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,
|
|
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);
|
|
@@ -263,9 +271,12 @@ export function buildServer({ apiKey, local = false } = {}) {
|
|
|
263
271
|
|
|
264
272
|
tool('index_signal', {
|
|
265
273
|
title: 'Index a signal (SignalLab)',
|
|
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,
|
|
267
|
-
inputSchema:
|
|
268
|
-
|
|
274
|
+
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). Set bandLimit:true to ask whether the audio was upsampled: bandLimit.upsampled is yes, no or cannot-say, with the reason in plain words. yes rests on a validated rule (study UP-1: the band stops under 5 kHz in a file of 16 kHz or more, as after a telephone call); no and the bandwidth ratio are proxies (study UP-2); cannot-say means look at the file, not that it is fine.' + srcDoc,
|
|
275
|
+
inputSchema: {
|
|
276
|
+
...src,
|
|
277
|
+
bandLimit: z.boolean().optional().describe('Also return bandLimit: whether the audio was upsampled (yes, no or cannot-say), its status, reason and basis. Off by default.'),
|
|
278
|
+
},
|
|
279
|
+
}, wrap((i) => analyzeSource('signallab', i, { bandLimit: i.bandLimit }, apiKey, local)));
|
|
269
280
|
|
|
270
281
|
// analyze_profile: the lens registry as one tool. A model that knows what it
|
|
271
282
|
// is looking for names the question, not forty field names; a model that does
|
|
@@ -340,8 +351,9 @@ export function buildServer({ apiKey, local = false } = {}) {
|
|
|
340
351
|
target: z.string().optional().describe('For mixlab/check-target: preset id (spotify, ebu-broadcast, podcast, …) or "custom".'),
|
|
341
352
|
lufs: z.number().optional().describe('For target="custom": integrated LUFS target.'),
|
|
342
353
|
tp: z.number().optional().describe('For target="custom": max true-peak (dBTP).'),
|
|
354
|
+
bandLimit: z.boolean().optional().describe('For signallab/index: also return bandLimit per file, with upsampled yes, no or cannot-say (see index_signal).'),
|
|
343
355
|
},
|
|
344
|
-
}, wrap((i) => batchSources({ urls: i.urls || [], paths: i.paths || [] }, i.endpoint || 'mixlab/analyze', { target: i.target, lufs: i.lufs, tp: i.tp }, apiKey, local)));
|
|
356
|
+
}, wrap((i) => batchSources({ urls: i.urls || [], paths: i.paths || [] }, i.endpoint || 'mixlab/analyze', { target: i.target, lufs: i.lufs, tp: i.tp, bandLimit: i.bandLimit }, apiKey, local)));
|
|
345
357
|
|
|
346
358
|
return { server, toolNames };
|
|
347
359
|
}
|
|
@@ -358,7 +370,21 @@ if (isMain && process.argv.includes('--selftest')) {
|
|
|
358
370
|
|
|
359
371
|
const prev = process.env.AUDIOLAB_API_KEY;
|
|
360
372
|
delete process.env.AUDIOLAB_API_KEY;
|
|
361
|
-
|
|
373
|
+
// Without a key: a single analysis goes out with no Authorization header (the keyless trial); a batch refuses before any fetch.
|
|
374
|
+
{
|
|
375
|
+
const realFetch = globalThis.fetch;
|
|
376
|
+
let sent;
|
|
377
|
+
globalThis.fetch = async (_url, init) => { sent = init.headers; return new Response('{"ok":true}', { status: 200 }); };
|
|
378
|
+
try {
|
|
379
|
+
await call('mixlab/analyze', { url: 'https://example.com/a.wav' });
|
|
380
|
+
assert.ok(sent && !('authorization' in sent), 'keyless call sends no Authorization header');
|
|
381
|
+
await call('mixlab/analyze', { url: 'https://example.com/a.wav' }, 'al_live_selftest');
|
|
382
|
+
assert.equal(sent.authorization, 'Bearer al_live_selftest', 'a key still goes out as Bearer');
|
|
383
|
+
sent = undefined;
|
|
384
|
+
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');
|
|
385
|
+
assert.equal(sent, undefined, 'the batch refusal happens before any fetch');
|
|
386
|
+
} finally { globalThis.fetch = realFetch; }
|
|
387
|
+
}
|
|
362
388
|
|
|
363
389
|
// 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).
|
|
364
390
|
{
|
|
@@ -396,7 +422,7 @@ if (isMain && process.argv.includes('--selftest')) {
|
|
|
396
422
|
if (e?.code !== 'ERR_MODULE_NOT_FOUND') throw e;
|
|
397
423
|
}
|
|
398
424
|
|
|
399
|
-
console.log(`selftest ok · v${PKG_VERSION} · ${expected.length} tools (incl. analyze_profile) +
|
|
425
|
+
console.log(`selftest ok · v${PKG_VERSION} · ${expected.length} tools (incl. analyze_profile) + keyless trial and batch-key guard + remote-path refusals + batch guards`);
|
|
400
426
|
process.exit(0);
|
|
401
427
|
}
|
|
402
428
|
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@audiolabtools/mcp-server",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.5.1",
|
|
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",
|