@statelyai/mcp 0.4.0 → 0.5.0

package/LICENSE

@@ -19,3 +19,9 @@ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
+
+Exception: the state-machine graph interface embedded in the MCP App resource
+`ui://stately/visualize-machine.html` is proprietary to Stately Software, Inc.
+No rights are granted to use, copy, modify, distribute, host, sublicense, or
+create derivative works from that interface except under a separate written
+agreement with Stately Software, Inc.

package/README.md

@@ -1,6 +1,7 @@
 # Stately MCP
 
-Use Stately's machine tools from an MCP-compatible agent.
+Validate, execute, explore, compare, convert, and visualize state machines from
+an MCP-compatible agent.
 
 ## Connect
 
@@ -78,36 +79,14 @@ 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.
 
-## `create_state_machine`
-
-<!-- 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.
-
-<details>
-<summary>Summary: create and visualize a machine</summary>
-
-```text
-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.
-
-</details>
-
 ## `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.
+Checks machine syntax and graph structure deterministically. It does not
+typecheck or execute XState source; use `simulate_machine` and
+`generate_graph_paths` to verify runtime behavior. A successful response
+contains `ok` and an `issues` array.
 
 <details>
 <summary>Summary: validate a machine</summary>
@@ -279,8 +258,10 @@ createMachine({
 <!-- 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.
+the event steps, state and transition coverage, total path count, truncation,
+and execution metadata. Stately MCP returns at most five paths per call.
+XState source uses native traversal in an isolated sandbox; other formats are
+converted to structural XGraph first.
 
 <details>
 <summary>Summary: generate shortest paths</summary>
@@ -306,8 +287,9 @@ createMachine({
 <!-- 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.
+states, context, selected action names, and execution metadata. XState source
+runs native transition logic in an isolated sandbox. Structural inputs report
+normalization explicitly.
 
 <details>
 <summary>Summary: simulate events</summary>
@@ -332,11 +314,12 @@ createMachine({
 
 <!-- visualize_machine registration from src/server.ts and visualize response contract -->
 
-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.
+MCP Apps hosts render an interactive, read-only graph with hierarchy drill-in,
+breadcrumbs, selection utilities, pan/zoom, and viewport keyboard shortcuts.
+Other image-capable clients receive one PNG fallback per parent node. Structured
+content includes the raw XGraph plus hierarchy metadata without duplicating
+image data. Use `parentNodeIds` to limit PNG fallback levels; omit it to render
+every parent with direct child states.
 
 Each returned image uses the MCP `ImageContent` shape:
 
@@ -363,61 +346,6 @@ createMachine({
 
 </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' }
-  }
-});
-```
-
-</details>
-
 ## `extract_machines_from_code`
 
 <!-- extract_machines_from_code registration from src/server.ts, API route from packages/editor/src/app/api/v1/code/extract-machines/route.ts, and parser from packages/graph-tools/src/xstateSource.ts -->
@@ -455,12 +383,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.