@statelyai/mcp 0.1.1 → 0.2.0

package/README.md

@@ -6,24 +6,77 @@ Use Stately's machine tools from an MCP-compatible agent.
 
 <!-- public Stately MCP URL -->
 
-Add this remote MCP server URL to your client:
+Choose your client and add Stately MCP using one of these methods.
+
+### Codex
+
+```bash
+codex mcp add stately --url https://stately.ai/mcp
+codex mcp login stately
+```
+
+### Claude Code
+
+```bash
+claude mcp add --transport http stately https://stately.ai/mcp
+```
+
+Then open Claude Code, run `/mcp`, and complete Stately sign-in.
+
+### Cursor
+
+Open **Cursor Settings → MCP → Add new global MCP server**, then add:
+
+```json
+{
+  "mcpServers": {
+    "stately": {
+      "url": "https://stately.ai/mcp"
+    }
+  }
+}
+```
+
+Save the configuration and complete Stately sign-in when Cursor connects. To
+share the server with a project, put the same configuration in
+`.cursor/mcp.json` at the project root.
+
+### VS Code with GitHub Copilot
+
+Create `.vscode/mcp.json` in your project:
+
+```json
+{
+  "servers": {
+    "stately": {
+      "type": "http",
+      "url": "https://stately.ai/mcp"
+    }
+  }
+}
+```
+
+Open the Command Palette and run **MCP: List Servers**, start `stately`, then
+complete Stately sign-in. For a personal configuration available in every
+workspace, run **MCP: Open User Configuration** instead.
+
+### Other MCP clients
+
+Add a remote server using the Streamable HTTP transport and this URL:
 
 ```text
 https://stately.ai/mcp
 ```
 
-The client will open Stately sign-in when authentication is required.
+Complete Stately sign-in when the client connects.
 
 ## Machine input
 
 <!-- shared machine input schemas from src/server.ts -->
 
-Most tools accept either `machine` plus `format`, or a `source` object with
-`format` and `content`. Conversion-based tools support `xstate`, `scxml`,
-`xgraph`, and `d2`. Validation also supports `json`, `yaml`, and `mermaid`.
-
-The examples below use `<machine source>` as a placeholder for the complete
-machine document supplied by the agent.
+Most tools accept a machine config object or a source document. Conversion
+supports XState, SCXML, XGraph, and D2. Validation also supports JSON, YAML, and
+Mermaid.
 
 ## `validate_machine`
 
@@ -32,15 +85,25 @@ machine document supplied by the agent.
 Checks whether a machine can be parsed and reports structural issues such as
 unreachable states. A successful response contains `ok` and an `issues` array.
 
-Example prompt: "Check this machine for logic problems."
+<details>
+<summary>Summary: validate a machine</summary>
 
-```json
-{
-  "machine": "<machine source>",
-  "format": "xstate"
-}
+```text
+Use Stately to validate this machine:
+
+createMachine({
+  id: 'player',
+  initial: 'paused',
+  states: {
+    paused: { on: { PLAY: 'playing' } },
+    playing: { on: { PAUSE: 'paused', STOP: 'stopped' } },
+    stopped: { type: 'final' }
+  }
+});
 ```
 
+</details>
+
 ## `convert_machine`
 
 <!-- convert_machine registration from src/server.ts and convert response contract -->
@@ -48,16 +111,82 @@ Example prompt: "Check this machine for logic problems."
 Converts a machine between XState, SCXML, XGraph, and D2. The response contains
 the target `format`, converted `content`, and any `warnings`.
 
-Example prompt: "Convert this machine to SCXML."
+<details>
+<summary>Summary: convert XState to SCXML</summary>
 
-```json
-{
-  "machine": "<machine source>",
-  "format": "xstate",
-  "to": "scxml"
-}
+```text
+Use Stately to convert this machine to SCXML:
+
+createMachine({
+  id: 'player',
+  initial: 'paused',
+  states: {
+    paused: { on: { PLAY: 'playing' } },
+    playing: { on: { STOP: 'stopped' } },
+    stopped: { type: 'final' }
+  }
+});
+```
+
+</details>
+
+<details>
+<summary>Summary: convert SCXML to XState</summary>
+
+```text
+Use Stately to convert this SCXML machine to XState:
+
+<scxml xmlns="http://www.w3.org/2005/07/scxml" name="player" initial="paused">
+  <state id="paused">
+    <transition event="PLAY" target="playing" />
+  </state>
+  <state id="playing">
+    <transition event="STOP" target="stopped" />
+  </state>
+  <final id="stopped" />
+</scxml>
+```
+
+</details>
+
+<details>
+<summary>Summary: convert XState to D2</summary>
+
+```text
+Use Stately to convert this machine to D2:
+
+createMachine({
+  id: 'player',
+  initial: 'paused',
+  states: {
+    paused: { on: { PLAY: 'playing' } },
+    playing: { on: { STOP: 'stopped' } },
+    stopped: { type: 'final' }
+  }
+});
+```
+
+</details>
+
+<details>
+<summary>Summary: convert XState to XGraph</summary>
+
+```text
+Use Stately to convert this machine to XGraph:
+
+createMachine({
+  id: 'player',
+  initial: 'paused',
+  states: {
+    paused: { on: { PLAY: 'playing' } },
+    playing: { on: { STOP: 'stopped' } },
+    stopped: { type: 'final' }
+  }
+});
 ```
 
