@audiolabtools/mcp-server 0.1.0 → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nathan Renting
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,107 +1,90 @@
-# AudioLab MCP server
+# @audiolabtools/mcp-server
 
-Exposes the proprietary AudioLab analysis engine as [Model Context Protocol](https://modelcontextprotocol.io)
-tools, so an AI agent (Claude Desktop, Claude Code, or any MCP client) can analyze audio.
+MCP ([Model Context Protocol](https://modelcontextprotocol.io)) server that gives any
+MCP-capable AI — Claude Desktop, Claude Code, Cursor, and others — eight 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.
 
-Audio sources accepted:
-- **Public URL** (`{url: "https://..."}`): fetched and decoded server-side
-- **Local file path** (`{path: "./song.wav"}`): read server-side from disk
+## Install
 
-The MCP server runs on stdio in the user's own process, so local-file access is the
-same threat model as a CLI the user installs themselves.
-
-Nothing is uploaded by the caller in either case. Responses are **curated** JSON
-(per-sample waveform/spectrum arrays are dropped so the response is useful to an
-LLM, not overwhelming).
-
-## Two modes (pick by who runs it)
-
-| | `mcp/server.mjs` (local) | `mcp/hosted-server.mjs` (hosted) |
-|---|---|---|
-| Runs | the proprietary engine locally (bundled ffmpeg) | HTTP calls to the hosted API `audiolab.tools/v1/*` |
-| Audio source | `{url}` **or** `{path}` (on-device, never leaves the machine) | `{url}` only |
-| Needs | the repo + engine (private) | an `AUDIOLAB_API_KEY` |
-| Distribute? | **No** (it contains the proprietary engine; keep it repo-only) | **Yes** (no engine code, safe to hand to Claude & other AIs) |
-
-Give **hosted mode** to Claude Desktop / Claude Code / Cursor / any MCP client:
+Point your MCP client at the package via `npx` (nothing to install globally):
 
 ```json
 {
   "mcpServers": {
     "audiolab": {
-      "command": "node",
-      "args": ["/abs/path/to/mcp/hosted-server.mjs"],
+      "command": "npx",
+      "args": ["-y", "@audiolabtools/mcp-server"],
       "env": { "AUDIOLAB_API_KEY": "al_live_yourkey" }
     }
   }
 }
 ```
 
-Get a key from partners@audiolab.tools (self-serve opens after the first partners).
-Both modes expose the identical eight tools below.
+Get a key: sign in at **https://audiolab.tools/account** and generate one (free tier available).
 
-## Tools: eight, all single-shot
+## Requirements
 
-| Tool | Lab | Input | Returns |
-|---|---|---|---|
-| `analyze_loudness` | MixLab | `{url}` or `{path}` | Integrated LUFS (EBU R128 / BS.1770-4), true-peak, loudness range, crest factor, stereo correlation, tonal balance, harshness/muddiness labels |
-| `check_target` | MixLab | `{url\|path, target, lufs?, tp?}` | Pass/fail vs Spotify -14 / Apple-Music -16 / YouTube -14 / TIDAL -14 / Amazon -14 / podcast -16 / EBU-broadcast -23 / ATSC-broadcast -24 (or `"custom"` + lufs+tp). Includes deltas, issue messages, ffmpeg loudnorm fix command |
-| `analyze_timeseries` | MixLab | `{url\|path, waveformPoints?}` | Short-term LUFS samples + downsampled waveform peaks over time (for graphing/UI) |
-| `get_spectrum` | MixLab | `{url}` or `{path}` | FFT bins (freqs+mags) + 7-band energies + centroid/rolloff/flatness |
-| `analyze_voice` | VoiceLab | `{url}` or `{path}` | Speech/silence ratio, speaking rate, SNR, noise floor, room echo, sibilance & clipping risk |
-| `get_speech_segments` | VoiceLab | `{url}` or `{path}` | Voiced regions with start/end timestamps + per-segment RMS (for auto-trim, chapters, speaker-turn detection) |
-| `index_signal` | SignalLab | `{url}` or `{path}` | Content-type guess, tags, clipping/silence regions, brightness & dynamics buckets, file facts |
-| `compare_loudness` | MixLab A/B | `{a: {url\|path}, b: {url\|path}}` | Run MixLab on both, return both results + per-metric deltas with verdict |
+- **Node ≥ 18** — uses the built-in global `fetch` + `AbortSignal.timeout`.
+- An `AUDIOLAB_API_KEY`. No ffmpeg, no native dependencies.
 
-Provide **exactly one** of `url` or `path` per source.
+## Tools
 
-## Requirements
+Every tool takes **one audio source** — a public `url` **or** a local `path`:
 
-- Node ≥ 22
-- **ffmpeg on `PATH`**: the engine's Node decoder shells out to it.
+- `{ 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.)*
 
-## Run
+| 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 |
 
-```sh
-npm run mcp            # or: node mcp/server.mjs
-node mcp/server.mjs --selftest   # smoke test (4 tools), no network/ffmpeg needed
-```
+Example asks to your AI:
 
-The server speaks MCP over **stdio** (what desktop clients spawn). Streamable HTTP
-for a remote, keyed server is a later transport addition; deploy, auth keys,
-and billing are gated steps (see [`docs/PDD.md`](../docs/PDD.md) §0/§8).
+- *“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"`
 
-## Add to Claude Desktop / Claude Code
+## Configuration (env)
 
-```json
-{
-  "mcpServers": {
-    "audiolab": {
-      "command": "node",
-      "args": ["E:/New audiolab.dev/mcp/server.mjs"]
-    }
-  }
-}
-```
-
-(Once the package ships on npm, this becomes
-`{"command": "npx", "args": ["-y", "@audiolab/mcp-server"]}`, gated on publish.)
+| 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. |
 
-Then ask:
+## Privacy
 
-- *"Analyze the loudness of https://example.com/track.wav"* → calls `analyze_loudness` with `{url}`
-- *"Run loudness on ./mix.wav"* → calls `analyze_loudness` with `{path}`
-- *"A/B compare ./master.wav against ./reference.wav for loudness"* → calls `compare_loudness`
+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
 
-- 200 MB per file (size cap)
-- Any sample rate / channel count (engine preserves rate; multi-channel mixed to stereo for analysis)
-- One file per call (no batch; agent loops for many)
-- One-shot only (no streaming / realtime)
+- 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 8 tools + guards; no network
+```
 
-## Fastest path to first paying partner
+## License
 
-Deploy the hosted-API counterpart (`api/v1/[...endpoint].mjs`) + add one key +
-invoice them. No Stripe, no key DB, no metering platform required to start.
-Metering/credits/self-serve come later, behind the billing gate.
+MIT © Nathan Renting

package/hosted-server.mjs

@@ -1,115 +1,229 @@
 #!/usr/bin/env node
 // AudioLab HOSTED-mode MCP server. Exposes the 8 AudioLab tools to any MCP-capable
 // AI (Claude Desktop / Claude Code, Cursor, etc.) by calling the hosted API at
-// audiolab.tools/v1/*. Unlike mcp/server.mjs it contains NO engine code, just HTTP
-// calls, so it is safe to distribute publicly without exposing the proprietary engine.
+// 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 @audiolab/mcp-server),
-//      reading the key from AUDIOLAB_API_KEY.
+//   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
+//      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 }).
+//      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.
 //
-// Requires an API key (the API is live for design partners; email partners@audiolab.tools).
+// Requires an API key (self-serve: sign in at https://audiolab.tools/account and generate one).
 // Config in Claude Desktop's claude_desktop_config.json:
 //   { "mcpServers": { "audiolab": {
-//       "command": "npx", "args": ["-y", "@audiolab/mcp-server"],
+//       "command": "npx", "args": ["-y", "@audiolabtools/mcp-server"],
 //       "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). Smoke test (no network): node mcp/hosted-server.mjs --selftest
+// (default https://audiolab.tools/v1, must be https), AUDIOLAB_TIMEOUT_MS (default 60000).
+// Smoke test (no network): node hosted-server.mjs --selftest
 
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { readFile } from 'node:fs/promises';
+import { basename } from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { z } from 'zod';
 
+// 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;
+const STORAGE_MAX = 50 * 1024 * 1024;
+
 // Read env at CALL time (not module load) so the key can be injected by the MCP host
 // and so the missing-key guard is testable.
-const apiBase = () => (process.env.AUDIOLAB_API_BASE || 'https://audiolab.tools/v1').replace(/\/$/, '');
+const apiBase = () => {
+  const base = (process.env.AUDIOLAB_API_BASE || 'https://audiolab.tools/v1').replace(/\/$/, '');
+  // Defense in depth: never send the Bearer key over a non-https (or attacker-injected) base.
+  if (!/^https:\/\//i.test(base)) throw new Error('AUDIOLAB_API_BASE must be an https:// URL.');
+  return base;
+};
 
-// key defaults to the env var (stdio mode); the remote endpoint passes a per-request key.
-export async function call(route, body, key = process.env.AUDIOLAB_API_KEY) {
-  if (!key) throw new Error('AUDIOLAB_API_KEY is not set. Get a key from partners@audiolab.tools.');
-  const res = await fetch(`${apiBase()}/${route}`, {
-    method: 'POST',
-    headers: { 'content-type': 'application/json', authorization: `Bearer ${key}` },
-    body: JSON.stringify(body),
-  });
+const timeoutMs = () => Number(process.env.AUDIOLAB_TIMEOUT_MS) || 60_000;
+
+function requireKey(key) {
+  const k = key || process.env.AUDIOLAB_API_KEY;
+  if (!k) throw new Error('AUDIOLAB_API_KEY is not set. Get a key at https://audiolab.tools/account.');
+  return k;
+}
+
+// Guess an audio content-type from a filename extension.
+const CT_BY_EXT = { mp3: 'audio/mpeg', wav: 'audio/wav', flac: 'audio/flac', m4a: 'audio/mp4', mp4: 'audio/mp4', aac: 'audio/aac', ogg: 'audio/ogg', oga: 'audio/ogg', opus: 'audio/opus', webm: 'audio/webm', aiff: 'audio/aiff', aif: 'audio/aiff' };
+const ctForPath = (p) => CT_BY_EXT[String(p).split('.').pop()?.toLowerCase()] || 'application/octet-stream';
+
+// Low-level JSON request with a hard timeout. Never echoes an arbitrary upstream body.
+async function request(url, { method = 'POST', headers = {}, body } = {}) {
+  const ms = timeoutMs();
+  let res;
+  try {
+    res = await fetch(url, { method, headers, body, signal: AbortSignal.timeout(ms) });
+  } catch (e) {
+    if (e?.name === 'TimeoutError') throw new Error(`AudioLab API timed out after ${ms} ms.`);
+    throw new Error(`Could not reach the AudioLab API: ${String(e?.message || e)}`);
+  }
   const text = await res.text();
   let json;
-  try { json = JSON.parse(text); } catch { json = { raw: text.slice(0, 500) }; }
+  try { json = JSON.parse(text); }
+  catch { throw new Error(res.ok ? 'AudioLab API returned a non-JSON response.' : `AudioLab API error ${res.status}.`); }
   if (!res.ok) throw new Error(String(json?.error?.message || json?.error || `API returned ${res.status}`));
   return json;
 }
 
+// key defaults to the env var (stdio mode); the remote endpoint passes a per-request key.
+export async function call(route, body, key = process.env.AUDIOLAB_API_KEY) {
+  const k = requireKey(key);
+  return request(`${apiBase()}/${route}`, {
+    headers: { 'content-type': 'application/json', authorization: `Bearer ${k}` },
+    body: JSON.stringify(body),
+  });
+}
+
+// Small local file → raw audio body straight to /v1 (fast, no storage round-trip).
+// Tool extras (target/lufs/tp/waveformPoints/fileName) ride along as query params.
+async function postRaw(route, buf, ct, extra, key) {
+  const k = requireKey(key);
+  const qs = new URLSearchParams();
+  for (const [name, v] of Object.entries(extra || {})) if (v !== undefined && v !== null && v !== '') qs.set(name, String(v));
+  const q = qs.toString();
+  return request(`${apiBase()}/${route}${q ? `?${q}` : ''}`, {
+    headers: { 'content-type': ct, authorization: `Bearer ${k}` },
+    body: buf,
+  });
+}
+
+// Larger local file → mint a signed upload URL, PUT the bytes to storage, then analyse by
+// objectPath. The objectPath is namespaced to this key server-side; only this key can read it.
+async function postUpload(route, buf, ct, fileName, extra, key) {
+  const k = requireKey(key);
+  const origin = new URL(apiBase()).origin;
+  const mint = await request(`${origin}/api/upload-url`, {
+    headers: { 'content-type': 'application/json', authorization: `Bearer ${k}` },
+    body: JSON.stringify({ contentType: ct, size: buf.length }),
+  });
+  if (!mint?.signedUrl || !mint?.objectPath) throw new Error('Could not prepare the upload.');
+  let put;
+  try {
+    put = await fetch(mint.signedUrl, { method: 'PUT', headers: { 'content-type': ct }, body: buf, signal: AbortSignal.timeout(timeoutMs()) });
+  } catch (e) {
+    if (e?.name === 'TimeoutError') throw new Error(`Upload timed out after ${timeoutMs()} ms.`);
+    throw new Error(`Upload to storage failed: ${String(e?.message || e)}`);
+  }
+  if (!put.ok) throw new Error(`Upload to storage failed (HTTP ${put.status}).`);
+  return call(route, { objectPath: mint.objectPath, fileName, ...extra }, k);
+}
+
+// Resolve one audio source (url OR local path) to a route call. `local` gates path reads:
+// the remote /mcp endpoint passes local=false and must NEVER touch the server filesystem.
+async function analyzeSource(route, { url, path } = {}, extra = {}, key, local = false) {
+  if (url && path) throw new Error('Provide exactly one of url or path, not both.');
+  if (path) {
+    if (!local) throw new Error('Local file paths are only supported by the local (stdio) MCP server; use a public https url instead.');
+    let buf;
+    try { buf = await readFile(path); }
+    catch (e) { throw new Error(`Could not read local file "${path}": ${e?.code || e?.message || e}`); }
+    if (!buf.length) throw new Error('Local file is empty.');
+    if (buf.length > STORAGE_MAX) throw new Error(`Local file is ${(buf.length / 1048576).toFixed(1)} MB; max ${STORAGE_MAX / 1048576} MB. Host it at a public https URL for larger files.`);
+    const name = basename(path);
+    const ct = ctForPath(path);
+    return buf.length <= RAW_MAX
+      ? postRaw(route, buf, ct, { ...extra, fileName: name }, key)  // small → raw POST (no storage)
+      : postUpload(route, buf, ct, name, extra, key);              // large → signed-URL upload
+  }
+  if (url) return call(route, { url, ...extra }, key);
+  throw new Error('Provide a url (public https) or a path (local file).');
+}
+
 const asContent = (obj) => ({ content: [{ type: 'text', text: JSON.stringify(obj) }] });
 const wrap = (fn) => async (input) => {
   try { return asContent(await fn(input)); }
   catch (e) { return { isError: true, content: [{ type: 'text', text: String(e?.message || e) }] }; }
 };
 
-const URL_IN = { url: z.string().url().describe('Public https URL to the audio file.') };
+// Input source shape. Remote (url-only) keeps the original required url; local adds an
+// optional path (exactly one of the two). Local-file support only exists in stdio mode.
+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.'),
+    }
+  : { url: z.string().url().describe('Public https URL to the audio file.') };
 
-export function buildServer({ apiKey } = {}) {
-  const server = new McpServer({ name: 'audiolab', version: '0.2.0' });
+export function buildServer({ apiKey, local = false } = {}) {
+  const server = new McpServer({ name: 'audiolab', version: '0.2.0' }); // keep in sync with package.json
   const toolNames = [];
   const tool = (name, def, handler) => { server.registerTool(name, def, handler); toolNames.push(name); };
-  // Per-request API key threaded from the transport, so we never race on process.env
-  // when several requests share one warm serverless instance.
-  const api = (route, body) => call(route, body, apiKey);
+  const src = sourceShape(local);
+  const srcDoc = local ? ' Audio source: a public https URL, or a local file path (`path`).' : ' Audio source: public https URL.';
 
   tool('analyze_loudness', {
     title: 'Analyze loudness (MixLab)',
-    description: 'Loudness and dynamics for a track: integrated LUFS (EBU R128 / BS.1770-4), true-peak (dBTP), loudness range (LRA), crest factor, stereo correlation, mono compatibility, and tonal balance. Audio source: public https URL.',
-    inputSchema: URL_IN,
-  }, wrap(({ url }) => api('mixlab/analyze', { url })));
+    description: 'Loudness and dynamics for a track: integrated LUFS (EBU R128 / BS.1770-4), true-peak (dBTP), loudness range (LRA), crest factor, stereo correlation, mono compatibility, and tonal balance.' + srcDoc,
+    inputSchema: src,
+  }, wrap((i) => analyzeSource('mixlab/analyze', i, {}, apiKey, local)));
 
   tool('check_target', {
     title: 'Check audio against a loudness target (Spotify, EBU, etc.)',
-    description: 'Verify whether audio hits a delivery target (Spotify -14 LUFS / EBU broadcast -23 / podcast -16 / etc.). Returns pass/fail with per-metric deltas and a concrete ffmpeg loudnorm command to fix if failing. Presets: spotify, apple-music, youtube, tidal, amazon-music, podcast, ebu-broadcast, atsc-broadcast; or target="custom" with lufs+tp.',
-    inputSchema: { ...URL_IN, target: z.string().describe('Preset id or "custom".'), lufs: z.number().optional(), tp: z.number().optional() },
-  }, wrap(({ url, target, lufs, tp }) => api('mixlab/check-target', { url, target, lufs, tp })));
+    description: 'Verify whether audio hits a delivery target (Spotify -14 LUFS / EBU broadcast -23 / podcast -16 / etc.). Returns pass/fail with per-metric deltas and a concrete ffmpeg loudnorm command to fix if failing. Presets: spotify, apple-music, youtube, tidal, amazon-music, podcast, ebu-broadcast, atsc-broadcast; or target="custom" with lufs+tp.' + srcDoc,
+    inputSchema: { ...src, target: z.string().describe('Preset id or "custom".'), lufs: z.number().optional(), tp: z.number().optional() },
+  }, wrap((i) => analyzeSource('mixlab/check-target', i, { target: i.target, lufs: i.lufs, tp: i.tp }, apiKey, local)));
 
   tool('analyze_timeseries', {
     title: 'Loudness over time (for graphing / visualization)',
-    description: 'Short-term LUFS samples over time (EBU R128, ~3s window) with their time-base, plus downsampled waveform peaks. Arrays suitable for loudness-over-time charts, level meters, and waveform UIs.',
-    inputSchema: { ...URL_IN, waveformPoints: z.number().int().positive().optional().describe('Waveform peak count (default 200).') },
-  }, wrap(({ url, waveformPoints }) => api('mixlab/timeseries', { url, waveformPoints })));
+    description: 'Short-term LUFS samples over time (EBU R128, ~3s window) with their time-base, plus downsampled waveform peaks. Arrays suitable for loudness-over-time charts, level meters, and waveform UIs.' + srcDoc,
+    inputSchema: { ...src, waveformPoints: z.number().int().positive().optional().describe('Waveform peak count (default 200).') },
+  }, wrap((i) => analyzeSource('mixlab/timeseries', i, { waveformPoints: i.waveformPoints }, apiKey, local)));
 
   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.',
-    inputSchema: URL_IN,
-  }, wrap(({ url }) => api('mixlab/spectrum', { url })));
+    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,
+    inputSchema: src,
+  }, wrap((i) => analyzeSource('mixlab/spectrum', i, {}, apiKey, local)));
 
   tool('analyze_voice', {
     title: 'Analyze voice quality (VoiceLab)',
-    description: 'Speech-quality QA for a voice recording: speech/silence ratio, speaking-rate label, signal-to-noise, noise floor, room-echo label, sibilance risk, clipping severity. Gates a voice take.',
-    inputSchema: URL_IN,
-  }, wrap(({ url }) => api('voicelab/qa', { url })));
+    description: 'Speech-quality QA for a voice recording: speech/silence ratio, speaking-rate label, signal-to-noise, noise floor, room-echo label, sibilance risk, clipping severity. Gates a voice take.' + srcDoc,
+    inputSchema: src,
+  }, wrap((i) => analyzeSource('voicelab/qa', i, {}, apiKey, local)));
 
   tool('get_speech_segments', {
     title: 'Speech segments (VoiceLab)',
-    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.',
-    inputSchema: URL_IN,
-  }, wrap(({ url }) => api('voicelab/segments', { url })));
+    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,
+    inputSchema: src,
+  }, wrap((i) => analyzeSource('voicelab/segments', i, {}, apiKey, local)));
 
   tool('index_signal', {
     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.',
-    inputSchema: URL_IN,
-  }, wrap(({ url }) => api('signallab/index', { url })));
+    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)));
 
+  // 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.'),
+        pathA: z.string().optional().describe('First source as a local file path.'),
+        urlB: z.string().url().optional().describe('Second source URL (e.g. reference). Provide urlB or pathB.'),
+        pathB: z.string().optional().describe('Second source as a local file path.'),
+      }
+    : {
+        urlA: z.string().url().describe('First source (e.g. master).'),
+        urlB: z.string().url().describe('Second source (e.g. reference).'),
+      };
   tool('compare_loudness', {
     title: 'Compare two tracks (A/B)',
-    description: 'Run loudness analysis on TWO URLs and return both results for an A/B comparison: master vs reference, before vs after a fix, two encoders, two cuts.',
-    inputSchema: {
-      urlA: z.string().url().describe('First source (e.g. master).'),
-      urlB: z.string().url().describe('Second source (e.g. reference).'),
-    },
-  }, wrap(async ({ urlA, urlB }) => {
-    const [a, b] = await Promise.all([api('mixlab/analyze', { url: urlA }), api('mixlab/analyze', { url: urlB })]);
+    description: 'Run loudness analysis on TWO sources and return both results for an A/B comparison: master vs reference, before vs after a fix, two encoders, two cuts.' + srcDoc,
+    inputSchema: cmp,
+  }, wrap(async (i) => {
+    const [a, b] = await Promise.all([
+      analyzeSource('mixlab/analyze', { url: i.urlA, path: i.pathA }, {}, apiKey, local),
+      analyzeSource('mixlab/analyze', { url: i.urlB, path: i.pathB }, {}, apiKey, local),
+    ]);
     return { a, b };
   }));
 
@@ -122,21 +236,26 @@ 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 { toolNames } = buildServer();
-  assert.deepEqual(
-    toolNames.slice().sort(),
-    ['analyze_loudness', 'analyze_timeseries', 'analyze_voice', 'check_target', 'compare_loudness', 'get_spectrum', 'get_speech_segments', 'index_signal'],
-    'eight hosted tools registered',
-  );
+  const expected = ['analyze_loudness', 'analyze_timeseries', 'analyze_voice', 'check_target', 'compare_loudness', 'get_spectrum', 'get_speech_segments', 'index_signal'];
+  assert.deepEqual(buildServer().toolNames.slice().sort(), expected, 'eight hosted tools (remote / url-only)');
+  assert.deepEqual(buildServer({ local: true }).toolNames.slice().sort(), expected, 'eight hosted tools (local / url+path)');
+
   const prev = process.env.AUDIOLAB_API_KEY;
   delete process.env.AUDIOLAB_API_KEY;
   await assert.rejects(() => call('mixlab/analyze', { url: 'https://example.com/a.wav' }), /AUDIOLAB_API_KEY/, 'refuses without a key (before any fetch)');
-  if (prev) process.env.AUDIOLAB_API_KEY = prev;
-  console.log('selftest ok · 8 hosted tools (API-backed, no engine) + missing-key guard');
+
+  process.env.AUDIOLAB_API_KEY = 'al_live_selftest';
+  // A remote server (local=false) must refuse a path BEFORE any filesystem read.
+  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');
+  // url + path together is a usage error.
+  await assert.rejects(() => analyzeSource('mixlab/analyze', { url: 'https://x/a.wav', path: '/tmp/a.wav' }, {}, 'al_live_selftest', true), /exactly one/, 'url+path together rejected');
+  if (prev) process.env.AUDIOLAB_API_KEY = prev; else delete process.env.AUDIOLAB_API_KEY;
+
+  console.log('selftest ok · 8 tools (remote url-only + local url|path) + missing-key guard + remote-path refusal');
   process.exit(0);
 }
 
 if (isMain) {
-  const { server } = buildServer();
+  const { server } = buildServer({ local: true });
   await server.connect(new StdioServerTransport());
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@audiolabtools/mcp-server",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "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": {
@@ -22,6 +22,7 @@
     "audiolab"
   ],
   "homepage": "https://audiolab.tools/api",
+  "bugs": { "url": "https://audiolab.tools/api" },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/Audio-Launch/audiolab-tools.git",