@statelyai/mcp 0.8.7 → 0.9.1

package/README.md

@@ -13,11 +13,10 @@ own Stately deployment.
 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*.
+**Both use Stately credentials by default.** Only `list_machines` and
+`get_machine` run entirely on your machine; every other tool calls the
+configured HTTP API. Stately's hosted API rejects unauthenticated calls with
+`Missing authentication.` A self-hosted API can define its own auth policy.
 
 ### Local (stdio)
 
@@ -294,6 +293,20 @@ createMachine({
 Applies semantic patches to a machine and returns the updated document. Use
 `to` to choose the returned format.
 
+Patches use semantic graph operations. For example:
+
+```json
+{
+  "op": "createTransition",
+  "sourceId": "player.playing",
+  "targetId": "player.paused",
+  "eventType": "STOP"
+}
+```
+
+Use graph entity IDs; top-level states commonly use `<machine-id>.<state-key>`. Use
+camelCase operation names such as `createTransition`, not snake_case names.
+
 <details>
 <summary>Summary: update a machine</summary>
 
@@ -328,6 +341,8 @@ converted to structural XGraph first.
 ```text
 Use Stately to find up to five shortest paths through this machine:
 
+import { createMachine } from 'xstate';
+
 createMachine({
   id: 'player',
   initial: 'paused',
@@ -356,6 +371,8 @@ normalization explicitly.
 ```text
 Use Stately to simulate PLAY followed by STOP on this machine:
 
+import { createMachine } from 'xstate';
+
 createMachine({
   id: 'player',
   initial: 'paused',
@@ -374,7 +391,9 @@ createMachine({
 <!-- visualize_machine registration from src/server.ts and visualize response contract -->
 
 MCP Apps hosts render an interactive, read-only graph with hierarchy drill-in,
-breadcrumbs, selection utilities, pan/zoom, and viewport keyboard shortcuts.
+breadcrumbs, select/pan/structural-simulation controls, selection utilities,
+zoom, viewport recovery, keyboard shortcuts, and a host-mediated link to the
+same graph in Stately. It starts in pan mode; AI controls remain hidden.
 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.
@@ -477,7 +496,7 @@ are deliberately absent.
 <summary>Summary: list the machines in a hosted project</summary>
 
 ```text
-Use Stately to list the machines in project project-id.
+Use Stately to list the machines in the project with ID `project-id`.
 ```
 
 ```json
@@ -492,7 +511,7 @@ open-world.
 
 ## Tool-call observation
 
-<!-- onToolCall option and event types from src/server.ts and src/toolCallObserver.ts -->
+<!-- onToolCall and clientId options from src/server.ts and event types from src/toolCallObserver.ts -->
 
 Hosts can pass `onToolCall` to `registerStatelyMcpTools` or
 `createStatelyMcpServer`. It receives a content-free completion event with the
@@ -501,6 +520,10 @@ machine source, and results are never included. Input and output validation
 failures are reported as errors. Configure the observer before registering any
 other tools on the same `McpServer`.
 
+Set `clientId` to label this server's HTTP analysis calls for channel-level
+telemetry. It defaults to `stately-mcp/embedded`; the stdio binary uses
+`stately-mcp/stdio`. The label carries no user or machine content.
+
 The observer is absent by default. Its failures do not affect tool results, and
 its promises are not awaited; serverless hosts should schedule delivery with
 their platform lifecycle primitive.