+</details>
+
 ## `diff_machines`
 
 <!-- diff_machines registration from src/server.ts and diff response contract -->
@@ -66,16 +195,36 @@ Compares two machine documents structurally instead of comparing their source
 text. It returns a summary and semantic diff; set `includePatches` to request
 applicable patches.
 
-Example prompt: "What changed between these two machines?"
+<details>
+<summary>Summary: compare two machine versions</summary>
 
-```json
-{
-  "base": { "format": "xstate", "content": "<old machine source>" },
-  "compare": { "format": "xstate", "content": "<new machine source>" },
-  "includePatches": true
-}
+```text
+Use Stately to compare these two versions of a machine and suggest patches:
+
+Before:
+createMachine({
+  id: 'player',
+  initial: 'paused',
+  states: {
+    paused: { on: { PLAY: 'playing' } },
+    playing: {}
+  }
+});
+
+After:
+createMachine({
+  id: 'player',
+  initial: 'paused',
+  states: {
+    paused: { on: { PLAY: 'playing' } },
+    playing: { on: { STOP: 'stopped' } },
+    stopped: { type: 'final' }
+  }
+});
 ```
 
+</details>
+
 ## `apply_machine_patches`
 
 <!-- apply_machine_patches registration from src/server.ts and apply-patches response contract -->
@@ -83,19 +232,24 @@ Example prompt: "What changed between these two machines?"
 Applies semantic patches to a machine and returns the updated document. Use
 `to` to choose the returned format.
 
-Example prompt: "Apply these suggested changes and return XState code."
+<details>
+<summary>Summary: update a machine</summary>
 
-```json
-{
-  "machine": "<machine source>",
-  "format": "xstate",
-  "patches": [
-    { "op": "updateState", "stateId": "active", "key": "complete" }
-  ],
-  "to": "xstate"
-}
+```text
+Use Stately to rename the playing state to active and return the updated XState machine:
+
+createMachine({
+  id: 'player',
+  initial: 'paused',
+  states: {
+    paused: { on: { PLAY: 'playing' } },
+    playing: {}
+  }
+});
 ```
 
+</details>
+
 ## `generate_graph_paths`
 
 <!-- generate_graph_paths registration from src/server.ts and graph-paths response contract -->
@@ -104,17 +258,25 @@ Generates shortest or simple paths through a machine. The response includes
 the event steps for each path plus state and transition coverage. Stately MCP
 returns at most five paths per call.
 
-Example prompt: "Find the shortest paths through this machine."
+<details>
+<summary>Summary: generate shortest paths</summary>
 
-```json
-{
-  "machine": "<machine source>",
-  "format": "xstate",
-  "kind": "shortest",
-  "max": 5
-}
+```text
+Use Stately to find up to five shortest paths through this machine:
+
+createMachine({
+  id: 'player',
+  initial: 'paused',
+  states: {
+    paused: { on: { PLAY: 'playing' } },
+    playing: { on: { PAUSE: 'paused', STOP: 'stopped' } },
+    stopped: { type: 'final' }
+  }
+});
 ```
 
+</details>
+
 ## `simulate_machine`
 
 <!-- simulate_machine registration from src/server.ts and simulate response contract -->
@@ -123,33 +285,60 @@ Runs up to 100 events through a machine and returns a step-by-step trace of
 states, context, and executed action names. Guards are stubbed during this
 deterministic simulation.
 
-Example prompt: "Simulate PLAY followed by STOP."
+<details>
+<summary>Summary: simulate events</summary>
 
-```json
-{
-  "machine": "<machine source>",
-  "format": "xstate",
-  "events": [{ "type": "PLAY" }, { "type": "STOP" }]
-}
+```text
+Use Stately to simulate PLAY followed by STOP on this machine:
+
+createMachine({
+  id: 'player',
+  initial: 'paused',
+  states: {
+    paused: { on: { PLAY: 'playing' } },
+    playing: { on: { STOP: 'stopped' } },
+    stopped: { type: 'final' }
+  }
+});
 ```
 
+</details>
+
 ## `visualize_machine`
 
 <!-- visualize_machine registration from src/server.ts and visualize response contract -->
 
