@sanity/workflow-mcp 0.33.0 → 0.34.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @sanity/workflow-mcp
 
+## 0.34.0
+
+### Patch Changes
+
+- @sanity/workflow-engine@0.34.0
+
 ## 0.33.0
 
 ### Patch Changes

package/README.md

@@ -105,20 +105,21 @@ Definition content is unaffected (deploy expands and vets it).
 
 ### Telemetry
 
-The stdio server reports adoption telemetry to Sanity: one
-`Workflows MCP Tool Called` event per tool invocation carrying the
-tool name, a success flag, and whether a list cursor was supplied — from every
-tool it registers, `workflows_list_tags` included, through one shared outcome
-path. Cursor
-values, other tool arguments, and results are never sent. This makes continued
-page usage measurable without collecting customer content. The org-authed boot
-has no project to attribute intake to, so the store initializes with the first
-call that names a dataset resource; calls before that one send nothing. The
-server also reports the engine's own adoption
-events. Nothing is sent unless the account's telemetry consent resolves to
-granted (the account-wide status `sanity telemetry status` shows). Set
-`DO_NOT_TRACK=1` to opt a process out; CI environments (`CI` set) never
-send. Separately from consent, every Content Lake request the server issues
+The stdio server reports adoption telemetry to Sanity. Nothing is sent unless
+the account's telemetry consent resolves to granted (the account-wide status
+`sanity telemetry status` shows). Set `DO_NOT_TRACK=1` to opt a process out;
+CI environments (`CI` set) never send. The org-authed boot has no project to
+attribute intake to, so the store initializes with the first call that names
+a dataset resource; calls before that one send nothing. Address-free tools
+(`workflows_get_authoring_guide`, `workflows_validate_definition`) therefore
+emit nothing until some earlier call has addressed a dataset.
+
+Payloads never include customer-authored strings: no tool arguments, cursor
+values, results, definition names, stage names, GROQ, or document content.
+The one instance-scoped exception the engine already ships is `instanceId`
+(the instance document `_id`).
+
+Separately from consent, every Content Lake request the server issues
 carries a request tag under the `sanity.workflows-mcp` prefix (composing as
 `sanity.workflows-mcp.<op>`) for request-log attribution — deliberately outside
 the zero-rated `sanity.workflows.*` family, so agent-driven traffic bills.
@@ -134,6 +135,68 @@ alongside `context.environment`. Environment does not identify a production
 dataset or deployment; the API host, dataset name, and workflow tag do not
 set it. Existing telemetry consent and opt-out settings still apply.
 
