@statelyai/mcp 0.3.1 → 0.4.0

package/dist/index.mjs

@@ -3,6 +3,472 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
 
+//#region ../api-contract/dist/errors.mjs
+/**
+* Error shape returned by every `/api/v1` machine operation (and by the shared
+* auth guard). Each operation registers its own error schema component in the
+* OpenAPI document, so this is a factory rather than a single shared instance.
+*/
+function createApiErrorResponseSchema() {
+	return z.object({
+		error: z.string(),
+		issues: z.array(z.unknown()).optional()
+	});
+}
+const apiErrorResponseSchema = createApiErrorResponseSchema();
+/**
+* Canonical error codes for the `/api/v1` resource operations. Machine
+* operations keep the flat `{ error: string }` shape above unchanged; the
+* nested envelope below applies to resource operations only.
+*/
+const resourceErrorCodeSchema = z.enum([
+	"bad_request",
+	"unauthenticated",
+	"forbidden",
+	"not_found",
+	"conflict",
+	"payload_too_large",
+	"rate_limited",
+	"capability_disabled",
+	"upstream_error",
+	"internal_error"
+]);
+/** Factory, matching `createApiErrorResponseSchema`, for per-route OpenAPI components. */
+function createResourceApiErrorResponseSchema() {
+	return z.object({ error: z.object({
+		code: resourceErrorCodeSchema,
+		message: z.string(),
+		issues: z.array(z.unknown()).optional(),
+		retryable: z.boolean().optional()
+	}) });
+}
+const resourceApiErrorResponseSchema = createResourceApiErrorResponseSchema();
+
+//#endregion
+//#region ../api-contract/dist/resources.mjs
+/**
+* Canonical schemas for persistent `/api/v1` resources plus the owned,
+* deterministic code-extraction operation.
+*
+* These models are canonical, not upstream-shaped: providers (e.g. the Stately
+* Registry adapter) are responsible for translating upstream envelopes,
+* identifier quirks and casing into these shapes. No `{ data }` envelope
+* appears anywhere; all timestamps are ISO strings.
+*/
+/**
+* XState major versions the editor targets (see
+* `packages/editor/src/formats/xstate.ts`).
+*/
+const xstateVersionSchema = z.union([z.literal(5), z.literal(6)]);
+const projectVisibilitySchema = z.enum([
+	"public",
+	"unlisted",
+	"private"
+]);
+const verifyResultSchema = z.object({
+	valid: z.literal(true),
+	tokenScope: z.enum(["user", "project"])
+});
+const projectSummarySchema = z.object({
+	projectId: z.string(),
+	projectVersionId: z.string(),
+	name: z.string(),
+	description: z.string().nullable(),
+	visibility: projectVisibilitySchema,
+	createdAt: z.string(),
+	updatedAt: z.string()
+});
+const projectSchema = projectSummarySchema.extend({
+	rootMachineId: z.string().nullable(),
+	machines: z.array(z.object({ machineId: z.string() }))
+});
+/**
+* `name` is optional: the Registry project envelope only returns machine ids.
+* Providers that can supply names cheaply should.
+*/
+const projectMachineSummarySchema = z.object({
+	machineId: z.string(),
+	name: z.string().optional()
+});
+const machineSchema$1 = z.object({
+	machineId: z.string(),
+	name: z.string(),
+	projectId: z.string().optional(),
+	projectVersionId: z.string(),
+	definition: z.unknown(),
+	createdAt: z.string().optional(),
+	updatedAt: z.string().optional()
+});
+const machineVersionSchema = z.object({
+	machineVersionId: z.string(),
+	machineId: z.string(),
+	versionNumber: z.number(),
+	name: z.string(),
+	definition: z.unknown(),
+	createdAt: z.string(),
+	updatedAt: z.string()
+});
+const extractedMachinesSchema = z.object({ machines: z.array(z.object({ config: z.record(z.string(), z.unknown()) })) });
+const projectsCreateRequestSchema = z.object({
+	name: z.string().min(1),
+	visibility: projectVisibilitySchema
+});
+const projectsUpdateRequestSchema = z.object({
+	name: z.string().min(1).optional(),
+	description: z.string().nullable().optional(),
+	visibility: projectVisibilitySchema.optional()
+}).refine((value) => value.name !== void 0 || value.description !== void 0 || value.visibility !== void 0, { message: "At least one of `name`, `description` or `visibility` is required." });
+const machinesCreateRequestSchema = z.object({
+	projectVersionId: z.string().min(1),
+	xstateVersion: xstateVersionSchema,
+	name: z.string().min(1).optional(),
+	definition: z.unknown().optional()
+});
+const machinesUpdateRequestSchema = z.object({
+	name: z.string().min(1).optional(),
+	definition: z.unknown().optional()
+}).refine((value) => value.name !== void 0 || value.definition !== void 0, { message: "At least one of `name` or `definition` is required." });
+const codeExtractMachinesRequestSchema = z.object({
+	code: z.string().min(1),
+	xstateVersion: xstateVersionSchema.optional()
+});
+const authVerifyResponseSchema = verifyResultSchema;
+const projectsListResponseSchema = z.array(projectSummarySchema);
+const projectsGetResponseSchema = projectSchema;
+const projectsCreateResponseSchema = projectSchema;
+const projectsUpdateResponseSchema = projectSchema;
+const projectsDeleteResponseSchema = z.object({ projectId: z.string() });
+const projectsListMachinesResponseSchema = z.array(projectMachineSummarySchema);
+const machinesCreateResponseSchema = machineSchema$1;
+const machinesGetResponseSchema = machineSchema$1;
+const machinesUpdateResponseSchema = machineSchema$1;
+const machinesGetVersionResponseSchema = machineVersionSchema;
+const codeExtractMachinesResponseSchema = extractedMachinesSchema;
+/**
+* Request/response schema pairs keyed by resource capability name. Kept here
+* rather than on the `Capability` metadata entries so that the capability
+* registry stays plain, serialisable data.
+*/
+const resourceOperationSchemas = {
+	"auth.verify": { response: authVerifyResponseSchema },
+	"projects.list": { response: projectsListResponseSchema },
+	"projects.create": {
+		request: projectsCreateRequestSchema,
+		response: projectsCreateResponseSchema
+	},
+	"projects.get": { response: projectsGetResponseSchema },
+	"projects.update": {
+		request: projectsUpdateRequestSchema,
+		response: projectsUpdateResponseSchema
+	},
+	"projects.delete": { response: projectsDeleteResponseSchema },
+	"projects.listMachines": { response: projectsListMachinesResponseSchema },
+	"machines.create": {
+		request: machinesCreateRequestSchema,
+		response: machinesCreateResponseSchema
+	},
+	"machines.get": { response: machinesGetResponseSchema },
+	"machines.getVersion": { response: machinesGetVersionResponseSchema },
+	"machines.update": {
+		request: machinesUpdateRequestSchema,
+		response: machinesUpdateResponseSchema
+	}
+};
+/** Provider-independent operations implemented by this repository. */
+const codeOperationSchemas = { "code.extractMachines": {
+	request: codeExtractMachinesRequestSchema,
+	response: codeExtractMachinesResponseSchema
+} };
+/** Every owned API operation with a canonical request/response contract. */
+const operationSchemas = {
+	...resourceOperationSchemas,
+	...codeOperationSchemas
+};
+
+//#endregion
+//#region src/resourceClient.ts
+/**
+* `ResourceClient` port: the only way MCP resource tools reach hosted Stately
+* projects and machines.
+*
+* Implementations speak canonical `@statelyai/api-contract` values and throw
+* {@link ResourceClientError} with a canonical `{ code, message }`. Two
+* implementations exist:
+*
+* - HTTP-backed ({@link createHttpResourceClient}), used by Studio's MCP proxy,
+*   which already forwards `apiBaseUrl` and an `Authorization` header.
+* - in-process, provided by the editor MCP route directly over its resource
+*   service (see `packages/editor/src/lib/resources/mcpResourceClient.ts`).
+*
+* Resource tools must never import Registry code or re-implement the contract.
+*/
+/** Canonical error surfaced by every `ResourceClient` implementation. */
+var ResourceClientError = class extends Error {
+	code;
+	issues;
+	retryable;
+	constructor(code, message, options = {}) {
+		super(message, options.cause ? { cause: options.cause } : void 0);
+		this.name = "ResourceClientError";
+		this.code = code;
+		this.issues = options.issues;
+		this.retryable = options.retryable;
+	}
+};
+function isResourceClientError(value) {
+	return value instanceof ResourceClientError;
+}
+const statusToResourceErrorCode = {
+	400: "bad_request",
+	401: "unauthenticated",
+	403: "forbidden",
+	404: "not_found",
+	409: "conflict",
+	413: "payload_too_large",
+	429: "rate_limited",
+	500: "internal_error",
+	501: "capability_disabled",
+	502: "upstream_error"
+};
+function resourceErrorCodeForStatus(status) {
+	return statusToResourceErrorCode[status] ?? (status >= 500 ? "upstream_error" : "bad_request");
+}
+/**
+* Base URL of the owned v1 resource routes, derived from the same
+* `apiBaseUrl` option the machine tools use.
+*
+* `apiBaseUrl` conventionally already ends in `/api` (the default is
+* `https://editor.stately.ai/api`, and Studio's proxy passes that), so the
+* rules are explicit and never double a segment:
+*
+* - ends in `/v1` -> used as-is
+* - ends in `/api` -> `+ /v1`
+* - anything else (e.g. a bare origin) -> `+ /api/v1`
+*/
+function resourceApiV1BaseUrl(apiBaseUrl) {
+	const normalized = new URL(String(apiBaseUrl ?? "https://editor.stately.ai/api")).toString().replace(/\/+$/, "");
+	if (/\/v1$/.test(normalized)) return normalized;
+	if (/\/api$/.test(normalized)) return `${normalized}/v1`;
+	return `${normalized}/api/v1`;
+}
+async function resolveHeaders(options) {
+	const headers = new Headers(options.headers);
+	if (options.getHeaders) new Headers(await options.getHeaders()).forEach((value, key) => {
+		headers.set(key, value);
+	});
+	headers.set("accept", "application/json");
+	return headers;
+}
+function parseErrorBody(body, status) {
+	const nested = typeof body === "object" && body !== null ? body.error : void 0;
+	if (typeof nested === "object" && nested !== null) {
+		const envelope = nested;
+		const code = resourceErrorCodeSchema.safeParse(envelope.code);
+		return new ResourceClientError(code.success ? code.data : resourceErrorCodeForStatus(status), typeof envelope.message === "string" ? envelope.message : `Request failed with HTTP ${status}.`, {
+			issues: Array.isArray(envelope.issues) ? envelope.issues : void 0,
+			retryable: typeof envelope.retryable === "boolean" ? envelope.retryable : void 0
+		});
+	}
+	return new ResourceClientError(resourceErrorCodeForStatus(status), typeof nested === "string" ? nested : `Request failed with HTTP ${status}.`);
+}
+/**
+* HTTP-backed `ResourceClient` over the owned routes:
+* `GET /api/v1/projects`, `/api/v1/projects/:projectId`,
+* `/api/v1/projects/:projectId/machines` and `/api/v1/machines/:machineId`.
+*/
+function createHttpResourceClient(options = {}) {
+	const baseUrl = resourceApiV1BaseUrl(options.apiBaseUrl);
+	const doFetch = options.fetch ?? fetch;
+	async function get(pathname, schema, call) {
+		const headers = await resolveHeaders(options);
+		let response;
+		try {
+			response = await doFetch(`${baseUrl}${pathname}`, {
+				method: "GET",
+				headers,
+				signal: call?.signal
+			});
+		} catch (error) {
+			if (error instanceof Error && error.name === "AbortError") throw error;
+			throw new ResourceClientError("upstream_error", error instanceof Error ? error.message : `GET ${pathname} failed.`, {
+				retryable: true,
+				cause: error
+			});
+		}
+		const body = await response.json().catch(() => void 0);
+		if (!response.ok) throw parseErrorBody(body, response.status);
+		const parsed = schema.safeParse(body);
+		if (!parsed.success) throw new ResourceClientError("upstream_error", `Unexpected response shape for GET ${pathname}.`);
+		return parsed.data;
+	}
+	return {
+		listProjects: (call) => get("/projects", projectsListResponseSchema, call),
+		getProject: (projectId, call) => get(`/projects/${encodeURIComponent(projectId)}`, projectsGetResponseSchema, call),
+		listProjectMachines: (projectId, call) => get(`/projects/${encodeURIComponent(projectId)}/machines`, projectsListMachinesResponseSchema, call),
+		getMachine: (machineId, call) => get(`/machines/${encodeURIComponent(machineId)}`, machinesGetResponseSchema, call)
+	};
+}
+
+//#endregion
+//#region src/toolCallObserver.ts
+const observerStates = /* @__PURE__ */ new WeakMap();
+const errorCodes = /* @__PURE__ */ new WeakMap();
+function notifyToolCall(observer, event) {
+	try {
+		Promise.resolve(observer(event)).catch(() => void 0);
+	} catch {}
+}
+function isErrorResult(result) {
+	return typeof result === "object" && result !== null && "isError" in result && result.isError === true;
+}
+function getRequestMethod(requestSchema) {
+	if (typeof requestSchema !== "object" || requestSchema === null) return;
+	const shape = requestSchema.shape;
+	if (typeof shape !== "object" || shape === null) return void 0;
+	const method = shape.method;
+	if (typeof method !== "object" || method === null) return void 0;
+	return method.value;
+}
+function installToolCallObserver(server, state) {
+	try {
+		server.server.assertCanSetRequestHandler("tools/call");
+	} catch {
+		throw new Error("onToolCall must be configured before any tools are registered on this McpServer.");
+	}
+	const setRequestHandler = server.server.setRequestHandler.bind(server.server);
+	server.server.setRequestHandler = ((requestSchema, handler) => {
+		if (getRequestMethod(requestSchema) !== "tools/call") return setRequestHandler(requestSchema, handler);
+		return setRequestHandler(requestSchema, async (request, extra) => {
+			const observer = state.observers.get(request.params.name);
+			if (!observer) return handler(request, extra);
+			const startedAt = Date.now();
+			try {
+				const result = await handler(request, extra);
+				const failed = isErrorResult(result);
+				notifyToolCall(observer, {
+					toolName: request.params.name,
+					outcome: failed ? "error" : "success",
+					durationMs: Date.now() - startedAt,
+					...failed ? { errorCode: errorCodes.get(result) ?? "tool_error" } : {}
+				});
+				return result;
+			} catch (error) {
+				notifyToolCall(observer, {
+					toolName: request.params.name,
+					outcome: "error",
+					durationMs: Date.now() - startedAt,
+					errorCode: "tool_error"
+				});
+				throw error;
+			}
+		});
+	});
+}
+function registerToolCallObserver(server, toolName, observer) {
+	if (!observer) return;
+	let state = observerStates.get(server);
+	if (!state) {
+		state = { observers: /* @__PURE__ */ new Map() };
+		installToolCallObserver(server, state);
+		observerStates.set(server, state);
+	}
+	state.observers.set(toolName, observer);
+}
+function markToolCallError(result, errorCode) {
+	errorCodes.set(result, errorCode);
+	return result;
+}
+
+//#endregion
+//#region src/resourceTools.ts
+/** Read-only, non-destructive; hosted resources are an open world. */
+const resourceReadOnlyAnnotations = {
+	readOnlyHint: true,
+	destructiveHint: false,
+	idempotentHint: true,
+	openWorldHint: true
+};
+const projectIdSchema = z.string().min(1).describe("Stately project id (`projectId`, never a project version id).");
+const machineIdSchema = z.string().min(1).describe("Stately machine id (`machineId`).");
+const projectsOutputSchema = z.object({ projects: projectsListResponseSchema });
+const projectOutputSchema = z.object({ project: projectsGetResponseSchema });
+const projectMachinesOutputSchema = z.object({ machines: projectsListMachinesResponseSchema });
+const machineOutputSchema = z.object({ machine: machinesGetResponseSchema });
+function toolText$2(body) {
+	return JSON.stringify(body, null, 2);
+}
+function resourceToolResult(body) {
+	return {
+		structuredContent: body,
+		content: [{
+			type: "text",
+			text: toolText$2(body)
+		}]
+	};
+}
+function resourceToolError(error) {
+	return {
+		isError: true,
+		content: [{
+			type: "text",
+			text: toolText$2({ error: {
+				code: error.code,
+				message: error.message,
+				...error.issues ? { issues: error.issues } : {},
+				...error.retryable === void 0 ? {} : { retryable: error.retryable }
+			} })
+		}]
+	};
+}
+function toResourceClientError(error) {
+	if (isResourceClientError(error)) return error;
+	return new ResourceClientError("internal_error", error instanceof Error ? error.message : String(error), { cause: error });
+}
+function registerResourceTool(server, name, config, resolveClient, handler, options) {
+	registerToolCallObserver(server, name, options.onToolCall);
+	server.registerTool(name, {
+		...config,
+		annotations: resourceReadOnlyAnnotations
+	}, async (args) => {
+		try {
+			const client = await resolveClient();
+			if (!client) throw new ResourceClientError("capability_disabled", "Hosted Stately resources are not available on this deployment.");
+			return resourceToolResult(await handler(client, args));
+		} catch (error) {
+			const resourceError = toResourceClientError(error);
+			return markToolCallError(resourceToolError(resourceError), resourceError.code);
+		}
+	});
+}
+function registerStatelyResourceTools(server, resolveClient, options = {}) {
+	registerResourceTool(server, "list_stately_projects", {
+		title: "List Stately projects",
+		description: "List the hosted Stately projects the caller can access. Hosted resources only; use list_machines for workspace files.",
+		inputSchema: {},
+		outputSchema: projectsOutputSchema
+	}, resolveClient, async (client) => ({ projects: await client.listProjects() }), options);
+	registerResourceTool(server, "get_stately_project", {
+		title: "Get Stately project",
+		description: "Read one hosted Stately project, including its current project version id and machine ids.",
+		inputSchema: { projectId: projectIdSchema },
+		outputSchema: projectOutputSchema
+	}, resolveClient, async (client, args) => ({ project: await client.getProject(args.projectId) }), options);
+	registerResourceTool(server, "list_stately_project_machines", {
+		title: "List Stately project machines",
+		description: "List the machines belonging to a hosted Stately project.",
+		inputSchema: { projectId: projectIdSchema },
+		outputSchema: projectMachinesOutputSchema
+	}, resolveClient, async (client, args) => ({ machines: await client.listProjectMachines(args.projectId) }), options);
+	registerResourceTool(server, "get_stately_machine", {
+		title: "Get Stately machine",
+		description: "Read one hosted Stately machine, including its definition.",
+		inputSchema: { machineId: machineIdSchema },
+		outputSchema: machineOutputSchema
+	}, resolveClient, async (client, args) => ({ machine: await client.getMachine(args.machineId) }), options);
+	return server;
+}
+
+//#endregion
 //#region src/server.ts
 const readOnlyAnnotations = {
 	readOnlyHint: true,
@@ -178,7 +644,8 @@ function toConversionSource(source) {
 	}
 	return source;
 }
