@vocalstack/mcp 1.0.0 → 1.3.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,55 @@ 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`: Start transcribing a finished recording, from a public link or a file sent inline; returns a transcriptionId at once, before any text.
65
+ - `get_transcription`: Read one transcription's status and text, with timestamps and speakers: as it was spoken or translated, at once or after waiting for it to finish.
66
+ - `list_transcriptions`: List this account's transcriptions, newest first, a page at a time: files, links and live ones, including those broadcasts recorded.
67
+ - `search_transcriptions`: Find what was said across this account's transcriptions, or in one: the lines with given words or a name (mode words), or the passages that answer a question (mode meaning).
68
+ - `get_summary`: Get the title and summary of a finished transcription, writing one the first time if it has none.
69
+ - `rename_speaker`: Name a speaker in one transcription, so its transcript shows the name instead of "Speaker N".
70
+ - `delete_transcription`: Move a transcription to the trash, with its recordings, transcript, translations and summary; its share links stop working.
71
+ - `restore_transcription`: Bring a deleted transcription back from the trash, with its recordings, transcript, translations, summary and working share links.
72
+ - `set_cloned_voices`: Turn cloned voices on or off for one transcription's spoken translations.
73
+ - `list_speakers`: List the speakers this account has saved: people recognised by name in every new transcription.
74
+ - `save_speaker`: Save one speaker of a transcription to the account's saved speakers, so later transcriptions recognise and name them; their own speech in this transcription is the sample.
75
+ - `delete_speaker`: Delete a saved speaker for good: their name, fingerprint, stored sample and any cloned voice are erased at once and cannot be restored.
76
+ - `list_broadcasts`: List this account's broadcasts, or get one in detail.
77
+ - `start_broadcast`: Start live transcription and translation of a stream playing now, on a public link listeners open in their own language.
78
+ - `stop_broadcast`: Stop the live transcription a broadcast is running, which also stops its billing.
79
+ <!-- /tools -->
80
+
81
+ 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
82
 
79
83
  ## Settings
80
84
 
81
85
  | Variable | Meaning |
82
86
  | --- | --- |
83
87
  | `VOCALSTACK_API_KEY` | Your API key. |
84
- | `VOCALSTACK_MCP_URL` | Another server address, for testing. Defaults to `https://api.vocalstack.com/v1/mcp`. |
88
+ | `VOCALSTACK_API_URL` | Another API address, for testing. Defaults to `https://api.vocalstack.com`. |
89
+
90
+ ## Development
91
+
92
+ ```sh
93
+ npm ci
94
+ npm test # builds, then runs the tests against a fake API
95
+ npm run sync-tools # refreshes src/tools.json (and the list above) from VocalStack's published tool definitions
96
+ npm run smoke # starts the built server with no key and checks its tools against tools.json and the published list
97
+ ```
98
+
99
+ 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
100
 
86
101
  ## License
87
102
 
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
+ }