@vocalstack/mcp 1.0.0 → 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/README.md +47 -29
- 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 +26 -184
- package/dist/result.js +59 -0
- package/dist/server.js +49 -0
- package/dist/tools.json +847 -0
- package/package.json +7 -4
package/dist/index.js
CHANGED
|
@@ -1,211 +1,53 @@
|
|
|
1
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
2
|
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
|
|
8
|
-
import {
|
|
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;
|
|
3
|
+
import { createServer } from "./server.js";
|
|
13
4
|
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
5
|
function log(message) {
|
|
24
6
|
process.stderr.write(`[vocalstack-mcp] ${message}\n`);
|
|
25
7
|
}
|
|
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
8
|
async function main() {
|
|
114
|
-
const url = new URL(process.env.VOCALSTACK_MCP_URL || DEFAULT_URL);
|
|
115
9
|
const apiKey = process.env.VOCALSTACK_API_KEY?.trim() || undefined;
|
|
116
|
-
const
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
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
|
-
}
|
|
10
|
+
const baseUrl = process.env.VOCALSTACK_API_URL?.trim() || undefined;
|
|
11
|
+
if (!apiKey)
|
|
12
|
+
log("VOCALSTACK_API_KEY is not set: the tools are listed, and each call asks for a key.");
|
|
13
|
+
const server = createServer({ apiKey, baseUrl });
|
|
130
14
|
let stopping = false;
|
|
131
15
|
const shutdown = async () => {
|
|
132
16
|
if (stopping)
|
|
133
17
|
return;
|
|
134
18
|
stopping = true;
|
|
135
|
-
await
|
|
19
|
+
await server.close().catch(() => { });
|
|
136
20
|
process.exit(0);
|
|
137
21
|
};
|
|
138
22
|
let pending = 0;
|
|
139
23
|
let ending = false;
|
|
140
|
-
const
|
|
141
|
-
pending
|
|
142
|
-
|
|
143
|
-
return await run();
|
|
144
|
-
}
|
|
145
|
-
finally {
|
|
146
|
-
pending--;
|
|
147
|
-
if (ending && pending === 0)
|
|
148
|
-
setImmediate(() => void shutdown());
|
|
149
|
-
}
|
|
24
|
+
const settle = () => {
|
|
25
|
+
if (ending && pending === 0)
|
|
26
|
+
setImmediate(() => void shutdown());
|
|
150
27
|
};
|
|
151
|
-
const
|
|
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
|
-
});
|
|
28
|
+
const stdio = new StdioServerTransport(process.stdin, process.stdout, { maxBufferSize: MAX_STDIN_MESSAGE_BYTES });
|
|
200
29
|
stdio.onclose = () => void shutdown();
|
|
30
|
+
await server.connect(stdio);
|
|
31
|
+
const receive = stdio.onmessage;
|
|
32
|
+
stdio.onmessage = (message) => {
|
|
33
|
+
if ("method" in message && "id" in message)
|
|
34
|
+
pending++;
|
|
35
|
+
receive?.(message);
|
|
36
|
+
};
|
|
37
|
+
const send = stdio.send.bind(stdio);
|
|
38
|
+
stdio.send = async (message) => {
|
|
39
|
+
await send(message);
|
|
40
|
+
if ("id" in message && ("result" in message || "error" in message)) {
|
|
41
|
+
pending = Math.max(0, pending - 1);
|
|
42
|
+
settle();
|
|
43
|
+
}
|
|
44
|
+
};
|
|
201
45
|
process.stdin.on("end", () => {
|
|
202
46
|
ending = true;
|
|
203
|
-
|
|
204
|
-
setImmediate(() => void shutdown());
|
|
47
|
+
settle();
|
|
205
48
|
});
|
|
206
49
|
process.on("SIGINT", () => void shutdown());
|
|
207
50
|
process.on("SIGTERM", () => void shutdown());
|
|
208
|
-
await server.connect(stdio);
|
|
209
51
|
}
|
|
210
52
|
main().catch((error) => {
|
|
211
53
|
log(error instanceof Error ? (error.stack ?? error.message) : String(error));
|
package/dist/result.js
ADDED
|
@@ -0,0 +1,59 @@
|
|
|
1
|
+
export const KEY_MISSING = "Set VOCALSTACK_API_KEY to an API key from https://app.vocalstack.com (Developers → API keys).";
|
|
2
|
+
export 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).";
|
|
3
|
+
export const TOP_UP_URL = "https://app.vocalstack.com/billing";
|
|
4
|
+
function sorted(v) {
|
|
5
|
+
if (Array.isArray(v))
|
|
6
|
+
return v.map(sorted);
|
|
7
|
+
if (v && typeof v === "object") {
|
|
8
|
+
const o = {};
|
|
9
|
+
for (const k of Object.keys(v).sort())
|
|
10
|
+
o[k] = sorted(v[k]);
|
|
11
|
+
return o;
|
|
12
|
+
}
|
|
13
|
+
return v;
|
|
14
|
+
}
|
|
15
|
+
export function toolOk(v) {
|
|
16
|
+
const body = sorted(v);
|
|
17
|
+
return { content: [{ type: "text", text: JSON.stringify(body, null, 2) }], structuredContent: body };
|
|
18
|
+
}
|
|
19
|
+
export function toolText(text) {
|
|
20
|
+
return { content: [{ type: "text", text }], isError: true };
|
|
21
|
+
}
|
|
22
|
+
export function toolError(e) {
|
|
23
|
+
const status = e.status;
|
|
24
|
+
const details = e.details ?? {};
|
|
25
|
+
const retryAfter = details.retryAfterS ?? null;
|
|
26
|
+
const topUp = details.topUpUrl ?? (status === 402 ? TOP_UP_URL : null);
|
|
27
|
+
let guidance = "";
|
|
28
|
+
if (status === 402 && e.code === "insufficient_credit") {
|
|
29
|
+
guidance =
|
|
30
|
+
" The account has not enough credit to start this (a new transcription needs more than its minimum charge costs); add credit before trying again.";
|
|
31
|
+
}
|
|
32
|
+
else if (status === 402 && e.code === "usage_cap_reached") {
|
|
33
|
+
guidance =
|
|
34
|
+
typeof details.resetsAt === "string"
|
|
35
|
+
? ` This API key reached the usage cap its account set for it; it resets at ${details.resetsAt}, or the account can raise the cap. Adding credit does not lift it.`
|
|
36
|
+
: " This API key reached the usage cap its account set for it; the account can raise the cap. Adding credit does not lift it.";
|
|
37
|
+
}
|
|
38
|
+
else if (status === 402) {
|
|
39
|
+
guidance = typeof details.resetsAt === "string" ? ` The quota resets at ${details.resetsAt}.` : "";
|
|
40
|
+
}
|
|
41
|
+
else if (status === 429) {
|
|
42
|
+
guidance = ` Wait ${typeof retryAfter === "number" && retryAfter >= 0 ? Math.floor(retryAfter) : 5} seconds before trying again.`;
|
|
43
|
+
}
|
|
44
|
+
else if (status === 503) {
|
|
45
|
+
guidance = " Try again shortly.";
|
|
46
|
+
}
|
|
47
|
+
const message = status === 401 ? KEY_REFUSED : status === 500 ? "Something went wrong on the server." : e.message;
|
|
48
|
+
const body = sorted({
|
|
49
|
+
error: e.code,
|
|
50
|
+
status,
|
|
51
|
+
message,
|
|
52
|
+
retryable: status === 429 || status === 503 || e.retryable,
|
|
53
|
+
retryAfterS: retryAfter,
|
|
54
|
+
topUpUrl: topUp,
|
|
55
|
+
details,
|
|
56
|
+
});
|
|
57
|
+
const stop = guidance === "" || /[.!?]$/.test(message) ? "" : ".";
|
|
58
|
+
return { content: [{ type: "text", text: `${message}${stop}${guidance}` }], structuredContent: body, isError: true };
|
|
59
|
+
}
|
package/dist/server.js
ADDED
|
@@ -0,0 +1,49 @@
|
|
|
1
|
+
import { readFileSync } from "node:fs";
|
|
2
|
+
import { Server } from "@modelcontextprotocol/sdk/server/index.js";
|
|
3
|
+
import { CallToolRequestSchema, ErrorCode, ListToolsRequestSchema, McpError, } from "@modelcontextprotocol/sdk/types.js";
|
|
4
|
+
import { Api } from "./api.js";
|
|
5
|
+
import { Args } from "./args.js";
|
|
6
|
+
import { ToolError } from "./errors.js";
|
|
7
|
+
import { handlers } from "./handlers.js";
|
|
8
|
+
import { KEY_MISSING, toolError, toolOk, toolText } from "./result.js";
|
|
9
|
+
export const definitions = JSON.parse(readFileSync(new URL("./tools.json", import.meta.url), "utf8"));
|
|
10
|
+
export const VERSION = (() => {
|
|
11
|
+
try {
|
|
12
|
+
const pkg = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
|
|
13
|
+
return typeof pkg.version === "string" ? pkg.version : "0.0.0";
|
|
14
|
+
}
|
|
15
|
+
catch {
|
|
16
|
+
return "0.0.0";
|
|
17
|
+
}
|
|
18
|
+
})();
|
|
19
|
+
export function createServer(options) {
|
|
20
|
+
const baseUrl = options.baseUrl || "https://api.vocalstack.com";
|
|
21
|
+
const api = options.apiKey ? new Api(baseUrl, options.apiKey, `vocalstack-mcp/${VERSION}`) : undefined;
|
|
22
|
+
const byName = new Map(definitions.tools.map((t) => [t.name, t]));
|
|
23
|
+
const server = new Server({ name: "vocalstack", version: VERSION }, { capabilities: { tools: { listChanged: false } }, instructions: definitions.instructions });
|
|
24
|
+
server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: definitions.tools }));
|
|
25
|
+
server.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
|
|
26
|
+
const name = request.params.name;
|
|
27
|
+
const tool = byName.get(name);
|
|
28
|
+
const handler = handlers[name];
|
|
29
|
+
if (!tool || !handler)
|
|
30
|
+
throw new McpError(ErrorCode.InvalidParams, `unknown tool ${JSON.stringify(name)}`);
|
|
31
|
+
if (!api)
|
|
32
|
+
return toolText(KEY_MISSING);
|
|
33
|
+
const token = request.params._meta?.progressToken;
|
|
34
|
+
const ctx = { api, signal: extra.signal };
|
|
35
|
+
if (token !== undefined) {
|
|
36
|
+
ctx.progress = (progress, total, message) => extra.sendNotification({ method: "notifications/progress", params: { progressToken: token, progress, total, message } });
|
|
37
|
+
}
|
|
38
|
+
try {
|
|
39
|
+
const args = Args.parse(tool.inputSchema, request.params.arguments);
|
|
40
|
+
return toolOk(await handler(args, ctx));
|
|
41
|
+
}
|
|
42
|
+
catch (e) {
|
|
43
|
+
if (e instanceof ToolError)
|
|
44
|
+
return toolError(e);
|
|
45
|
+
return toolError(new ToolError("internal", e instanceof Error ? e.message : String(e)));
|
|
46
|
+
}
|
|
47
|
+
});
|
|
48
|
+
return server;
|
|
49
|
+
}
|