@statelyai/mcp 0.1.0 → 0.1.2

package/LICENSE

@@ -0,0 +1,10 @@
+Copyright (c) 2025 Stately Software, Inc.
+
+All rights reserved.
+
+This repository and the Stately Viz software are proprietary to Stately
+Software, Inc. No rights are granted to use, copy, modify, distribute, host, or
+sublicense this software except under a separate written agreement with Stately
+Software, Inc.
+
+For licensing inquiries, contact team@stately.ai.

package/README.md

@@ -1,58 +1,428 @@
-# @statelyai/mcp
+# Stately MCP
 
-Reusable Stately MCP server for XState machine tooling.
+Use Stately's machine tools from an MCP-compatible agent.
 
-## Hosted HTTP usage
+## Connect
 
-<!-- hosted server factory and options from src/server.ts -->
+<!-- public Stately MCP URL -->
 
-```ts
-import { createStatelyMcpServer } from '@statelyai/mcp';
+Choose your client and add Stately MCP using one of these methods.
 
-const server = createStatelyMcpServer({
-  includeWorkspaceTools: false,
-  apiBaseUrl: 'https://editor.stately.ai/api',
-  credentialProvider: async () => ({
-    type: 'oauth',
-    accessToken,
-  }),
-  anonymousGraphPathLimit: 5,
+### 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
+```
+
+Complete Stately sign-in when the client connects.
+
+## Machine input
+
+<!-- shared machine input schemas from src/server.ts -->
+
+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`
+
+<!-- validate_machine registration from src/server.ts and validate response contract -->
+
+Checks whether a machine can be parsed and reports structural issues such as
+unreachable states. A successful response contains `ok` and an `issues` array.
+
+<details>
+<summary>Summary: validate a machine</summary>
+
+```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' }
+  }
 });
 ```
 
-The host owns the transport, auth, CORS, rate limiting, and deployment. This
-package owns MCP tool schemas, handlers, annotations, and calls to the Stately
-HTTP API. Use `authMode: 'none'` only when the API is protected elsewhere.
+</details>
 
-## Local stdio usage
+## `convert_machine`
 
-<!-- stdio CLI bin from package.json and workspace tools from src/index.ts -->
+<!-- convert_machine registration from src/server.ts and convert response contract -->
 
-```bash
-stately-mcp --workspace /path/to/project
+Converts a machine between XState, SCXML, XGraph, and D2. The response contains
+the target `format`, converted `content`, and any `warnings`.
+
+<details>
+<summary>Summary: convert XState to SCXML</summary>
+
+```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 -->
+
+Compares two machine documents structurally instead of comparing their source
+text. It returns a summary and semantic diff; set `includePatches` to request
+applicable patches.
+
+<details>
+<summary>Summary: compare two machine versions</summary>
+
+```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 -->
+
+Applies semantic patches to a machine and returns the updated document. Use
+`to` to choose the returned format.
+
+<details>
+<summary>Summary: update a machine</summary>
+
+```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 -->
+
+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.
+
+<details>
+<summary>Summary: generate shortest paths</summary>
+
+```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 -->
+
+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.
+
+<details>
+<summary>Summary: simulate events</summary>
+
+```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.
+
+<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 -->
+
+Combines deterministic checks with AI review. Provide optional intent to assess
+the machine against its expected behavior. The response contains issues and may
+include suggested fixes. Use `validate_machine` when only deterministic checks
+are needed.
+
+<details>
+<summary>Summary: analyze intended behavior</summary>
+
+```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 -->
+
+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.
+
+<details>
+<summary>Summary: generate Vitest tests</summary>
+
+```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' }
+  }
+});
 ```
 
-Local stdio mode includes workspace tools:
+</details>
+
+## `extract_machines_from_code`
+
+<!-- extract_machines_from_code registration from src/server.ts -->
+
+Parses XState source code and returns the extracted machine as an XGraph
+document.
+
+<details>
+<summary>Summary: extract a machine from TypeScript</summary>
+
+```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' }
+  }
+});
+```
 
-- `list_machines`
-- `get_machine`
+</details>
 
-API-backed tools read `STATELY_ACCESS_TOKEN`, stored CLI credentials, or
-`STATELY_API_KEY`. Use `STATELY_AUTH_MODE=none` for no-auth self-hosted APIs.
+All Stately MCP tools are registered as read-only, non-destructive, idempotent,
+and closed-world.
 
-## Tools
+## Self-hosting
 
-<!-- hosted MCP tool registrations from src/server.ts -->
+<!-- self-host MCP endpoint from ../editor/src/app/api/[transport]/route.ts and ../editor/src/lib/auth/oauthProtectedResource.ts -->
 
-- `validate_machine`
-- `convert_machine`
-- `diff_machines`
-- `apply_machine_patches`
-- `generate_graph_paths`
-- `simulate_machine`
-- `visualize_machine`
-- `analyze_machine`
-- `generate_test_code`
-- `extract_machines_from_code`
+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`.
 
-All tools are annotated read-only, non-destructive, idempotent, and closed-world.
+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.0",
+  "version": "0.1.2",
   "license": "UNLICENSED",
   "type": "module",
   "files": [
@@ -19,11 +19,6 @@
       "require": "./dist/index.cjs"
     }
   },
-  "scripts": {
-    "build": "tsdown",
-    "test": "vitest run",
-    "test:watch": "vitest"
-  },
   "dependencies": {
     "@modelcontextprotocol/sdk": "1.26.0",
     "zod": "^4.4.1"
@@ -32,5 +27,10 @@
     "@types/node": "25.2.1",
     "tsdown": "0.21.0-beta.2",
     "vitest": "^3.2.4"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "test": "vitest run",
+    "test:watch": "vitest"
   }
-}
+}