@audiolabtools/mcp-server 0.1.0

package/README.md

@@ -0,0 +1,107 @@
+# AudioLab 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.
+
+Audio sources accepted:
+- **Public URL** (`{url: "https://..."}`): fetched and decoded server-side
+- **Local file path** (`{path: "./song.wav"}`): read server-side from disk
+
+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:
+
+```json
+{
+  "mcpServers": {
+    "audiolab": {
+      "command": "node",
+      "args": ["/abs/path/to/mcp/hosted-server.mjs"],
+      "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.
+
+## Tools: eight, all single-shot
+
+| 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 |
+
+Provide **exactly one** of `url` or `path` per source.
+
+## Requirements
+
+- Node ≥ 22
+- **ffmpeg on `PATH`**: the engine's Node decoder shells out to it.
+
+## Run
+
+```sh
+npm run mcp            # or: node mcp/server.mjs
+node mcp/server.mjs --selftest   # smoke test (4 tools), no network/ffmpeg needed
+```
+
+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).
+
+## Add to Claude Desktop / Claude Code
+
+```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.)
+
+Then ask:
+
+- *"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`
+
+## 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)
+
+## Fastest path to first paying partner
+
+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.

package/hosted-server.mjs

@@ -0,0 +1,142 @@
+#!/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.
+//
+// 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.
+//   2. api/mcp.mjs = the remote streamable-HTTP endpoint at /mcp, which passes the
+//      per-request Bearer key via buildServer({ apiKey }).
+//
+// Requires an API key (the API is live for design partners; email partners@audiolab.tools).
+// Config in Claude Desktop's claude_desktop_config.json:
+//   { "mcpServers": { "audiolab": {
+//       "command": "npx", "args": ["-y", "@audiolab/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
+
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { pathToFileURL } from 'node:url';
+import { z } from 'zod';
+
+// 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(/\/$/, '');
+
+// 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 text = await res.text();
+  let json;
+  try { json = JSON.parse(text); } catch { json = { raw: text.slice(0, 500) }; }
+  if (!res.ok) throw new Error(String(json?.error?.message || json?.error || `API returned ${res.status}`));
+  return json;
+}
+
+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.') };
+
+export function buildServer({ apiKey } = {}) {
+  const server = new McpServer({ name: 'audiolab', version: '0.2.0' });
+  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);
+
+  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 })));
+
+  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 })));
+
+  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 })));
+
+  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 })));
+
+  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 })));
+
+  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 })));
+
+  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 })));
+
+  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 })]);
+    return { a, b };
+  }));
+
+  return { server, toolNames };
+}
+
+// Run as a stdio server ONLY when executed directly. Importing this module (api/mcp.mjs)
+// is side-effect-free so it can reuse buildServer() without opening a stdio transport.
+const isMain = process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
+
+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 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.exit(0);
+}
+
+if (isMain) {
+  const { server } = buildServer();
+  await server.connect(new StdioServerTransport());
+}

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@audiolabtools/mcp-server",
+  "version": "0.1.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": {
+    "audiolabtools-mcp-server": "hosted-server.mjs"
+  },
+  "files": ["hosted-server.mjs", "README.md"],
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "claude",
+    "audio",
+    "audio-analysis",
+    "loudness",
+    "lufs",
+    "ebu-r128",
+    "bs-1770",
+    "true-peak",
+    "voice-quality",
+    "audiolab"
+  ],
+  "homepage": "https://audiolab.tools/api",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Audio-Launch/audiolab-tools.git",
+    "directory": "mcp"
+  },
+  "license": "MIT",
+  "author": "Nathan Renting",
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "zod": "^4.4.3"
+  }
+}