@statelyai/mcp 0.4.0 → 0.4.1

package/README.md

@@ -83,11 +83,11 @@ Mermaid.
 <!-- create_state_machine registration from src/server.ts and convert/visualize response contracts -->
 
 Creates a new XState v5 machine from a natural-language request. The connected
-agent authors the XState source, then Stately normalizes it and returns the
-source. Visualization defaults on and returns native PNG image blocks because a
-diagram usually makes generated behavior easier to verify. Set `visualization`
-to `false` only for code-only requests, clients that cannot display images, or
-machines where a diagram adds no useful information.
+agent authors the XState source, then Stately validates and returns that source
+without rewriting it. Visualization defaults on and returns native PNG image
+blocks because a diagram usually makes generated behavior easier to verify. Set
+`visualization` to `false` only for code-only requests, clients that cannot
+display images, or machines where a diagram adds no useful information.
 
 <details>
 <summary>Summary: create and visualize a machine</summary>
@@ -98,7 +98,7 @@ Make a state machine representing an order checkout flow.
 
 The agent calls Stately with complete XState v5 source. Omit `visualization` to
 render PNG diagrams, customize it with `direction` or `parentNodeIds`, or set it
-to `false` to return only the normalized XState source.
+to `false` to return only the validated, authored XState source.
 
 </details>
 
@@ -455,12 +455,12 @@ These tools read hosted Stately projects and machines through the server-owned
 `/api/v1` resource contract. They are separate from the workspace tools
 (`list_machines`, `get_machine`), which read local files.
 
-| Tool                            | Reads                                                                  |
-| ------------------------------- | ---------------------------------------------------------------------- |
-| `list_stately_projects`         | The hosted projects the caller can access.                             |
-| `get_stately_project`           | One project, with its current project version id and machine ids.      |
-| `list_stately_project_machines` | The machines in a project.                                             |
-| `get_stately_machine`           | One machine, with its definition.                                      |
+| Tool                            | Reads                                                             |
+| ------------------------------- | ----------------------------------------------------------------- |
+| `list_stately_projects`         | The hosted projects the caller can access.                        |
+| `get_stately_project`           | One project, with its current project version id and machine ids. |
+| `list_stately_project_machines` | The machines in a project.                                        |
+| `get_stately_machine`           | One machine, with its definition.                                 |
 
 Inputs take a `projectId` or `machineId`, never a project version id.
 

package/dist/index.cjs

@@ -516,6 +516,10 @@ const xstateMachineResultSchema = zod.z.object({
 	content: zod.z.string(),
 	warnings: zod.z.array(zod.z.string())
 });
+const xstateConversionCheckSchema = zod.z.object({
+	format: zod.z.literal("xgraph"),
+	warnings: zod.z.array(zod.z.string())
+});
 const visualizationMetadataSchema = zod.z.object({
 	parentNodeId: zod.z.string(),
 	parentNodeLabel: zod.z.string(),
@@ -711,13 +715,18 @@ function registerStatelyMcpTools(server, options = {}) {
 		},
 		outputSchema: createMachineOutputSchema
 	}, async (input) => {
-		const machine = xstateMachineResultSchema.parse(await callApi(options, "/v1/convert", {
+		const conversion = xstateConversionCheckSchema.parse(await callApi(options, "/v1/convert", {
 			source: {
 				format: "xstate",
 				content: input.xstateCode
 			},
-			target: { format: "xstate" }
+			target: { format: "xgraph" }
 		}));
+		const machine = {
+			format: "xstate",
+			content: input.xstateCode,
+			warnings: conversion.warnings
+		};
 		return {
 			machine,
 			visualizations: input.visualization === false ? [] : await callApi(options, "/v1/visualize", {

package/dist/index.d.cts

@@ -145,7 +145,7 @@ type StatelyMcpServerOptions = {
   apiBaseUrl?: string | URL;
   apiHeaders?: HeadersInit | (() => HeadersInit | Promise<HeadersInit>);
   credentialProvider?: () => StatelyCredential | undefined | Promise<StatelyCredential | undefined>;
-  authMode?: 'auto' | 'none' | 'bearer';
+  authMode?: "auto" | "none" | "bearer";
   anonymousGraphPathLimit?: number;
   /**
    * Port used by the hosted resource tools (`list_stately_projects` etc.).
@@ -162,10 +162,10 @@ type StatelyMcpServerOptions = {
   onToolCall?: StatelyMcpToolCallObserver;
 };
 type StatelyCredential = {
-  type: 'api_key';
+  type: "api_key";
   token: string;
 } | {
-  type: 'oauth';
+  type: "oauth";
   accessToken: string;
   refreshToken?: string;
   expiresAt?: number;

package/dist/index.d.mts

@@ -145,7 +145,7 @@ type StatelyMcpServerOptions = {
   apiBaseUrl?: string | URL;
   apiHeaders?: HeadersInit | (() => HeadersInit | Promise<HeadersInit>);
   credentialProvider?: () => StatelyCredential | undefined | Promise<StatelyCredential | undefined>;
-  authMode?: 'auto' | 'none' | 'bearer';
+  authMode?: "auto" | "none" | "bearer";
   anonymousGraphPathLimit?: number;
   /**
    * Port used by the hosted resource tools (`list_stately_projects` etc.).
@@ -162,10 +162,10 @@ type StatelyMcpServerOptions = {
   onToolCall?: StatelyMcpToolCallObserver;
 };
 type StatelyCredential = {
-  type: 'api_key';
+  type: "api_key";
   token: string;
 } | {
-  type: 'oauth';
+  type: "oauth";
   accessToken: string;
   refreshToken?: string;
   expiresAt?: number;

package/dist/index.mjs

@@ -515,6 +515,10 @@ const xstateMachineResultSchema = z.object({
 	content: z.string(),
 	warnings: z.array(z.string())
 });
+const xstateConversionCheckSchema = z.object({
+	format: z.literal("xgraph"),
+	warnings: z.array(z.string())
+});
 const visualizationMetadataSchema = z.object({
 	parentNodeId: z.string(),
 	parentNodeLabel: z.string(),
@@ -710,13 +714,18 @@ function registerStatelyMcpTools(server, options = {}) {
 		},
 		outputSchema: createMachineOutputSchema
 	}, async (input) => {
-		const machine = xstateMachineResultSchema.parse(await callApi(options, "/v1/convert", {
+		const conversion = xstateConversionCheckSchema.parse(await callApi(options, "/v1/convert", {
 			source: {
 				format: "xstate",
 				content: input.xstateCode
 			},
-			target: { format: "xstate" }
+			target: { format: "xgraph" }
 		}));
+		const machine = {
+			format: "xstate",
+			content: input.xstateCode,
+			warnings: conversion.warnings
+		};
 		return {
 			machine,
 			visualizations: input.visualization === false ? [] : await callApi(options, "/v1/visualize", {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@statelyai/mcp",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "license": "MIT",
   "bin": {
     "stately-mcp": "dist/index.mjs"