@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 +44 -29
- package/dist/api.js +112 -0
- package/dist/args.js +90 -0
- package/dist/errors.js +39 -0
- package/dist/handlers.js +964 -0
- package/dist/index.js +26 -184
- package/dist/result.js +59 -0
- package/dist/server.js +49 -0
- package/dist/tools.json +708 -0
- package/package.json +7 -4
package/README.md
CHANGED
|
@@ -1,13 +1,17 @@
|
|
|
1
1
|
# @vocalstack/mcp
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
[](https://glama.ai/mcp/servers/vocalstack/mcp)
|
|
4
|
+
[](https://glama.ai/mcp/connectors/com.vocalstack/mcp)
|
|
5
|
+
[](https://mcptry.com/servers/com.vocalstack/mcp)
|
|
4
6
|
|
|
5
|
-
|
|
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
|
|
39
|
+
Add the same block to `~/.cursor/mcp.json` (all projects) or `.cursor/mcp.json` (one project).
|
|
36
40
|
|
|
37
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
| `
|
|
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
|
+
}
|