@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/dist/index.js
ADDED
|
@@ -0,0 +1,55 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
|
|
3
|
+
import { createServer } from "./server.js";
|
|
4
|
+
const MAX_STDIN_MESSAGE_BYTES = 64 * 1024 * 1024;
|
|
5
|
+
function log(message) {
|
|
6
|
+
process.stderr.write(`[vocalstack-mcp] ${message}\n`);
|
|
7
|
+
}
|
|
8
|
+
async function main() {
|
|
9
|
+
const apiKey = process.env.VOCALSTACK_API_KEY?.trim() || undefined;
|
|
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 });
|
|
14
|
+
let stopping = false;
|
|
15
|
+
const shutdown = async () => {
|
|
16
|
+
if (stopping)
|
|
17
|
+
return;
|
|
18
|
+
stopping = true;
|
|
19
|
+
await server.close().catch(() => { });
|
|
20
|
+
process.exit(0);
|
|
21
|
+
};
|
|
22
|
+
let pending = 0;
|
|
23
|
+
let ending = false;
|
|
24
|
+
const settle = () => {
|
|
25
|
+
if (ending && pending === 0)
|
|
26
|
+
setImmediate(() => void shutdown());
|
|
27
|
+
};
|
|
28
|
+
const stdio = new StdioServerTransport(process.stdin, process.stdout, { maxBufferSize: MAX_STDIN_MESSAGE_BYTES });
|
|
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
|
+
};
|
|
45
|
+
process.stdin.on("end", () => {
|
|
46
|
+
ending = true;
|
|
47
|
+
settle();
|
|
48
|
+
});
|
|
49
|
+
process.on("SIGINT", () => void shutdown());
|
|
50
|
+
process.on("SIGTERM", () => void shutdown());
|
|
51
|
+
}
|
|
52
|
+
main().catch((error) => {
|
|
53
|
+
log(error instanceof Error ? (error.stack ?? error.message) : String(error));
|
|
54
|
+
process.exit(1);
|
|
55
|
+
});
|
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
|
+
}
|