-async function callApi(options, pathname, body) {
+const missingCredentialMessage = "No Stately credential configured. Run `statelyai login` or set STATELY_ACCESS_TOKEN.";
+async function resolveApiHeaders(options, onMissingCredential) {
 	const configuredHeaders = typeof options.apiHeaders === "function" ? await options.apiHeaders() : options.apiHeaders;
 	const headers = new Headers(configuredHeaders);
 	const authMode = options.authMode ?? "auto";
@@ -186,8 +653,28 @@ async function callApi(options, pathname, body) {
 		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.");
+		else if (authMode === "bearer" || onMissingCredential === "throw") throw new Error(missingCredentialMessage);
 	}
+	return headers;
+}
+/**
+* Resource tools are always registered so tool listing keeps working; the
+* client is resolved per call. Missing credentials surface as a canonical
+* `unauthenticated` tool error rather than a crash.
+*/
+function createResourceClientResolver(options) {
+	return async () => {
+		if (options.resourceClient) return options.resourceClient;
+		const headers = await resolveApiHeaders(options, "allow");
+		if ((options.authMode ?? "auto") !== "none" && !headers.has("authorization")) throw new ResourceClientError("unauthenticated", `Hosted Stately resources require authentication. ${missingCredentialMessage}`);
+		return createHttpResourceClient({
+			apiBaseUrl: options.apiBaseUrl,
+			headers
+		});
+	};
+}
+async function callApi(options, pathname, body) {
+	const headers = await resolveApiHeaders(options, "allow");
 	const response = await fetch(`${normalizeApiBaseUrl(options.apiBaseUrl)}${pathname}`, {
 		method: "POST",
 		headers: {
@@ -200,7 +687,8 @@ async function callApi(options, pathname, body) {
 	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, formatResult = toolResult) {
+function registerTool(server, options, name, config, handler, formatResult = toolResult) {
+	registerToolCallObserver(server, name, options.onToolCall);
 	server.registerTool(name, {
 		...config,
 		annotations: readOnlyAnnotations
@@ -208,12 +696,12 @@ function registerTool(server, name, config, handler, formatResult = toolResult)
 		try {
 			return formatResult(await handler(args));
 		} catch (error) {
-			return toolError({ error: error instanceof Error ? error.message : String(error) });
+			return markToolCallError(toolError({ error: error instanceof Error ? error.message : String(error) }), "internal_error");
 		}
 	});
 }
 function registerStatelyMcpTools(server, options = {}) {
-	registerTool(server, "create_state_machine", {
+	registerTool(server, options, "create_state_machine", {
 		title: "Create state machine",
 		description: "Create a new XState v5 state machine from the user's description. The calling model must author complete XState v5 code and pass it as xstateCode. Return the XState source and, by default, directly viewable PNG diagrams. Prefer visualization because it makes behavior easier to verify; disable it only when the user explicitly wants code only, the client cannot display images, or a diagram adds no useful information.",
 		inputSchema: {
@@ -244,7 +732,7 @@ function registerStatelyMcpTools(server, options = {}) {
 			})
 		};
 	}, createMachineToolResult);
-	registerTool(server, "validate_machine", {
+	registerTool(server, options, "validate_machine", {
 		title: "Validate machine",
 		description: "Validate an XState machine config or source string through the Stately API.",
 		inputSchema: {
@@ -253,7 +741,7 @@ function registerStatelyMcpTools(server, options = {}) {
 			source: sourceSchema.optional()
 		}
 	}, (input) => callApi(options, "/v1/validate", { source: normalizeSource(input) }));
-	registerTool(server, "convert_machine", {
+	registerTool(server, options, "convert_machine", {
 		title: "Convert machine",
 		description: "Convert between XState, SCXML, XGraph, and D2 through the Stately API.",
 		inputSchema: {
@@ -266,7 +754,7 @@ function registerStatelyMcpTools(server, options = {}) {
 		source: toConversionSource(normalizeSource(input)),
 		target: { format: input.to }
 	}));
-	registerTool(server, "diff_machines", {
+	registerTool(server, options, "diff_machines", {
 		title: "Diff machines",
 		description: "Compute a semantic diff between two machine documents through the Stately API.",
 		inputSchema: {
@@ -279,7 +767,7 @@ function registerStatelyMcpTools(server, options = {}) {
 		compare: toConversionSource(normalizeSource({ source: input.compare })),
 		includePatches: input.includePatches
 	}));
-	registerTool(server, "apply_machine_patches", {
+	registerTool(server, options, "apply_machine_patches", {
 		title: "Apply machine patches",
 		description: "Apply semantic machine patches through the Stately API.",
 		inputSchema: {
@@ -294,7 +782,7 @@ function registerStatelyMcpTools(server, options = {}) {
 		patches: input.patches,
 		target: input.to ? { format: input.to } : void 0
 	}));
-	registerTool(server, "generate_graph_paths", {
+	registerTool(server, options, "generate_graph_paths", {
 		title: "Generate graph paths",
 		description: "Generate shortest or simple paths through the Stately API.",
 		inputSchema: {
@@ -317,7 +805,7 @@ function registerStatelyMcpTools(server, options = {}) {
 			}
 		});
 	});
-	registerTool(server, "simulate_machine", {
+	registerTool(server, options, "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: {
@@ -330,7 +818,7 @@ function registerStatelyMcpTools(server, options = {}) {
 		source: toConversionSource(normalizeSource(input)),
 		events: input.events
 	}));
-	registerTool(server, "visualize_machine", {
+	registerTool(server, options, "visualize_machine", {
 		title: "Visualize machine",
 		description: "Render machine hierarchy levels as directly viewable PNG images. Optionally select parent node ids.",
 		inputSchema: {
@@ -350,7 +838,16 @@ function registerStatelyMcpTools(server, options = {}) {
 			}
 		}).then((visualizations) => ({ visualizations }));
 	}, visualizeToolResult);
-	registerTool(server, "analyze_machine", {
+	registerTool(server, options, "extract_machines_from_code", {
+		title: "Extract machines from code",
+		description: "Deterministically extract canonical XState machine configs from JavaScript or TypeScript source. XState 5/6 syntax is inferred unless explicitly provided.",
+		inputSchema: {
+			code: z.string().min(1),
+			xstateVersion: xstateVersionSchema.optional().describe("Optional XState major-version override. Omit to infer from source syntax.")
+		},
+		outputSchema: codeExtractMachinesResponseSchema
+	}, (input) => callApi(options, "/v1/code/extract-machines", input));
+	registerTool(server, options, "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: {
@@ -363,7 +860,7 @@ function registerStatelyMcpTools(server, options = {}) {
 		source: toConversionSource(normalizeSource(input)),
 		intent: input.intent
 	}));
-	registerTool(server, "generate_test_code", {
+	registerTool(server, options, "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: {
@@ -395,22 +892,7 @@ function registerStatelyMcpTools(server, options = {}) {
 			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
-		}] };
-	});
+	if (options.includeResourceTools !== false) registerStatelyResourceTools(server, createResourceClientResolver(options), { onToolCall: options.onToolCall });
 	return server;
 }
 function createStatelyMcpServer(options = {}) {
@@ -530,6 +1012,7 @@ function createStatelyMcpServer$1(options = {}) {
 		version: "0.1.0"
 	});
 	if (options.includeWorkspaceTools !== false) {
+		registerToolCallObserver(server, "list_machines", options.onToolCall);
 		server.registerTool("list_machines", {
 			title: "list_machines",
 			description: "List candidate machine sources in the workspace.",
@@ -548,6 +1031,7 @@ function createStatelyMcpServer$1(options = {}) {
 				}]
 			};
 		});
+		registerToolCallObserver(server, "get_machine", options.onToolCall);
 		server.registerTool("get_machine", {
 			title: "get_machine",
 			description: "Read a machine source from the workspace and return it.",
@@ -582,4 +1066,4 @@ async function main() {
 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 };
+export { ResourceClientError, createStatelyMcpServer as createHostedStatelyMcpServer, createHttpResourceClient, createStatelyMcpServer$1 as createStatelyMcpServer, formatForPath, generateTestCode, getDefaultCredential, isCandidate, isResourceClientError, readOnlyAnnotations, readWorkspaceMachine, registerStatelyMcpTools, registerStatelyResourceTools, resourceApiV1BaseUrl, resourceReadOnlyAnnotations, walkWorkspace, workspaceFromArgv };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@statelyai/mcp",
-  "version": "0.3.1",
-  "license": "UNLICENSED",
+  "version": "0.4.0",
+  "license": "MIT",
   "bin": {
     "stately-mcp": "dist/index.mjs"
   },
@@ -26,10 +26,11 @@
   "devDependencies": {
     "@types/node": "25.2.1",
     "tsdown": "0.21.0-beta.2",
-    "vitest": "^3.2.4"
+    "vitest": "^3.2.4",
+    "@statelyai/api-contract": "0.0.1"
   },
   "scripts": {
-    "build": "tsdown",
+    "build": "pnpm --filter @statelyai/api-contract run build && tsdown",
     "test": "vitest run",
     "test:watch": "vitest",
     "verify:package": "node scripts/verify-package.mjs"