@audiolabtools/mcp-server 0.1.0 → 0.1.1

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,81 @@
-# 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.**
 
-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 a **public https URL** to the audio; the API fetches and analyses it
+server-side and returns numbers only (nothing is uploaded from your machine).
 
-- Node ≥ 22
-- **ffmpeg on `PATH`**: the engine's Node decoder shells out to it.
+| Tool | Input | Returns |
+|---|---|---|
+| `analyze_loudness` | `{ url }` | Integrated LUFS (EBU R128 / BS.1770-4), true-peak (dBTP), LRA, crest factor, stereo correlation, mono compatibility, tonal balance |
+| `check_target` | `{ url, target, lufs?, tp? }` | 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` | `{ url, waveformPoints? }` | Short-term LUFS over time + downsampled waveform peaks (for graphs/meters) |
+| `get_spectrum` | `{ url }` | FFT magnitude data + 7-band energies + dominant band |
+| `analyze_voice` | `{ url }` | Voice QA: speech/silence ratio, speaking rate, SNR, noise floor, room echo, sibilance & clipping risk |
+| `get_speech_segments` | `{ url }` | Voiced regions with start/end + per-segment RMS (auto-trim, chapters) |
+| `index_signal` | `{ url }` | Content-type guess, tags, clipping/silence regions, brightness & dynamics buckets |
+| `compare_loudness` | `{ urlA, urlB }` | Runs loudness on both and returns both results for an A/B comparison |
 
-## Run
+Example asks to your AI:
 
-```sh
-npm run mcp            # or: node mcp/server.mjs
-node mcp/server.mjs --selftest   # smoke test (4 tools), no network/ffmpeg needed
-```
+- *“Analyze the loudness of https://example.com/track.wav”* → `analyze_loudness`
+- *“Does https://example.com/mix.wav pass Spotify?”* → `check_target` with `target:"spotify"`
+- *“A/B-compare masterA.wav vs masterB.wav for loudness”* → `compare_loudness`
 
-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).
+## Configuration (env)
 
-## Add to Claude Desktop / Claude Code
+| 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. |
 
-```json
-{
-  "mcpServers": {
-    "audiolab": {
-      "command": "node",
-      "args": ["E:/New audiolab.dev/mcp/server.mjs"]
-    }
-  }
-}
-```
+## Privacy
 
-(Once the package ships on npm, this becomes
-`{"command": "npx", "args": ["-y", "@audiolab/mcp-server"]}`, gated on publish.)
+The tools send the **audio URL** and your **API key** to the AudioLab API (`audiolab.tools`),
+which fetches and analyses the audio server-side and returns numbers only — your audio is not
+stored (see https://audiolab.tools/privacy). This package has no telemetry and writes nothing
+to disk.
 
-Then ask:
+## Limits
 
-- *"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`
+- One file per call (agents loop for many); one-shot (no streaming/realtime).
+- File-size and rate limits are enforced by the API, per key.
 
-## Limits
+## Smoke test
 
-- 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)
+```sh
+node hosted-server.mjs --selftest   # verifies the 8 tools register + the missing-key guard; 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

@@ -5,15 +5,15 @@
 // 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),
+//   1. This file run directly = a stdio server (the npm package @audiolabtools/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).
+// 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
@@ -26,19 +26,35 @@ 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(/\/$/, '');
+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),
-  });
+  if (!key) throw new Error('AUDIOLAB_API_KEY is not set. Get a key at https://audiolab.tools/account.');
+  // Time-box the request so a hung/slow API can't stall the calling agent forever.
+  const timeoutMs = Number(process.env.AUDIOLAB_TIMEOUT_MS) || 60_000;
+  let res;
+  try {
+    res = await fetch(`${apiBase()}/${route}`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json', authorization: `Bearer ${key}` },
+      body: JSON.stringify(body),
+      signal: AbortSignal.timeout(timeoutMs),
+    });
+  } catch (e) {
+    if (e?.name === 'TimeoutError') throw new Error(`AudioLab API timed out after ${timeoutMs} 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) }; }
+  // Parse JSON only; never echo an arbitrary upstream body back to the agent.
+  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;
 }
@@ -52,7 +68,7 @@ const wrap = (fn) => async (input) => {
 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 server = new McpServer({ name: 'audiolab', version: '0.1.1' }); // 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@audiolabtools/mcp-server",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "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",