@statelyai/mcp 0.1.0 → 0.1.2

package/dist/index.mjs

@@ -1,472 +0,0 @@
-#!/usr/bin/env node
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { z } from "zod";
-
-//#region src/server.ts
-const readOnlyAnnotations = {
-	readOnlyHint: true,
-	destructiveHint: false,
-	idempotentHint: true,
-	openWorldHint: false
-};
-const apiFormats = [
-	"d2",
-	"scxml",
-	"xgraph",
-	"xstate"
-];
-const validationFormats = [
-	...apiFormats,
-	"json",
-	"yaml",
-	"mermaid"
-];
-const apiFormatSchema = z.enum(apiFormats);
-const validationFormatSchema = z.enum(validationFormats);
-const machineSchema = z.union([z.record(z.string(), z.unknown()), z.string()]);
-const sourceSchema = z.object({
-	format: validationFormatSchema.optional(),
-	content: machineSchema
-});
-const patchSchema = z.object({
-	op: z.string(),
-	path: z.string(),
-	value: z.unknown().optional()
-});
-function generateTestCode(machineCode, paths) {
-	return [
-		[
-			"// Generated by generate_test_code (Stately MCP).",
-			"// Guards and actions are stubbed; assertions use state paths.",
-			"import { createActor } from 'xstate';",
-			"import { describe, expect, it } from 'vitest';",
-			"",
-			machineCode.trim(),
-			""
-		].join("\n"),
-		"describe('generated paths', () => {",
-		paths.map((path) => {
-			const events = path.steps.filter((step) => step.eventType !== null && step.eventType !== "" && !step.eventType.startsWith("xstate.")).map((step) => `    actor.send({ type: ${JSON.stringify(step.eventType)} });`);
-			return [
-				`  it(${JSON.stringify(path.name)}, () => {`,
-				"    const actor = createActor(machine).start();",
-				...events,
-				`    expect(actor.getSnapshot().matches(${JSON.stringify(path.finalStatePath)})).toBe(true);`,
-				"  });"
-			].join("\n");
-		}).join("\n\n"),
-		"});",
-		""
-	].join("\n");
-}
-function toolText$1(body) {
-	return JSON.stringify(body, null, 2);
-}
-function toolResult(body) {
-	return {
-		structuredContent: body,
-		content: [{
-			type: "text",
-			text: toolText$1(body)
-		}]
-	};
-}
-function toolError(body) {
-	return {
-		isError: true,
-		...toolResult(body)
-	};
-}
-function normalizeApiBaseUrl(apiBaseUrl) {
-	return new URL(String(apiBaseUrl ?? "https://editor.stately.ai/api")).toString().replace(/\/$/, "");
-}
-function normalizeSource(input) {
-	const content = input.source?.content ?? input.machine;
-	if (content === void 0) throw new Error("Expected machine or source.content.");
-	return {
-		format: input.source?.format ?? input.format ?? (typeof content === "string" ? "xstate" : "json"),
-		content
-	};
-}
-function toConversionSource(source) {
-	if (!apiFormats.includes(source.format)) {
-		if (source.format === "json" && typeof source.content === "object") return {
-			format: "xstate",
-			content: `createMachine(${JSON.stringify(source.content, null, 2)})`
-		};
-		if (source.format === "json" && typeof source.content === "string") return {
-			format: "xstate",
-			content: source.content
-		};
-		throw new Error(`Format ${source.format} is only supported by validate_machine.`);
-	}
-	return source;
-}
-async function callApi(options, pathname, body) {
-	const configuredHeaders = typeof options.apiHeaders === "function" ? await options.apiHeaders() : options.apiHeaders;
-	const headers = new Headers(configuredHeaders);
-	const authMode = options.authMode ?? "auto";
-	if (authMode !== "none" && !headers.has("authorization")) {
-		const credential = await options.credentialProvider?.();
-		const token = credential?.type === "oauth" ? credential.accessToken : credential?.token;
-		if (token) headers.set("authorization", `Bearer ${token}`);
-		else if (authMode === "bearer") throw new Error("No Stately credential configured. Run `statelyai login` or set STATELY_ACCESS_TOKEN.");
-	}
-	const response = await fetch(`${normalizeApiBaseUrl(options.apiBaseUrl)}${pathname}`, {
-		method: "POST",
-		headers: {
-			"content-type": "application/json",
-			...Object.fromEntries(headers.entries())
-		},
-		body: JSON.stringify(body)
-	});
-	const result = await response.json().catch(() => ({ error: `Invalid JSON response from ${pathname}.` }));
-	if (!response.ok) throw new Error(typeof result.error === "string" ? result.error : `${pathname} failed with HTTP ${response.status}`);
-	return result;
-}
-function registerTool(server, name, config, handler) {
-	server.registerTool(name, {
-		...config,
-		annotations: readOnlyAnnotations
-	}, async (args) => {
-		try {
-			return toolResult(await handler(args));
-		} catch (error) {
-			return toolError({ error: error instanceof Error ? error.message : String(error) });
-		}
-	});
-}
-function registerStatelyMcpTools(server, options = {}) {
-	registerTool(server, "validate_machine", {
-		title: "Validate machine",
-		description: "Validate an XState machine config or source string through the Stately API.",
-		inputSchema: {
-			machine: machineSchema.optional(),
-			format: validationFormatSchema.optional(),
-			source: sourceSchema.optional()
-		}
-	}, (input) => callApi(options, "/v1/validate", { source: normalizeSource(input) }));
-	registerTool(server, "convert_machine", {
-		title: "Convert machine",
-		description: "Convert between XState, SCXML, XGraph, and D2 through the Stately API.",
-		inputSchema: {
-			machine: machineSchema.optional(),
-			format: apiFormatSchema.optional(),
-			source: sourceSchema.optional(),
-			to: apiFormatSchema
-		}
-	}, (input) => callApi(options, "/v1/convert", {
-		source: toConversionSource(normalizeSource(input)),
-		target: { format: input.to }
-	}));
-	registerTool(server, "diff_machines", {
-		title: "Diff machines",
-		description: "Compute a semantic diff between two machine documents through the Stately API.",
-		inputSchema: {
-			base: sourceSchema,
-			compare: sourceSchema,
-			includePatches: z.boolean().optional()
-		}
-	}, (input) => callApi(options, "/v1/diff", {
-		base: toConversionSource(normalizeSource({ source: input.base })),
-		compare: toConversionSource(normalizeSource({ source: input.compare })),
-		includePatches: input.includePatches
-	}));
-	registerTool(server, "apply_machine_patches", {
-		title: "Apply machine patches",
-		description: "Apply semantic machine patches through the Stately API.",
-		inputSchema: {
-			machine: machineSchema.optional(),
-			format: apiFormatSchema.optional(),
-			source: sourceSchema.optional(),
-			patches: z.array(patchSchema),
-			to: apiFormatSchema.optional()
-		}
-	}, (input) => callApi(options, "/v1/apply-patches", {
-		source: toConversionSource(normalizeSource(input)),
-		patches: input.patches,
-		target: input.to ? { format: input.to } : void 0
-	}));
-	registerTool(server, "generate_graph_paths", {
-		title: "Generate graph paths",
-		description: "Generate shortest or simple paths through the Stately API.",
-		inputSchema: {
-			machine: machineSchema.optional(),
-			format: apiFormatSchema.optional(),
-			source: sourceSchema.optional(),
-			graph: z.record(z.string(), z.unknown()).optional(),
-			kind: z.enum(["shortest", "simple"]).default("shortest"),
-			max: z.number().int().positive().optional()
-		}
-	}, async (input) => {
-		return callApi(options, "/v1/graph-paths", {
-			graph: input.graph ?? (await callApi(options, "/v1/convert", {
-				source: toConversionSource(normalizeSource(input)),
-				target: { format: "xgraph" }
-			})).content,
-			options: {
-				strategy: input.kind,
-				limit: Math.min(input.max ?? 5, options.anonymousGraphPathLimit ?? 5)
-			}
-		});
-	});
-	registerTool(server, "simulate_machine", {
-		title: "Simulate machine",
-		description: "Simulate an XState machine through a sequence of events; returns per-step state, context, and executed actions. Deterministic; guards are stubbed.",
-		inputSchema: {
-			machine: machineSchema.optional(),
-			format: apiFormatSchema.optional(),
-			source: sourceSchema.optional(),
-			events: z.array(z.object({ type: z.string() }).passthrough()).min(1).max(100)
-		}
-	}, (input) => callApi(options, "/v1/simulate", {
-		source: toConversionSource(normalizeSource(input)),
-		events: input.events
-	}));
-	registerTool(server, "visualize_machine", {
-		title: "Visualize machine",
-		description: "Render the machine as an SVG diagram (returns svg string + dimensions).",
-		inputSchema: {
-			machine: machineSchema.optional(),
-			format: apiFormatSchema.optional(),
-			source: sourceSchema.optional(),
-			direction: z.enum(["right", "down"]).optional()
-		}
-	}, (input) => callApi(options, "/v1/visualize", {
-		source: toConversionSource(normalizeSource(input)),
-		options: input.direction ? { direction: input.direction } : void 0
-	}));
-	registerTool(server, "analyze_machine", {
-		title: "Analyze machine",
-		description: "Deep analysis of machine logic (merges deterministic graph checks with AI review); may require an API key — configure via server options; for purely deterministic checks use validate_machine.",
-		inputSchema: {
-			machine: machineSchema.optional(),
-			format: apiFormatSchema.optional(),
-			source: sourceSchema.optional(),
-			intent: z.string().optional()
-		}
-	}, (input) => callApi(options, "/v1/analyze", {
-		source: toConversionSource(normalizeSource(input)),
-		intent: input.intent
-	}));
-	registerTool(server, "generate_test_code", {
-		title: "Generate test code",
-		description: "Generate a runnable vitest test file from the machine, one test per generated path. Guards and actions are stubbed; assertions use state paths.",
-		inputSchema: {
-			machine: machineSchema.optional(),
-			format: apiFormatSchema.optional(),
-			source: sourceSchema.optional(),
-			kind: z.enum(["shortest", "simple"]).default("shortest"),
-			max: z.number().int().positive().optional()
-		}
-	}, async (input) => {
-		const source = toConversionSource(normalizeSource(input));
-		const graph = (await callApi(options, "/v1/convert", {
-			source,
-			target: { format: "xgraph" }
-		})).content;
-		const pathsResponse = await callApi(options, "/v1/graph-paths", {
-			graph,
-			options: {
-				strategy: input.kind,
-				limit: Math.min(input.max ?? 5, options.anonymousGraphPathLimit ?? 5)
-			}
-		});
-		return {
-			code: generateTestCode(String((await callApi(options, "/v1/convert", {
-				source,
-				target: { format: "xstate" }
-			})).content), pathsResponse.paths),
-			paths: pathsResponse.paths,
-			coverage: pathsResponse.coverage
-		};
-	});
-	registerTool(server, "extract_machines_from_code", {
-		title: "Extract machines from code",
-		description: "Parse XState source code into XGraph through the Stately API.",
-		inputSchema: { code: z.string().min(1) }
-	}, async (input) => {
-		return { machines: [{
-			format: "xgraph",
-			graph: (await callApi(options, "/v1/convert", {
-				source: {
-					format: "xstate",
-					content: input.code
-				},
-				target: { format: "xgraph" }
-			})).content
-		}] };
-	});
-	return server;
-}
-function createStatelyMcpServer(options = {}) {
-	const server = new McpServer({
-		name: "stately",
-		version: "0.1.0"
-	});
-	registerStatelyMcpTools(server, options);
-	return server;
-}
-
-//#endregion
-//#region src/index.ts
-async function loadNode() {
-	const [fs, os, path] = await Promise.all([
-		import("node:fs/promises"),
-		import("node:os"),
-		import("node:path")
-	]);
-	return {
-		fs,
-		os,
-		path
-	};
-}
-function workspaceFromArgv() {
-	const index = process.argv.indexOf("--workspace");
-	return index >= 0 ? process.argv[index + 1] : process.cwd();
-}
-function isCandidate(pathname) {
-	return /\.(?:[cm]?[jt]sx?|json|ya?ml|scxml|mmd|mermaid)$/i.test(pathname);
-}
-function formatForPath(pathname, text) {
-	if (/\.(?:mmd|mermaid)$/i.test(pathname)) return "mermaid";
-	if (/\.scxml$/i.test(pathname)) return "scxml";
-	if (/\.ya?ml$/i.test(pathname)) return "yaml";
-	if (/\.json$/i.test(pathname)) return "json";
-	if (/^\s*</.test(text)) return "scxml";
-	return "xstate";
-}
-async function walkWorkspace(root, glob) {
-	const { fs, path } = await loadNode();
-	const results = [];
-	async function walk(dir) {
-		const entries = await fs.readdir(dir, { withFileTypes: true });
-		for (const entry of entries) {
-			if (entry.name === "node_modules" || entry.name === ".git" || entry.name === "dist") continue;
-			const full = path.join(dir, entry.name);
-			if (entry.isDirectory()) await walk(full);
-			else if (isCandidate(full)) {
-				const relative = path.relative(root, full);
-				if (!glob || relative.includes(glob)) results.push(relative);
-			}
-		}
-	}
-	await walk(root);
-	return results;
-}
-async function readWorkspaceMachine(input) {
-	const { fs, path } = await loadNode();
-	const root = workspaceFromArgv();
-	const fullPath = path.resolve(root, input.path);
-	const relative = path.relative(root, fullPath);
-	if (relative.startsWith("..") || path.isAbsolute(relative)) throw new Error("Path must stay inside workspace.");
-	const sourceText = await fs.readFile(fullPath, "utf8");
-	return {
-		machine: sourceText,
-		format: formatForPath(fullPath, sourceText),
-		source: { path: relative },
-		...input.includeSourceText ? { sourceText } : {}
-	};
-}
-async function readStoredCliCredential() {
-	const { fs, os, path } = await loadNode();
-	const configDir = process.env.STATELYAI_CONFIG_DIR ? path.resolve(process.env.STATELYAI_CONFIG_DIR) : process.platform === "darwin" ? path.join(os.homedir(), "Library", "Application Support", "statelyai") : process.platform === "win32" ? path.join(process.env.APPDATA ?? path.join(os.homedir(), "AppData", "Roaming"), "statelyai") : path.join(process.env.XDG_CONFIG_HOME ?? path.join(os.homedir(), ".config"), "statelyai");
-	try {
-		const raw = await fs.readFile(path.join(configDir, "credentials.json"), "utf8");
-		const parsed = JSON.parse(raw);
-		if (typeof parsed.apiKey === "string" && parsed.apiKey) return {
-			type: "api_key",
-			token: parsed.apiKey
-		};
-		if (typeof parsed.credential === "object" && parsed.credential !== null && "type" in parsed.credential) {
-			const credential = parsed.credential;
-			if (credential.type === "api_key" && typeof credential.token === "string") return {
-				type: "api_key",
-				token: credential.token
-			};
-			if (credential.type === "oauth" && typeof credential.accessToken === "string") return {
-				type: "oauth",
-				accessToken: credential.accessToken,
-				...typeof credential.refreshToken === "string" ? { refreshToken: credential.refreshToken } : {},
-				...typeof credential.expiresAt === "number" ? { expiresAt: credential.expiresAt } : {}
-			};
-		}
-	} catch {
-		return;
-	}
-}
-async function getDefaultCredential() {
-	if (process.env.STATELY_ACCESS_TOKEN) return {
-		type: "oauth",
-		accessToken: process.env.STATELY_ACCESS_TOKEN
-	};
-	if (process.env.STATELY_API_KEY) return {
-		type: "api_key",
-		token: process.env.STATELY_API_KEY
-	};
-	return readStoredCliCredential();
-}
-function toolText(body) {
-	return JSON.stringify(body, null, 2);
-}
-function createStatelyMcpServer$1(options = {}) {
-	const server = new McpServer({
-		name: "stately",
-		version: "0.1.0"
-	});
-	if (options.includeWorkspaceTools !== false) {
-		server.registerTool("list_machines", {
-			title: "list_machines",
-			description: "List candidate machine sources in the workspace.",
-			inputSchema: { glob: z.string().optional() },
-			annotations: readOnlyAnnotations
-		}, async (request) => {
-			const machines = (await walkWorkspace(workspaceFromArgv(), request.glob)).map((pathname) => ({
-				source: { path: pathname },
-				format: "xstate"
-			}));
-			return {
-				structuredContent: { machines },
-				content: [{
-					type: "text",
-					text: toolText({ machines })
-				}]
-			};
-		});
-		server.registerTool("get_machine", {
-			title: "get_machine",
-			description: "Read a machine source from the workspace and return it.",
-			inputSchema: {
-				path: z.string(),
-				includeSourceText: z.boolean().optional()
-			},
-			annotations: readOnlyAnnotations
-		}, async (request) => {
-			const result = await readWorkspaceMachine(request);
-			return {
-				structuredContent: result,
-				content: [{
-					type: "text",
-					text: toolText(result)
-				}]
-			};
-		});
-	}
-	registerStatelyMcpTools(server, {
-		...options,
-		authMode: options.authMode ?? (process.env.STATELY_AUTH_MODE === "none" ? "none" : void 0),
-		credentialProvider: options.credentialProvider ?? getDefaultCredential
-	});
-	return server;
-}
-async function main() {
-	const server = createStatelyMcpServer$1();
-	const transport = new StdioServerTransport();
-	await server.connect(transport);
-}
-if (import.meta.url === `file://${process.argv[1]}`) main();
-
-//#endregion
-export { createStatelyMcpServer as createHostedStatelyMcpServer, createStatelyMcpServer$1 as createStatelyMcpServer, formatForPath, generateTestCode, getDefaultCredential, isCandidate, readOnlyAnnotations, readWorkspaceMachine, registerStatelyMcpTools, walkWorkspace, workspaceFromArgv };