@statelyai/mcp 0.3.2 → 0.4.0

package/README.md

@@ -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