+An embedding host that calls `registerWorkflowTools` without a `telemetry`
+logger records no MCP events. Engine events still require that host to pass
+the same logger into `createEngine({telemetry})`.
+
+#### Session properties
+
+The built-in store attaches these user properties once, when the first dataset
+resource is addressed (joined to events by session id). User identity is not
+in the payload; the intake service resolves the sender from the authenticated
+session. There is no `orgId`: attribution uses the project-to-org join
+downstream.
+
+| Property          | What it is                                          |
+| ----------------- | --------------------------------------------------- |
+| `surface`         | Always `'mcp'`.                                     |
+| `machinePlatform` | Node `process.platform`.                            |
+| `cpuArchitecture` | Node `process.arch`.                                |
+| `runtime`         | Always `'node'` for the stdio server.               |
+| `runtimeVersion`  | Node `process.version`.                             |
+| `packageVersion`  | This package's version.                             |
+| `projectId`       | Project id of the first addressed dataset resource. |
+| `dataset`         | Dataset of that same resource.                      |
+
+#### MCP events
+
+This package defines one event. Every tool it registers — the `WORKFLOW_TOOLS`
+defs and host-registered `workflows_list_tags` — shares one outcome path, so
+adoption, the result envelope, and error rendering cannot diverge.
+
+##### `Workflows MCP Tool Called` (version 2)
+
+One event per tool invocation after the handler settles, including failed
+calls that return an `isError` result.
+
+| Field        | Type      | What is collected                                                                                                                                    |
+| ------------ | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `tool`       | `string`  | Registered tool name (`workflows_list_instances`, `workflows_fire_action`, …). The MCP SDK rejects unregistered names before dispatch.               |
+| `success`    | `boolean` | `true` when the handler returned; `false` when it threw (rendered as `isError`).                                                                     |
+| `cursorUsed` | `boolean` | `true` only for `workflows_list_instances` when `cursor` is a non-empty string. Always `false` for every other tool. The cursor value is never sent. |
+
+#### Engine events the MCP server records
+
+Addressed write tools pass the MCP logger into the engine. Read tools and
+address-free tools do not emit engine events.
+
+Every instance-scoped engine event includes `definitionContentHash` (omitted
+when the definition predates fingerprinting) and `instanceId`.
+
+| Event                           | Version | When the MCP server emits it                           | Additional payload                                                                                                                                                                                                                                                                                                                                               |
+| ------------------------------- | ------- | ------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `Workflows Definition Deployed` | 1       | `workflows_deploy_definition` (created or unchanged)   | `contentHash`, `status` (`'created'` or `'unchanged'`), `deployId` (random run id, not the workflow tag), `stageCount`, `activityCount`, `actionCount`, `transitionCount`, `fieldCount`, `activityKinds`, `fieldKinds`, `guardCount`, `effectCount`, `subworkflowCount`, `lifecycle` (`'standalone'` or `'child'`). Counts and kinds only — never names or GROQ. |
+| `Workflows Instance Started`    | 1       | `workflows_start`, and a fire that spawns a child      | `initialFieldCount`, `viaSpawn` (`true` only for a spawned child), `lifecycle`.                                                                                                                                                                                                                                                                                  |
+| `Workflows Stage Transitioned`  | 1       | A committed hop from start or fire (cascades included) | `fromStageIndex`, `toStageIndex` (indexes into `stages[]`, never names), `toIsTerminal`, `isRevisit`, `dwellMs` (milliseconds in the exited stage, omitted if that entry is missing), `via`: `'transition'`. Unsampled.                                                                                                                                          |
+| `Workflows Action Fired`        | 1       | `workflows_fire_action`                                | `activityKind` (optional), `hasParams` (whether params were supplied — not the params), `cascaded`.                                                                                                                                                                                                                                                              |
+
+This MCP surface has no abort, set-stage, reset-activity, delete, tick, drain,
+or generic field-edit tools, so it does not record `Workflows Instance Aborted`,
+`Workflows Stage Set`, `Workflows Activity Reset`, `Workflows Definition Deleted`,
+`Workflows Field Edited`, `Workflows Instance Ticked`, `Workflows Effects Drained`,
+`Workflows Effect Completed`, or `Workflows Effect State Reported`. Those remain
+engine events for shells that call those verbs.
+
 ## API
 
 The package is a host-neutral library: it never builds an engine, reads

package/dist/stdio.js

@@ -6,7 +6,7 @@ import { deployedTagsGroq, parseResourceGdr, datasetResourceParts, EXECUTION_KIN
 
 import { LIST_WORKFLOW_TAGS_TOOL_NAME, workflowAddressFields, LIST_WORKFLOW_TAGS_DESCRIPTION, withToolTelemetry, clientForResource, registerWorkflowTools, workflowAddressFromInput, createMcpTelemetry, createEngineCache } from "./_chunks-es/index.js";
 
-var version = "0.33.0", packageJson = {
+var version = "0.34.0", packageJson = {
     version: version
 };
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sanity/workflow-mcp",
-  "version": "0.33.0",
+  "version": "0.34.0",
   "description": "MCP server exposing Sanity workflow tools to agents — operate running workflow instances and author new definitions.",
   "keywords": [
     "agent",
@@ -62,15 +62,15 @@
     "@types/node": "^24.12.4",
     "vitest": "^4.1.8",
     "zod": "^4.4.3",
-    "@sanity/workflow-engine": "0.33.0",
-    "@sanity/workflow-engine-test": "0.33.0",
-    "@sanity/workflow-examples": "0.12.1",
+    "@sanity/workflow-engine": "0.34.0",
+    "@sanity/workflow-engine-test": "0.34.0",
+    "@sanity/workflow-examples": "0.12.2",
     "@sanity/workflow-test-fixtures": "0.0.0"
   },
   "peerDependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
     "zod": "^3.25.28 || ^4",
-    "@sanity/workflow-engine": "0.33.0"
+    "@sanity/workflow-engine": "0.34.0"
   },
   "engines": {
     "node": ">=20"