@statelyai/mcp 0.8.3 → 0.8.6

package/README.md

@@ -3,11 +3,69 @@
 Validate, execute, explore, compare, convert, and visualize state machines from
 an MCP-compatible agent.
 
-## Connect
+## Two ways to run it
+
+**Local (stdio).** `npx @statelyai/mcp` runs the server on your machine. Use it
+when you want the server in-process, or when you need to point the tools at your
+own Stately deployment.
+
+**Hosted (HTTP).** `https://mcp.stately.ai/mcp` needs no local install and adds
+the [hosted resource tools](#hosted-resource-tools) that read your Stately
+projects.
+
+**Both require a Stately credential.** Only `list_machines` and `get_machine`
+run entirely on your machine; every other tool sends the machine to Stately's
+HTTP API, which rejects unauthenticated calls with `Missing authentication.`
+Running locally changes *where the process lives*, not *whether you need an
+account*.
+
+### Local (stdio)
+
+Add this to your MCP client configuration:
+
+```json
+{
+  "mcpServers": {
+    "stately": {
+      "command": "npx",
+      "args": ["-y", "@statelyai/mcp"],
+      "env": { "STATELY_ACCESS_TOKEN": "..." }
+    }
+  }
+}
+```
+
+Or install it and run the `stately-mcp` binary directly:
+
+```bash
+npm install -g @statelyai/mcp
+stately-mcp
+```
+
+Credentials are read from `STATELY_ACCESS_TOKEN`, `STATELY_API_KEY`, or the
+config written by `statelyai login`.
+
+The API defaults to `https://editor.stately.ai/api`. Point it at a self-hosted
+deployment with `STATELY_API_BASE_URL`:
+
+```json
+{
+  "mcpServers": {
+    "stately": {
+      "command": "npx",
+      "args": ["-y", "@statelyai/mcp"],
+      "env": { "STATELY_API_BASE_URL": "https://stately.internal/api" }
+    }
+  }
+}
+```
+
+## Connect to the hosted endpoint
 
 <!-- public Stately MCP URL -->
 
-Choose your client and add Stately MCP using one of these methods.
+Choose your client and add Stately MCP using one of these methods. Each ends in
+a Stately sign-in; to run the server locally instead, see [Local (stdio)](#local-stdio) above.
 
 ### Codex
 
@@ -321,15 +379,17 @@ Pass XState source text (the default for strings), a JSON machine config, SCXML,
 XGraph, Mermaid, or D2; the server converts it once to canonical XGraph before
 rendering the app and PNG fallbacks.
 Other image-capable clients receive one PNG fallback per parent node. Structured
-content uses a required `schemaVersion: "1.0"` envelope. Its `interactive` and
-`pngFallback` fields independently discriminate `ready` from `unavailable`, so
-PNG rendering may succeed when the persisted interactive graph is unavailable.
+content uses a required `schemaVersion: "2.0"` envelope with a canonical XGraph
+JSON string in `interactive.graphJson`. Every V2 field has a concrete JSON
+schema so hosts can persist the result without traversing open XGraph data.
+`interactive` and `pngFallback` independently report `ready` or `unavailable`,
+so PNG rendering may succeed when the persisted interactive graph is unavailable.
 The graph is capped at 500,000 UTF-8 bytes by default and PNG metadata at 100
 entries; image bytes remain native MCP content blocks. Use `parentNodeIds` to
 limit PNG fallback levels; omit it to render every parent with direct children.
 
 The App reads only this declared structured output. The stable resource URI is
-retained: newer bundles decode V1 and the earlier unversioned `graph` /
+retained: newer bundles decode V2, V1, and the earlier unversioned `graph` /
 `graphError` shape. Saved results created before graph fields were declared
 cannot be reconstructed and deliberately ask the user to run the tool again.