@vocalstack/mcp 1.0.0 → 1.2.0

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 CHANGED
@@ -1,13 +1,17 @@
1
1
  # @vocalstack/mcp
2
2
 
3
- A local bridge to VocalStack's hosted MCP server. Use it in MCP clients that only run local (stdio) servers, such as Claude Desktop, Cursor and Windsurf, to transcribe, translate, search and summarize audio and video, and to run live broadcasts.
3
+ [![vocalstack/mcp MCP server](https://vocalstack.com/badges/glama-server.svg)](https://glama.ai/mcp/servers/vocalstack/mcp)
4
+ [![VocalStack MCP connector](https://vocalstack.com/badges/glama-connector.svg)](https://glama.ai/mcp/connectors/com.vocalstack/mcp)
5
+ [![mcptry](https://mcptry.com/badge/com.vocalstack/mcp)](https://mcptry.com/servers/com.vocalstack/mcp)
4
6
 
5
- If your client supports remote MCP servers, you don't need this package: add `https://api.vocalstack.com/v1/mcp` as a remote server and sign in with your VocalStack account when asked. Nothing to install.
7
+ VocalStack's MCP server. It runs on your machine (stdio) and works with VocalStack's public API using your API key, so any MCP client can transcribe, translate, search and summarize audio and video, and run live broadcasts that listeners follow in their own language.
6
8
 
7
9
  ## API key
8
10
 
9
11
  Create a key at [app.vocalstack.com](https://app.vocalstack.com) under **Developers → API keys**, and pass it as `VOCALSTACK_API_KEY`. Without a key the server still starts and lists its tools, but every tool call asks you to set one.
10
12
 
13
+ Only transcription is billed, per second of audio. Reading, searching, summaries, translations and listeners are free.
14
+
11
15
  ## Setup
12
16
 
13
17
  Requires Node.js 20 or later.
@@ -32,23 +36,11 @@ Add this to `claude_desktop_config.json` (Settings → Developer → Edit Config
32
36
 
33
37
  ### Cursor
34
38
 
35
- Add this to `~/.cursor/mcp.json` (all projects) or `.cursor/mcp.json` (one project):
39
+ Add the same block to `~/.cursor/mcp.json` (all projects) or `.cursor/mcp.json` (one project).
36
40
 
37
- ```json
38
- {
39
- "mcpServers": {
40
- "vocalstack": {
41
- "command": "npx",
42
- "args": ["-y", "@vocalstack/mcp"],
43
- "env": {
44
- "VOCALSTACK_API_KEY": "your-api-key"
45
- }
46
- }
47
- }
48
- }
49
- ```
41
+ ### Windsurf
50
42
 
51
- Windsurf and other clients take the same `command`, `args` and `env`.
43
+ Add the same block to `~/.codeium/windsurf/mcp_config.json`, then refresh the MCP servers in Windsurf's settings.
52
44
 
53
45
  ### Claude Code
54
46
 
@@ -56,32 +48,58 @@ Windsurf and other clients take the same `command`, `args` and `env`.
56
48
  claude mcp add vocalstack -e VOCALSTACK_API_KEY=your-api-key -- npx -y @vocalstack/mcp
57
49
  ```
58
50
 
59
- Claude Code also supports remote servers directly:
51
+ ### Hosted alternative
52
+
53
+ Clients that support remote MCP servers can use VocalStack's hosted endpoint instead, with no install and no API key: add `https://api.vocalstack.com/v1/mcp` and sign in with your VocalStack account when the client asks. In Claude Code:
60
54
 
61
55
  ```sh
62
56
  claude mcp add --transport http vocalstack https://api.vocalstack.com/v1/mcp
63
57
  ```
64
58
 
65
- ### Remote, no install
66
-
67
- In clients that support remote MCP servers, add:
68
-
69
- ```
70
- https://api.vocalstack.com/v1/mcp
71
- ```
72
-
73
- The client opens a VocalStack sign-in page the first time it needs it.
59
+ Both offer the same tools.
74
60
 
75
61
  ## Tools
76
62
 
77
- The tools come from VocalStack's hosted server, so the list is always current without updating this package. Ask your assistant what VocalStack can do, or see [vocalstack.com](https://vocalstack.com/).
63
+ <!-- tools -->
64
+ - `transcribe_url`: Start transcribing a recorded audio or video at a public link: a media file, a podcast episode, a YouTube video, or a public post on one of the sites listed under url.
65
+ - `transcribe_file`: Start transcribing an audio or video file you hold, sent whole as base64 (at most 10 MiB decoded; mp3, m4a, wav, mp4, webm and other common formats).
66
+ - `get_transcription`: Read one transcription's text, with timestamps and speakers, and its status.
67
+ - `wait_for_transcription`: Wait until a file or link transcription finishes, up to timeoutS seconds (default 50, at most 60), and return its status without the text.
68
+ - `list_transcriptions`: List this account's transcriptions (files, links and live ones, including those recorded by broadcasts), newest first, one page at a time.
69
+ - `search_transcriptions`: Find the lines where given words or a name were said, across all of this account's transcriptions or in one (transcriptionId).
70
+ - `search_by_meaning`: Find the passages closest in meaning to a question or topic, across this account's transcriptions or in one (transcriptionId), in any language and even when they share none of its words.
71
+ - `get_summary`: Get the title and summary of a finished transcription.
72
+ - `translate_transcription`: Get a whole finished transcription translated into another language, in the same text or segments shape as get_transcription.
73
+ - `rename_speaker`: Name a speaker in one transcription, so its transcript shows the name instead of "Speaker N".
74
+ - `delete_transcription`: Delete a transcription: it moves to the trash with its recordings, transcript, translations and summary, and its share links stop working.
75
+ - `list_voices`: List the voices that can read translations aloud in one language: stock voices and this account's own cloned voices.
76
+ - `set_cloned_voices`: Turn cloned voices on or off for one transcription's spoken translations.
77
+ - `list_speakers`: List the speakers this account has saved: people named once so they are recognised by name in later transcriptions.
78
+ - `list_broadcasts`: List this account's broadcasts, most recently updated first (up to 500, no paging).
79
+ - `get_broadcast`: Get one broadcast in detail: whether it is on air, its public link, the transcriptions it recorded and the stream addresses it uses.
80
+ - `start_broadcast`: Start live transcription and translation of a live stream (YouTube live, internet radio, HLS .m3u8 or Icecast).
81
+ - `stop_broadcast`: Stop the live transcription a broadcast is running (started with start_broadcast), which also stops its billing.
82
+ <!-- /tools -->
83
+
84
+ Errors come back as tool results with `isError` set and a body with `error` (a code such as `not_found`, `invalid_options`, `invalid_state`, `insufficient_credit` or `rate_limited`), `message`, `retryable`, `retryAfterS` and `topUpUrl` when credit is needed. Retry a start with the same `idempotencyKey` so nothing is made or billed twice.
78
85
 
79
86
  ## Settings
80
87
 
81
88
  | Variable | Meaning |
82
89
  | --- | --- |
83
90
  | `VOCALSTACK_API_KEY` | Your API key. |
84
- | `VOCALSTACK_MCP_URL` | Another server address, for testing. Defaults to `https://api.vocalstack.com/v1/mcp`. |
91
+ | `VOCALSTACK_API_URL` | Another API address, for testing. Defaults to `https://api.vocalstack.com`. |
92
+
93
+ ## Development
94
+
95
+ ```sh
96
+ npm ci
97
+ npm test # builds, then runs the tests against a fake API
98
+ npm run sync-tools # refreshes src/tools.json (and the list above) from VocalStack's published tool definitions
99
+ npm run smoke # starts the built server with no key and checks its tools against tools.json and the published list
100
+ ```
101
+
102
+ Tool names, descriptions and argument schemas live in `src/tools.json` and are kept identical to the hosted server's; `src/handlers.ts` implements each one on the REST API. A daily check fails when they drift apart.
85
103
 
86
104
  ## License
87
105
 
package/dist/api.js ADDED
@@ -0,0 +1,112 @@
1
+ import { ToolError } from "./errors.js";
2
+ const DEFAULT_TIMEOUT_MS = 120_000;
3
+ function linked(outer, timeoutMs) {
4
+ const controller = new AbortController();
5
+ let expired = false;
6
+ const timer = setTimeout(() => {
7
+ expired = true;
8
+ controller.abort();
9
+ }, timeoutMs);
10
+ const onAbort = () => controller.abort();
11
+ if (outer?.aborted)
12
+ controller.abort();
13
+ else
14
+ outer?.addEventListener("abort", onAbort, { once: true });
15
+ return {
16
+ signal: controller.signal,
17
+ done: () => {
18
+ clearTimeout(timer);
19
+ outer?.removeEventListener("abort", onAbort);
20
+ },
21
+ timedOut: () => expired,
22
+ };
23
+ }
24
+ function fallbackCode(status) {
25
+ if (status === 401)
26
+ return "invalid_token";
27
+ if (status === 403)
28
+ return "forbidden";
29
+ if (status === 404)
30
+ return "not_found";
31
+ if (status === 409)
32
+ return "conflict";
33
+ if (status === 429)
34
+ return "rate_limited";
35
+ if (status === 504)
36
+ return "timeout";
37
+ if (status >= 500)
38
+ return status === 500 ? "internal" : "unavailable";
39
+ return "invalid_options";
40
+ }
41
+ export class Api {
42
+ apiKey;
43
+ userAgent;
44
+ origin;
45
+ constructor(baseUrl, apiKey, userAgent) {
46
+ this.apiKey = apiKey;
47
+ this.userAgent = userAgent;
48
+ this.origin = baseUrl.replace(/\/+$/, "");
49
+ }
50
+ url(path, query) {
51
+ const u = new URL(this.origin + path);
52
+ for (const [k, v] of Object.entries(query ?? {})) {
53
+ if (v !== undefined && v !== null)
54
+ u.searchParams.set(k, String(v));
55
+ }
56
+ return u.toString();
57
+ }
58
+ async request(method, path, opts = {}) {
59
+ const headers = {
60
+ authorization: `Bearer ${this.apiKey}`,
61
+ "user-agent": this.userAgent,
62
+ accept: "application/json",
63
+ };
64
+ let body;
65
+ if (opts.form)
66
+ body = opts.form;
67
+ else if (opts.json !== undefined) {
68
+ headers["content-type"] = "application/json";
69
+ body = JSON.stringify(opts.json);
70
+ }
71
+ if (opts.idempotencyKey)
72
+ headers["idempotency-key"] = opts.idempotencyKey;
73
+ const t = linked(opts.signal, opts.timeoutMs ?? DEFAULT_TIMEOUT_MS);
74
+ let res;
75
+ let text;
76
+ try {
77
+ res = await fetch(this.url(path, opts.query), { method, headers, body, signal: t.signal });
78
+ text = await res.text();
79
+ }
80
+ catch (error) {
81
+ if (t.timedOut())
82
+ throw new ToolError("timeout", "VocalStack did not answer in time; try again.");
83
+ if (opts.signal?.aborted)
84
+ throw new ToolError("timeout", "The call was cancelled.");
85
+ const why = error instanceof Error ? (error.cause instanceof Error ? error.cause.message : error.message) : String(error);
86
+ throw new ToolError("unavailable", `Could not reach VocalStack (${why}).`);
87
+ }
88
+ finally {
89
+ t.done();
90
+ }
91
+ let parsed = undefined;
92
+ if (text) {
93
+ try {
94
+ parsed = JSON.parse(text);
95
+ }
96
+ catch {
97
+ parsed = undefined;
98
+ }
99
+ }
100
+ if (!res.ok) {
101
+ const code = typeof parsed?.code === "string" ? parsed.code : fallbackCode(res.status);
102
+ const message = typeof parsed?.message === "string" && parsed.message ? parsed.message : `VocalStack answered HTTP ${res.status}.`;
103
+ const details = parsed?.data?.details && typeof parsed.data.details === "object" ? parsed.data.details : {};
104
+ const retryable = typeof parsed?.data?.retryable === "boolean" ? parsed.data.retryable : undefined;
105
+ throw new ToolError(code, message, details, res.status, retryable);
106
+ }
107
+ return { data: parsed, headers: res.headers };
108
+ }
109
+ get(path, query, signal) {
110
+ return this.request("GET", path, { query, signal }).then((r) => r.data);
111
+ }
112
+ }
package/dist/args.js ADDED
@@ -0,0 +1,90 @@
1
+ import { bad } from "./errors.js";
2
+ const UUID = /^(?:[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}|[0-9a-f]{32})$/i;
3
+ export class Args {
4
+ raw;
5
+ constructor(raw) {
6
+ this.raw = raw;
7
+ }
8
+ static parse(schema, value) {
9
+ let m;
10
+ if (value === undefined || value === null)
11
+ m = {};
12
+ else if (typeof value === "object" && !Array.isArray(value))
13
+ m = value;
14
+ else
15
+ throw bad("arguments must be an object");
16
+ const props = Object.keys(schema.properties ?? {}).sort();
17
+ const unknown = Object.keys(m).find((k) => !props.includes(k));
18
+ if (unknown !== undefined) {
19
+ throw bad(`unknown argument \`${unknown}\`; this tool takes ${props.join(", ")}`);
20
+ }
21
+ for (const r of schema.required ?? []) {
22
+ if (m[r] === undefined || m[r] === null)
23
+ throw bad(`\`${r}\` is required`);
24
+ }
25
+ return new Args(m);
26
+ }
27
+ str(k) {
28
+ const v = this.raw[k];
29
+ if (v === undefined || v === null)
30
+ return undefined;
31
+ if (typeof v !== "string")
32
+ throw bad(`\`${k}\` must be a string`);
33
+ const t = v.trim();
34
+ return t ? t : undefined;
35
+ }
36
+ reqStr(k) {
37
+ const v = this.str(k);
38
+ if (v === undefined)
39
+ throw bad(`\`${k}\` is required`);
40
+ return v;
41
+ }
42
+ rawStr(k) {
43
+ const v = this.raw[k];
44
+ return typeof v === "string" ? v : undefined;
45
+ }
46
+ num(k) {
47
+ const v = this.raw[k];
48
+ if (v === undefined || v === null)
49
+ return undefined;
50
+ if (typeof v !== "number" || !Number.isFinite(v))
51
+ throw bad(`\`${k}\` must be a number`);
52
+ return v;
53
+ }
54
+ int(k, def, min, max) {
55
+ const v = this.raw[k];
56
+ if (v === undefined || v === null)
57
+ return def;
58
+ if (typeof v === "number" && Number.isInteger(v) && v >= 0 && v >= min && v <= max)
59
+ return v;
60
+ throw bad(`\`${k}\` must be an integer from ${min} to ${max}`);
61
+ }
62
+ bool(k) {
63
+ const v = this.raw[k];
64
+ if (v === undefined || v === null)
65
+ return false;
66
+ if (typeof v !== "boolean")
67
+ throw bad(`\`${k}\` must be true or false`);
68
+ return v;
69
+ }
70
+ oneOf(k, allowed, def) {
71
+ const v = this.str(k) ?? def;
72
+ if (!allowed.includes(v))
73
+ throw bad(`\`${k}\` must be one of ${allowed.join(", ")}`);
74
+ return v;
75
+ }
76
+ id(k) {
77
+ const v = this.reqStr(k);
78
+ if (!UUID.test(v))
79
+ throw bad(`\`${k}\` must be a UUID`);
80
+ return v.toLowerCase();
81
+ }
82
+ optId(k) {
83
+ const v = this.str(k);
84
+ if (v === undefined)
85
+ return undefined;
86
+ if (!UUID.test(v))
87
+ throw bad(`\`${k}\` must be a UUID`);
88
+ return v.toLowerCase();
89
+ }
90
+ }
package/dist/errors.js ADDED
@@ -0,0 +1,39 @@
1
+ const STATUS = {
2
+ invalid_audio: 400,
3
+ invalid_options: 400,
4
+ invalid_token: 401,
5
+ forbidden: 403,
6
+ not_found: 404,
7
+ conflict: 409,
8
+ invalid_state: 409,
9
+ idempotency_key_reused: 422,
10
+ rate_limited: 429,
11
+ internal: 500,
12
+ unavailable: 503,
13
+ timeout: 504,
14
+ };
15
+ const RETRYABLE = new Set([
16
+ "capacity_exceeded",
17
+ "engine_unavailable",
18
+ "engine_lost",
19
+ "rate_limited",
20
+ "preview_pending",
21
+ "timeout",
22
+ "unavailable",
23
+ ]);
24
+ export class ToolError extends Error {
25
+ code;
26
+ details;
27
+ status;
28
+ retryable;
29
+ constructor(code, message, details = {}, status, retryable) {
30
+ super(message);
31
+ this.code = code;
32
+ this.details = details;
33
+ this.status = status ?? STATUS[code] ?? 400;
34
+ this.retryable = retryable ?? RETRYABLE.has(code);
35
+ }
36
+ }
37
+ export function bad(message) {
38
+ return new ToolError("invalid_options", message);
39
+ }