-Renders a machine as an SVG diagram. The response contains the SVG string,
-its width and height, and any warnings.
+Renders each machine hierarchy level as a directly viewable PNG. Codex,
+Claude, and other image-capable MCP clients receive one native image block per
+parent node. Structured content contains parent IDs, labels, hierarchy levels,
+dimensions, and warnings without duplicating image data. Use `parentNodeIds` to
+select levels; omit it to render every parent with direct child states.
 
-Example prompt: "Draw this machine from left to right."
+Each returned image uses the MCP `ImageContent` shape:
 
-```json
-{
-  "machine": "<machine source>",
-  "format": "xstate",
-  "direction": "right"
-}
+```ts
+{ type: 'image', data: pngBase64, mimeType: 'image/png' }
 ```
 
+<details>
+<summary>Summary: visualize a machine</summary>
+
+```text
+Use Stately to visualize this machine from left to right:
+
+createMachine({
+  id: 'player',
+  initial: 'paused',
+  states: {
+    paused: { on: { PLAY: 'playing' } },
+    playing: { on: { STOP: 'stopped' } },
+    stopped: { type: 'final' }
+  }
+});
+```
+
+</details>
+
 ## `analyze_machine`
 
 <!-- analyze_machine registration from src/server.ts and analyze response contract -->
@@ -159,16 +348,25 @@ the machine against its expected behavior. The response contains issues and may
 include suggested fixes. Use `validate_machine` when only deterministic checks
 are needed.
 
-Example prompt: "Check that STOP always ends playback permanently."
+<details>
+<summary>Summary: analyze intended behavior</summary>
 
-```json
-{
-  "machine": "<machine source>",
-  "format": "xstate",
-  "intent": "STOP must reach a final state, and playback must not restart"
-}
+```text
+Use Stately to check that STOP reaches a final state and playback cannot restart:
+
+createMachine({
+  id: 'player',
+  initial: 'paused',
+  states: {
+    paused: { on: { PLAY: 'playing' } },
+    playing: { on: { STOP: 'stopped' } },
+    stopped: { type: 'final' }
+  }
+});
 ```
 
+</details>
+
 ## `generate_test_code`
 
 <!-- generate_test_code registration and generateTestCode implementation from src/server.ts -->
@@ -177,17 +375,25 @@ Generates a runnable Vitest file with one test per generated path. Each test
 sends the path's events and asserts its final state. Guards and actions are
 stubbed.
 
-Example prompt: "Generate tests for the shortest paths through this machine."
+<details>
+<summary>Summary: generate Vitest tests</summary>
 
-```json
-{
-  "machine": "<machine source>",
-  "format": "xstate",
-  "kind": "shortest",
-  "max": 5
-}
+```text
+Use Stately to generate Vitest tests for the shortest paths through this machine:
+
+createMachine({
+  id: 'player',
+  initial: 'paused',
+  states: {
+    paused: { on: { PLAY: 'playing' } },
+    playing: { on: { STOP: 'stopped' } },
+    stopped: { type: 'final' }
+  }
+});
 ```
 
+</details>
+
 ## `extract_machines_from_code`
 
 <!-- extract_machines_from_code registration from src/server.ts -->
@@ -195,13 +401,37 @@ Example prompt: "Generate tests for the shortest paths through this machine."
 Parses XState source code and returns the extracted machine as an XGraph
 document.
 
-Example prompt: "Extract the XState machine from this TypeScript file."
+<details>
+<summary>Summary: extract a machine from TypeScript</summary>
 
-```json
-{
-  "code": "import { createMachine } from 'xstate';\nexport const player = createMachine({ /* complete config */ });"
-}
+```text
+Use Stately to extract the machine from this TypeScript:
+
+import { createMachine } from 'xstate';
+
+export const player = createMachine({
+  id: 'player',
+  initial: 'paused',
+  states: {
+    paused: { on: { PLAY: 'playing' } },
+    playing: { on: { STOP: 'stopped' } },
+    stopped: { type: 'final' }
+  }
+});
 ```
 
+</details>
+
 All Stately MCP tools are registered as read-only, non-destructive, idempotent,
 and closed-world.
+
+## Self-hosting
+
+<!-- self-host MCP endpoint from ../editor/src/app/api/[transport]/route.ts and ../editor/src/lib/auth/oauthProtectedResource.ts -->
+
+Self-host Stately Studio, then replace the hosted URL above with your
+deployment's `/api/mcp` endpoint, for example
+`https://studio.example.com/api/mcp`.
+
+For enterprise self-hosting options, [see pricing and contact
+us](https://stately.ai/pricing).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@statelyai/mcp",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "license": "UNLICENSED",
   "type": "module",
   "files": [