@statelyai/mcp 0.9.4 → 0.9.5

package/README.md

@@ -254,7 +254,10 @@ createMachine({
 
 Compares two machine documents structurally instead of comparing their source
 text. It returns a summary and semantic diff; set `includePatches` to request
-applicable patches.
+applicable patches. `hasChanges` also covers supported non-structural changes;
+the node and edge counts remain structural. Generated patches preserve ordered
+actions/invokes and guarded transition priority, including explicit
+null/default resets and action parameter clearing.
 
 <details>
 <summary>Summary: compare two machine versions</summary>
@@ -306,6 +309,13 @@ Patches use semantic graph operations. For example:
 
 Use graph entity IDs; top-level states commonly use `<machine-id>.<state-key>`. Use
 camelCase operation names such as `createTransition`, not snake_case names.
+State patches preserve initial input, output, timeout, and route; transition
+patches preserve input and matches; invoke patches preserve metadata, input, and
+output; implementation patches preserve code; schema patches preserve context,
+event, input, and output schemas. Use `null` to clear these optional fields,
+schemas, or machine context.
+Schema-valid sparse XGraphs may omit effect/tag arrays; create patches initialize
+those collections when needed.
 
 <details>
 <summary>Summary: update a machine</summary>
@@ -520,6 +530,37 @@ 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`.
 
+### Error codes
+
+<!-- allowlist from src/server.ts (upstreamErrorCodes) and @statelyai/api-contract/errors -->
+
+Tool errors carry a `code` from a closed set. An upstream `code` is only
+preserved when it is one of these values; anything else falls back to the
+default for the HTTP status class, so clients never see an invented code.
+
+| Code | Meaning |
+| --- | --- |
+| `bad_request` | Malformed request, and the default for unmapped 4xx statuses. |
+| `unauthenticated` | Missing or rejected credentials (HTTP 401). |
+| `forbidden` | Authenticated but not allowed (HTTP 403). |
+| `not_found` | No such project, machine, or route (HTTP 404). |
+| `conflict` | Version or state conflict (HTTP 409). |
+| `payload_too_large` | Upstream rejected the request size (HTTP 413). |
+| `rate_limited` | Too many requests (HTTP 429). |
+| `capability_disabled` | The operation is not enabled on this deployment. |
+| `upstream_error` | Server-side HTTP failure, and the default for 5xx statuses. |
+| `internal_error` | Unhandled failure inside a tool handler. |
+| `upstream_timeout` | The Stately API did not answer within `apiTimeoutMs`. |
+| `invalid_input` | Local input validation failed before any API call. |
+| `input_too_large` | Input exceeded `maxSourceBytes` before any API call. |
+
+Migration: 4xx responses that previously surfaced an unrecognized upstream code
+verbatim (or `upstream_error` from a proxy) now report the status-class default
+listed above. `upstream_error` remains reserved for 5xx responses.
+
+On HTTP 429 the upstream `Retry-After` header is appended to the error message,
+for example `Too many requests. Retry after 30 seconds.`
+
 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.
@@ -530,11 +571,23 @@ their platform lifecycle primitive.
 
 ## Self-hosting
 
-<!-- self-host MCP endpoint from ../editor/src/app/api/[transport]/route.ts and ../editor/src/lib/auth/oauthProtectedResource.ts -->
+<!-- self-host MCP endpoint from ../editor/src/app/api/[transport]/route.ts and ../editor/src/lib/auth/oauthProtectedResource.ts; deployment canary from package.json and scripts/canary.mjs -->
 
 Self-host Stately Studio, then replace the hosted URL above with your
 deployment's `/api/mcp` endpoint, for example
 `https://studio.example.com/api/mcp`.
 
+After deployment, run the protocol and MCP App canary with a read-only bearer
+credential:
+
+```bash
+STATELY_MCP_CANARY_URL=https://studio.example.com/api/mcp \
+STATELY_MCP_CANARY_TOKEN=... pnpm verify:mcp:canary
+```
+
+It verifies tool discovery, fetches and hashes the advertised app template,
+and runs a minimal visualization. The scheduled production workflow uses the
+`STATELY_MCP_CANARY_TOKEN` repository secret.
+
 For enterprise self-hosting options, [see pricing and contact
 us](https://stately.ai/pricing).