@statelyai/mcp 0.3.1 → 0.4.0

package/LICENSE

@@ -1,10 +1,21 @@
-Copyright (c) 2025 Stately Software, Inc.
+MIT License
 
-All rights reserved.
+Copyright (c) 2026 Stately Software, Inc.
 
-This repository and the Stately Viz software are proprietary to Stately
-Software, Inc. No rights are granted to use, copy, modify, distribute, host, or
-sublicense this software except under a separate written agreement with Stately
-Software, Inc.
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
 
-For licensing inquiries, contact team@stately.ai.
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

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