@vocalstack/mcp 0.0.0-stage → 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/LICENSE +21 -0
- package/README.md +105 -2
- package/dist/api.js +112 -0
- package/dist/args.js +90 -0
- package/dist/errors.js +39 -0
- package/dist/handlers.js +835 -0
- package/dist/index.js +55 -0
- package/dist/result.js +59 -0
- package/dist/server.js +49 -0
- package/dist/tools.json +847 -0
- package/package.json +49 -4
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 VocalStack
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,106 @@
|
|
|
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)
|
|
6
|
+
|
|
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.
|
|
8
|
+
|
|
9
|
+
## API key
|
|
10
|
+
|
|
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.
|
|
12
|
+
|
|
13
|
+
Only transcription is billed, per second of audio. Reading, searching, summaries, translations and listeners are free.
|
|
14
|
+
|
|
15
|
+
## Setup
|
|
16
|
+
|
|
17
|
+
Requires Node.js 20 or later.
|
|
18
|
+
|
|
19
|
+
### Claude Desktop
|
|
20
|
+
|
|
21
|
+
Add this to `claude_desktop_config.json` (Settings → Developer → Edit Config), then restart Claude Desktop:
|
|
22
|
+
|
|
23
|
+
```json
|
|
24
|
+
{
|
|
25
|
+
"mcpServers": {
|
|
26
|
+
"vocalstack": {
|
|
27
|
+
"command": "npx",
|
|
28
|
+
"args": ["-y", "@vocalstack/mcp"],
|
|
29
|
+
"env": {
|
|
30
|
+
"VOCALSTACK_API_KEY": "your-api-key"
|
|
31
|
+
}
|
|
32
|
+
}
|
|
33
|
+
}
|
|
34
|
+
}
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
### Cursor
|
|
38
|
+
|
|
39
|
+
Add the same block to `~/.cursor/mcp.json` (all projects) or `.cursor/mcp.json` (one project).
|
|
40
|
+
|
|
41
|
+
### Windsurf
|
|
42
|
+
|
|
43
|
+
Add the same block to `~/.codeium/windsurf/mcp_config.json`, then refresh the MCP servers in Windsurf's settings.
|
|
44
|
+
|
|
45
|
+
### Claude Code
|
|
46
|
+
|
|
47
|
+
```sh
|
|
48
|
+
claude mcp add vocalstack -e VOCALSTACK_API_KEY=your-api-key -- npx -y @vocalstack/mcp
|
|
49
|
+
```
|
|
50
|
+
|
|
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:
|
|
54
|
+
|
|
55
|
+
```sh
|
|
56
|
+
claude mcp add --transport http vocalstack https://api.vocalstack.com/v1/mcp
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
Both offer the same tools.
|
|
60
|
+
|
|
61
|
+
## Tools
|
|
62
|
+
|
|
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.
|
|
85
|
+
|
|
86
|
+
## Settings
|
|
87
|
+
|
|
88
|
+
| Variable | Meaning |
|
|
89
|
+
| --- | --- |
|
|
90
|
+
| `VOCALSTACK_API_KEY` | Your API key. |
|
|
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.
|
|
103
|
+
|
|
104
|
+
## License
|
|
105
|
+
|
|
106
|
+
MIT
|
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
|
+
}
|