@statelyai/mcp 0.3.2 → 0.4.1

package/README.md

@@ -83,11 +83,11 @@ Mermaid.
 <!-- 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.
+agent authors the XState source, then Stately validates and returns that source
+without rewriting it. 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>
@@ -98,7 +98,7 @@ 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.
+to `false` to return only the validated, authored XState source.
 
 </details>
 
@@ -420,10 +420,11 @@ createMachine({
 
 ## `extract_machines_from_code`
 
-<!-- extract_machines_from_code registration from src/server.ts -->
+<!-- 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 -->
 
-Parses XState source code and returns the extracted machine as an XGraph
-document.
+Statically extracts every XState machine config from JavaScript or TypeScript.
+The parser infers XState v5 or v6 structurally; pass `xstateVersion` only to
+override inference. It does not execute source or require a resource provider.
 
 <details>
 <summary>Summary: extract a machine from TypeScript</summary>
@@ -446,8 +447,63 @@ export const player = createMachine({
 
 </details>
 
-All Stately MCP tools are registered as read-only, non-destructive, idempotent,
-and closed-world.
+## Hosted resource tools
+
+<!-- resource tool registrations from src/resourceTools.ts -->
+
+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.                                 |
+
+Inputs take a `projectId` or `machineId`, never a project version id.
+
+Every call needs a credential: the MCP host supplies it and the bearer token is
+forwarded to the resource provider. Calls without one fail with
+`unauthenticated`, and deployments with no resource provider fail with
+`capability_disabled`. Errors use the canonical resource envelope,
+`{ error: { code, message, issues?, retryable? } }`.
+
+These tools are read-only by policy. Create, update, and delete resource tools
+are deliberately absent.
+
+<details>
+<summary>Summary: list the machines in a hosted project</summary>
+
+```text
+Use Stately to list the machines in project project-id.
+```
+
+```json
+{ "machines": [{ "machineId": "machine-id", "name": "checkout" }] }
+```
+
+</details>
+
+All Stately MCP tools are registered as read-only, non-destructive, and
+idempotent. Machine tools are closed-world; the hosted resource tools are
+open-world.
+
+## Tool-call observation
+
+<!-- onToolCall option and event types from src/server.ts and src/toolCallObserver.ts -->
+
+Hosts can pass `onToolCall` to `registerStatelyMcpTools` or
+`createStatelyMcpServer`. It receives a content-free completion event with the
+tool name, outcome, duration, and stable error code when available. Arguments,
+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`.
+
+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.
 
 ## Self-hosting