@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.
- package/LICENSE +21 -0
- package/README.md +87 -2
- package/dist/index.js +213 -0
- 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
|
-
#
|
|
1
|
+
# @vocalstack/mcp
|
|
2
2
|
|
|
3
|
-
|
|
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": "
|
|
4
|
-
"
|
|
5
|
-
"
|
|
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
|
+
}
|