@vocalstack/mcp 0.0.0-stage → 1.0.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.
Files changed (4) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +87 -2
  3. package/dist/index.js +213 -0
  4. package/package.json +46 -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,88 @@
1
- # Temporary Holding Version
1
+ # @vocalstack/mcp
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
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.
4
+
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.
6
+
7
+ ## API key
8
+
9
+ 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
+
11
+ ## Setup
12
+
13
+ Requires Node.js 20 or later.
14
+
15
+ ### Claude Desktop
16
+
17
+ Add this to `claude_desktop_config.json` (Settings → Developer → Edit Config), then restart Claude Desktop:
18
+
19
+ ```json
20
+ {
21
+ "mcpServers": {
22
+ "vocalstack": {
23
+ "command": "npx",
24
+ "args": ["-y", "@vocalstack/mcp"],
25
+ "env": {
26
+ "VOCALSTACK_API_KEY": "your-api-key"
27
+ }
28
+ }
29
+ }
30
+ }
31
+ ```
32
+
33
+ ### Cursor
34
+
35
+ Add this to `~/.cursor/mcp.json` (all projects) or `.cursor/mcp.json` (one project):
36
+
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
+ ```
50
+
51
+ Windsurf and other clients take the same `command`, `args` and `env`.
52
+
53
+ ### Claude Code
54
+
55
+ ```sh
56
+ claude mcp add vocalstack -e VOCALSTACK_API_KEY=your-api-key -- npx -y @vocalstack/mcp
57
+ ```
58
+
59
+ Claude Code also supports remote servers directly:
60
+
61
+ ```sh
62
+ claude mcp add --transport http vocalstack https://api.vocalstack.com/v1/mcp
63
+ ```
64
+
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.
74
+
75
+ ## Tools
76
+
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/).
78
+
79
+ ## Settings
80
+
81
+ | Variable | Meaning |
82
+ | --- | --- |
83
+ | `VOCALSTACK_API_KEY` | Your API key. |
84
+ | `VOCALSTACK_MCP_URL` | Another server address, for testing. Defaults to `https://api.vocalstack.com/v1/mcp`. |
85
+
86
+ ## License
87
+
88
+ MIT
package/dist/index.js ADDED
@@ -0,0 +1,213 @@
1
+ #!/usr/bin/env node
2
+ import { readFileSync } from "node:fs";
3
+ import { Client } from "@modelcontextprotocol/sdk/client/index.js";
4
+ import { StreamableHTTPClientTransport, StreamableHTTPError, } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
5
+ import { UnauthorizedError } from "@modelcontextprotocol/sdk/client/auth.js";
6
+ import { Server } from "@modelcontextprotocol/sdk/server/index.js";
7
+ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
8
+ import { CallToolRequestSchema, CallToolResultSchema, ErrorCode, ListToolsRequestSchema, ListToolsResultSchema, McpError, } from "@modelcontextprotocol/sdk/types.js";
9
+ const DEFAULT_URL = "https://api.vocalstack.com/v1/mcp";
10
+ const KEY_MISSING = "Set VOCALSTACK_API_KEY to an API key from https://app.vocalstack.com (Developers → API keys).";
11
+ const KEY_REFUSED = "The API key was refused. Check that VOCALSTACK_API_KEY holds a current API key from https://app.vocalstack.com (Developers → API keys).";
12
+ const REQUEST_TIMEOUT_MS = 60 * 60 * 1000;
13
+ const MAX_STDIN_MESSAGE_BYTES = 64 * 1024 * 1024;
14
+ const VERSION = (() => {
15
+ try {
16
+ const pkg = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
17
+ return typeof pkg.version === "string" ? pkg.version : "0.0.0";
18
+ }
19
+ catch {
20
+ return "0.0.0";
21
+ }
22
+ })();
23
+ function log(message) {
24
+ process.stderr.write(`[vocalstack-mcp] ${message}\n`);
25
+ }
26
+ class ForwardedError extends Error {
27
+ code;
28
+ data;
29
+ constructor(code, message, data) {
30
+ super(message);
31
+ this.code = code;
32
+ this.data = data;
33
+ }
34
+ }
35
+ function unprefixed(message) {
36
+ return message.replace(/^MCP error -?\d+: /, "");
37
+ }
38
+ function isUnauthorized(error) {
39
+ return (error instanceof UnauthorizedError ||
40
+ (error instanceof StreamableHTTPError && error.code === 401));
41
+ }
42
+ function isSessionGone(error) {
43
+ return error instanceof StreamableHTTPError && error.code === 404;
44
+ }
45
+ class Remote {
46
+ url;
47
+ apiKey;
48
+ client;
49
+ connecting;
50
+ constructor(url, apiKey) {
51
+ this.url = url;
52
+ this.apiKey = apiKey;
53
+ }
54
+ get hasKey() {
55
+ return Boolean(this.apiKey);
56
+ }
57
+ connect() {
58
+ if (this.client)
59
+ return Promise.resolve(this.client);
60
+ if (!this.connecting) {
61
+ this.connecting = this.open().then((client) => {
62
+ this.client = client;
63
+ this.connecting = undefined;
64
+ return client;
65
+ }, (error) => {
66
+ this.connecting = undefined;
67
+ throw error;
68
+ });
69
+ }
70
+ return this.connecting;
71
+ }
72
+ async open() {
73
+ const headers = { "User-Agent": `vocalstack-mcp/${VERSION}` };
74
+ if (this.apiKey)
75
+ headers.Authorization = `Bearer ${this.apiKey}`;
76
+ const transport = new StreamableHTTPClientTransport(this.url, { requestInit: { headers } });
77
+ const client = new Client({ name: "vocalstack-mcp", version: VERSION }, { capabilities: {} });
78
+ client.onerror = (error) => {
79
+ if (!isUnauthorized(error))
80
+ log(`remote: ${error.message}`);
81
+ };
82
+ client.onclose = () => {
83
+ if (this.client === client)
84
+ this.client = undefined;
85
+ };
86
+ await client.connect(transport);
87
+ return client;
88
+ }
89
+ async reset() {
90
+ const client = this.client;
91
+ this.client = undefined;
92
+ if (client)
93
+ await client.close().catch(() => { });
94
+ }
95
+ async call(run) {
96
+ try {
97
+ return await run(await this.connect());
98
+ }
99
+ catch (error) {
100
+ if (!isSessionGone(error))
101
+ throw error;
102
+ await this.reset();
103
+ return run(await this.connect());
104
+ }
105
+ }
106
+ }
107
+ function forward(error) {
108
+ if (error instanceof McpError) {
109
+ throw new ForwardedError(error.code, unprefixed(error.message), error.data);
110
+ }
111
+ throw error;
112
+ }
113
+ async function main() {
114
+ const url = new URL(process.env.VOCALSTACK_MCP_URL || DEFAULT_URL);
115
+ const apiKey = process.env.VOCALSTACK_API_KEY?.trim() || undefined;
116
+ const remote = new Remote(url, apiKey);
117
+ let info = { name: "vocalstack", version: VERSION };
118
+ let instructions;
119
+ try {
120
+ const client = await remote.connect();
121
+ info = client.getServerVersion() ?? info;
122
+ instructions = client.getInstructions();
123
+ }
124
+ catch (error) {
125
+ if (isUnauthorized(error))
126
+ log(apiKey ? KEY_REFUSED : KEY_MISSING);
127
+ else
128
+ log(`could not reach ${url.href} yet: ${error instanceof Error ? error.message : String(error)}`);
129
+ }
130
+ let stopping = false;
131
+ const shutdown = async () => {
132
+ if (stopping)
133
+ return;
134
+ stopping = true;
135
+ await remote.reset();
136
+ process.exit(0);
137
+ };
138
+ let pending = 0;
139
+ let ending = false;
140
+ const tracked = async (run) => {
141
+ pending++;
142
+ try {
143
+ return await run();
144
+ }
145
+ finally {
146
+ pending--;
147
+ if (ending && pending === 0)
148
+ setImmediate(() => void shutdown());
149
+ }
150
+ };
151
+ const authMessage = () => (remote.hasKey ? KEY_REFUSED : KEY_MISSING);
152
+ const server = new Server(info, {
153
+ capabilities: { tools: { listChanged: false } },
154
+ ...(instructions ? { instructions } : {}),
155
+ });
156
+ server.setRequestHandler(ListToolsRequestSchema, (request, extra) => tracked(async () => {
157
+ try {
158
+ return await remote.call((client) => client.request({ method: "tools/list", params: request.params }, ListToolsResultSchema, {
159
+ signal: extra.signal,
160
+ timeout: REQUEST_TIMEOUT_MS,
161
+ }));
162
+ }
163
+ catch (error) {
164
+ if (isUnauthorized(error))
165
+ throw new ForwardedError(ErrorCode.InvalidRequest, authMessage());
166
+ forward(error);
167
+ }
168
+ }));
169
+ server.setRequestHandler(CallToolRequestSchema, (request, extra) => tracked(async () => {
170
+ const progressToken = request.params._meta?.progressToken;
171
+ try {
172
+ return await remote.call((client) => client.request({ method: "tools/call", params: request.params }, CallToolResultSchema, {
173
+ signal: extra.signal,
174
+ timeout: REQUEST_TIMEOUT_MS,
175
+ resetTimeoutOnProgress: true,
176
+ ...(progressToken !== undefined
177
+ ? {
178
+ onprogress: (progress) => {
179
+ extra
180
+ .sendNotification({
181
+ method: "notifications/progress",
182
+ params: { ...progress, progressToken },
183
+ })
184
+ .catch(() => { });
185
+ },
186
+ }
187
+ : {}),
188
+ }));
189
+ }
190
+ catch (error) {
191
+ if (isUnauthorized(error)) {
192
+ return { content: [{ type: "text", text: authMessage() }], isError: true };
193
+ }
194
+ forward(error);
195
+ }
196
+ }));
197
+ const stdio = new StdioServerTransport(process.stdin, process.stdout, {
198
+ maxBufferSize: MAX_STDIN_MESSAGE_BYTES,
199
+ });
200
+ stdio.onclose = () => void shutdown();
201
+ process.stdin.on("end", () => {
202
+ ending = true;
203
+ if (pending === 0)
204
+ setImmediate(() => void shutdown());
205
+ });
206
+ process.on("SIGINT", () => void shutdown());
207
+ process.on("SIGTERM", () => void shutdown());
208
+ await server.connect(stdio);
209
+ }
210
+ main().catch((error) => {
211
+ log(error instanceof Error ? (error.stack ?? error.message) : String(error));
212
+ process.exit(1);
213
+ });
package/package.json CHANGED
@@ -1,6 +1,48 @@
1
1
  {
2
2
  "name": "@vocalstack/mcp",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "1.0.0",
4
+ "description": "VocalStack MCP server: transcribe, translate, search and summarize audio and video, and run live broadcasts, from any MCP client.",
5
+ "license": "MIT",
6
+ "type": "module",
7
+ "mcpName": "com.vocalstack/mcp",
8
+ "bin": {
9
+ "vocalstack-mcp": "dist/index.js"
10
+ },
11
+ "files": [
12
+ "dist",
13
+ "README.md",
14
+ "LICENSE"
15
+ ],
16
+ "engines": {
17
+ "node": ">=20"
18
+ },
19
+ "repository": {
20
+ "type": "git",
21
+ "url": "git+https://github.com/vocalstack/mcp.git"
22
+ },
23
+ "homepage": "https://vocalstack.com/",
24
+ "keywords": [
25
+ "mcp",
26
+ "model-context-protocol",
27
+ "transcription",
28
+ "speech-to-text",
29
+ "translation",
30
+ "live-captions",
31
+ "vocalstack"
32
+ ],
33
+ "scripts": {
34
+ "build": "tsc -p tsconfig.json && chmod +x dist/index.js",
35
+ "test": "npm run build && node --test test/*.test.mjs",
36
+ "prepublishOnly": "npm run build"
37
+ },
38
+ "dependencies": {
39
+ "@modelcontextprotocol/sdk": "^1.32.2"
40
+ },
41
+ "devDependencies": {
42
+ "@types/node": "^20.19.43",
43
+ "typescript": "^7.0.2"
44
+ },
45
+ "publishConfig": {
46
+ "access": "public"
47
+ }
48
+ }