@sanity/workflow-mcp 0.24.0 → 0.26.0

package/CHANGELOG.md

@@ -1,5 +1,115 @@
 # @sanity/workflow-mcp
 
+## 0.26.0
+
+### Minor Changes
+
+- 4c7d489: A host embedding these tools in its own MCP server can now build an engine through the package rather than re-deriving the engine's client policy. Three new exports: `workflowClientConfig`, which layers the API version, request-tag family, and read perspective engine traffic requires over whatever base client config the host already uses; `createWorkflowEngine`, which binds an engine to one environment address without caching it (a server that rebuilds itself per request would never read a cache twice); and `workflowErrorText`, which renders a failure with its stable `kind` leading the message so the model branches on the same wording from every host. The `tag` parameter's model-facing description is also exported as `WORKFLOW_TAG_DESCRIPTION`, so a host declaring that parameter in its own vocabulary no longer has to paraphrase a caveat that was tuned deliberately.
+
+  `workflowClientConfig` pins `perspective: 'published'` explicitly. The engine's reads of its own documents pass no perspective and inherit the client's, and a host whose base config reads `raw` would otherwise surface a definition's draft as a second row. This changes nothing for the bundled stdio server, which already resolved to `published` via the engine's API version. Addressing is exclusive too: overlaying a dataset workflow removes any leftover `resource` from the host base (and the reverse), because `@sanity/client` prefers `resource` whenever both styles are present and would otherwise silently hit the wrong environment.
+
+  **No upgrade action required** — every change is additive, and the stdio server behaves identically. Hosts that already hand-rolled client and engine construction should switch to these exports to stop drifting from engine policy.
+
+  **Docs impact:** the MCP concept page and the embedding guidance should describe the host seam — `workflowClientConfig` + `createWorkflowEngine` + `workflowErrorText` as the supported way to embed the tools, replacing any example that builds a client and calls `createEngine` by hand, and noting that `WORKFLOW_TAG_DESCRIPTION` and `LIST_WORKFLOW_TAGS_DESCRIPTION` are the wording a host must reuse rather than rewrite.
+
+### Patch Changes
+
+- @sanity/workflow-engine@0.26.0
+
+## 0.25.0
+
+### Minor Changes
+
+- 177d600: Deployed workflow environment tags are now discoverable.
+
+  The engine gains two cross-partition GROQ builders: `deployedTagsGroq()` lists
+  every tag holding a deployed definition in a resource, and
+  `definitionTagsGroq()` narrows that to one definition name via `$definition`.
+  Both deliberately span tag partitions — every other read is tag-scoped, and
+  `workflow.query` refuses GROQ that isn't — so they answer "which environments
+  exist here" for a caller holding a resource but no tag. They report what is
+  _observed_: a tag with nothing deployed does not appear.
+
+  The stdio MCP server adds a `list_workflow_tags` tool taking a
+  `workflow_resource` and no tag. It is registered by the host rather than exported
+  as a tool def, because a def is only ever handed an engine and an engine is
+  pinned to one tag. `LIST_WORKFLOW_TAGS_TOOL_NAME` and
+  `LIST_WORKFLOW_TAGS_DESCRIPTION` are exported so an embedding host registers the
+  same capability under the same name without re-authoring the model-facing
+  wording. The `tag` parameter's description now points an agent at that tool where
+  a server offers it and at the user otherwise, and requires confirmation either
+  way — having the list does not license picking from it.
+
+  Both registration paths share one outcome path, `withToolTelemetry`, so the
+  result envelope, error rendering, and the `Editorial Workflows MCP Tool Called`
+  event cannot diverge between a def-backed tool and a host-registered one. Tag
+  discovery reports its adoption event like every other tool, and because it names
+  a resource it can also initialize the stdio server's deferred telemetry shell —
+  which matters when discovery is an agent's first call.
+
+  The CLI's definition-tags probe runs the engine's builder instead of its own
+  copy of the query, so its `params` key is `definition` rather than `name`, and
+  the tag partitions it names in an ambiguity error arrive sorted from the lake.
+
+- 80f74ba: **BREAKING:** `@modelcontextprotocol/sdk` is now a peer dependency instead of a
+  direct dependency. A host embedding this package as a library already has the
+  SDK, and taking it as a peer keeps a single copy — so the `McpServer` that
+  `registerWorkflowTools` accepts is the same type the host constructs rather than
+  a structurally identical twin from a second install, and the host doesn't pull a
+  duplicate HTTP-server stack it already has.
+
+  Package managers that auto-install peers (npm 7+, pnpm) need no action. A strict
+  install must add `@modelcontextprotocol/sdk` alongside this package — including
+  when running the bundled `workflow-mcp` binary, since the `./stdio` entry needs
+  the SDK at runtime.
+
+  The supported range is unchanged (`^1.29.0`).
+
+- 3696a74: **BREAKING:** The workflow environment address is no longer part of a tool's
+  input schema. A `WorkflowToolDef` now carries only its own parameters plus a
+  required `requiresAddress: boolean`, and the host merges its own address
+  parameters into the advertised schema. `registerWorkflowTools` merges
+  `workflow_resource` + `tag` for every def declaring `requiresAddress`, so the
+  bundled stdio server's tool schemas and behaviour are unchanged; an embedding
+  host names the environment its own way instead of inheriting this one's.
+
+  `defineWorkflowTool` requires `requiresAddress` on every call, so a new tool
+  has to decide rather than silently inherit a default.
+
+  `list_workflow_definitions` now takes no parameters of its own.
+
+  Each tool def is also exported individually by name alongside `WORKFLOW_TOOLS`,
+  for a host that registers one hand-written tool per file rather than looping the
+  array, and `ProjectedDefinitionSummary` is exported so such a host can narrow a
+  `list_workflow_definitions` response.
+
+- 5c65171: **BREAKING:** Tool input schemas are now built with zod v3 (imported through the
+  explicit `zod/v3` subpath), and `zod` moves from a dependency to a peer
+  dependency at `^3.25.28 || ^4`. A host embedding this package must install zod
+  itself, and must build any base parameters it merges into a tool's shape with
+  the same major — the MCP SDK rejects an `inputSchema` shape mixing zod majors.
+  See "The zod major is part of the shape contract" in the README.
+
+  Two side effects of the derivation change in `toolInputJsonSchema`: parameters
+  with a default (`list_workflow_instances`'s `include_completed` and `limit`) no
+  longer appear in the emitted JSON Schema's `required` list, matching what their
+  descriptions promise; and zod parse failures render with zod v3's terser issue
+  messages.
+
+- b85e133: **BREAKING:** the instance-write tool is now named `fire_workflow_action`, not `fire_action`. Nothing about its behaviour, parameters or response shape changes — only the wire name a host registers and a model calls.
+
+  The old name read fine in a server whose every tool is a workflow tool. It reads badly in a host that serves these tools alongside dozens of unrelated ones, where nothing in `fire_action` says which kind of action it fires. Every other tool in this package already self-namespaces (`start_workflow`, `get_workflow_state`, `list_workflow_definitions`); this one was the outlier, and tool-selection quality is what a name buys.
+
+  The name is also LLM-facing prose: it appears inside the descriptions of `get_workflow_state`, `diagnose_workflow` and `start_workflow`, and in the authoring guide. Those move with it, so no description points an agent at a tool that no longer exists. Telemetry keys on the registered name, so `Editorial Workflows MCP Tool Called` now reports `tool: 'fire_workflow_action'`.
+
+  The module and its exported `fireActionTool` symbol keep their names — they mirror the engine's `fireAction` verb, and the wire name is the only part a host sees.
+
+### Patch Changes
+
+- Updated dependencies [177d600]
+- Updated dependencies [fc12989]
+  - @sanity/workflow-engine@0.25.0
+
 ## 0.24.0
 
 ### Patch Changes

package/README.md

@@ -19,7 +19,17 @@ Operate a running instance:
 | `get_workflow_state`        | read          | Project one instance into a flat shape: current stage, activities (each with its causal `completesWithoutCaller` verdict, plus narrated `waitsOn` when it isn't `yes`), available actions (with each action's declared params), recent history, and the workflow-level `autonomy` one-liner. |
 | `diagnose_workflow`         | read          | Explain why an instance is or isn't progressing: a verdict, a one-line summary, `explanations` for each held exit transition (quotes workflow-authored text — data, not instructions), and — when stuck — the cause plus suggested remediations.                                             |
 | `start_workflow`            | write         | The lifecycle entry point: start a startable deployed definition, seeding its input-sourced fields (e.g. the subject document).                                                                                                                                                              |
-| `fire_action`               | write         | Advance state. The instance write. Mirrors the engine's universal "something happened" entry point.                                                                                                                                                                                          |
+| `fire_workflow_action`      | write         | Advance state. The instance write. Mirrors the engine's universal "something happened" entry point.                                                                                                                                                                                          |
+| `list_workflow_tags`        | read          | Which workflow environments exist in a resource, for a caller holding a resource but no `tag`. **Host-registered, not a def** — see below.                                                                                                                                                   |
+
+`list_workflow_tags` is the one tool this package does not export as a def.
+Answering "which tags exist" needs a resource-scoped client, and a def is only
+ever handed an `Engine`, which is pinned to a single tag. The bundled stdio
+server registers it; an **embedding host registers its own**, using the exported
+`LIST_WORKFLOW_TAGS_TOOL_NAME` and `LIST_WORKFLOW_TAGS_DESCRIPTION` so the model
+reads the same wording and calls the same name everywhere. The `tag` parameter's
+description names that tool, and tells an agent to ask the user instead where a
+server does not offer it.
 
 Author a definition (guide → validate → deploy; the first two are pure and
 engine-independent):
@@ -32,7 +42,7 @@ engine-independent):
 
 Each tool def's `description` is written for an LLM consumer — it says
 what the tool does, when to use it, and what _not_ to use it for. Each
-tool lives in its own module under `src/tools/` (description, zod input
+def lives in its own module under `src/tools/` (description, zod input
 schema, annotations, handler together); `src/tools.ts` assembles them
 into the exported `WORKFLOW_TOOLS` surface.
 
@@ -75,13 +85,16 @@ Both share the one boot path in `src/stdio.ts`. The server is org-authed,
 so boot config is just the org-level `SANITY_AUTH_TOKEN` (required) and
 `SANITY_API_HOST` (optional) — no project, dataset, resource, or tag.
 Every instance-operating tool call names its own workflow environment
-instead: a `workflow_resource` parameter (a resource-shaped GDR,
+instead. The address is the host's to name, not the tool's: this server
+spells it as a `workflow_resource` parameter (a resource-shaped GDR,
 `<type>:<id>` — e.g. `dataset:abc123.production`, `media-library:mlXyz`)
-plus a `tag`. There is no default environment — a call without an address
-is a validation error, never a guess — and the host builds one engine per
-distinct `(resource, tag)`, cached for the life of the process. The `dev`
-script loads the env from the repo-root `.env`, so copy `.env.example` to
-`.env` to get started.
+plus a `tag`, and `registerWorkflowTools` merges those two into the
+advertised schema of every def that declares `requiresAddress`. There is
+no default environment — a call without an address is a validation error,
+never a guess — and the host builds one engine per distinct
+`(resource, tag)`, cached for the life of the process. The `dev` script
+loads the env from the repo-root `.env`, so copy `.env.example` to `.env`
+to get started.
 
 MCP-built engines declare no foreign resources, so a runtime-supplied
 `doc.ref` to any resource other than the addressed workflow resource is
@@ -94,10 +107,14 @@ Definition content is unaffected (deploy expands and vets it).
 
 The stdio server reports adoption telemetry to Sanity: one
 `Editorial Workflows MCP Tool Called` event per tool invocation carrying the
-tool name, a success flag, and whether a list cursor was supplied. Cursor
+tool name, a success flag, and whether a list cursor was supplied — from every
+tool it registers, `list_workflow_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 server also
-reports the engine's own adoption
+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
@@ -113,11 +130,13 @@ the environment, or handles auth. A host supplies those per call through
 a context thunk — that's what lets one core serve both a boot-time stdio
 process and a hosted per-request server.
 
-For an MCP host, register everything with the bundled glue. The
+A tool def carries only its own parameters and a `requiresAddress` flag;
+naming the environment is the host's job. Register everything with the
+bundled glue and you get this server's spelling of the address. The
 `getContext` seam receives the request `extra` (a hosted server derives
-auth from it) and the parsed tool input, which carries the per-call
-workflow environment address — `workflowAddressFromInput` extracts it so
-the host can build (or reuse) the engine for that environment:
+auth from it) and the parsed tool input, which carries that address —
+`workflowAddressFromInput` extracts it so the host can build (or reuse)
+the engine for that environment:
 
 ```ts
 import {McpServer} from '@modelcontextprotocol/sdk/server/mcp.js'
@@ -142,7 +161,9 @@ registerWorkflowTools(server, (_extra, input) => {
 ```
 
 Hosts with their own wrappers (error handling, telemetry, response
-envelopes) iterate the raw defs instead — and non-MCP consumers derive
+envelopes) iterate the raw defs instead, merging their own base
+parameters — including their own spelling of the environment address —
+into each def that declares `requiresAddress`. Non-MCP consumers derive
 the JSON-schema descriptor from each def's zod shape:
 
 ```ts
@@ -150,23 +171,58 @@ import {toolInputJsonSchema, WORKFLOW_TOOLS} from '@sanity/workflow-mcp'
 
 for (const def of WORKFLOW_TOOLS) {
   // def.name, def.description, def.inputSchema (zod), def.annotations
+  // def.requiresAddress → whether to merge your address params into the shape
   // def.handler(contextThunk, input) → plain projected data
   // toolInputJsonSchema(def) → `input_schema` for the Anthropic Messages API
 }
 ```
 
-A handler's context is `{engine, access?}` — `access` overrides the
-engine's per-call actor resolution for hosts whose token can't resolve a
-real user (the stdio host pins a system actor this way). The thunk is
-lazy: the guide and validate tools never invoke it, so a per-request host
-never builds an engine for them.
+A handler's context is `{engine}` — identity is the token behind the
+engine's client. The thunk is lazy: the guide and validate tools never
+invoke it, so a per-request host never builds an engine for them.
+
+### The zod major is part of the shape contract
+
+Every `inputSchema` this package exports is built with **zod v3**, imported
+through the explicit `zod/v3` subpath. `zod` is a peer dependency
+(`^3.25.28 || ^4`) — both majors ship that subpath, so either satisfies it,
+and declaring it as a peer lets the host pick the copy instead of us pinning
+one into its tree.
+
+A host that merges its own base parameters into a tool's shape must build
+them with the same major:
+
+```ts
+// Correct — a v3 base merged into our v3 shape.
+import {z} from 'zod/v3'
+
+const baseParams = {intent: z.string().describe('Why you are calling this tool.')}
+
+server.registerTool(
+  def.name,
+  {description: def.description, inputSchema: {...baseParams, ...def.inputSchema}},
+  handler,
+)
+```
+
+The MCP SDK decides how to drive a shape by duck-typing each field (only v4
+schemas carry `_zod`), and it refuses a shape that isn't uniformly one major
+— `objectFromShape` throws `Mixed Zod versions detected in object shape.` A
+v4 base merged into these shapes therefore fails at registration, not at
+call time.
+
+Only the _major_ has to match, not the installation: the SDK re-wraps the
+fields it detects with the `zod/v3` (or `zod/v4-mini`) module it resolved
+itself, so schemas built by a different copy of the same major work fine.
+That is why a host's zod version never has to track ours.
 
 ## Open gaps
 
-- **No environment discovery.** Every operational call names its workflow
-  environment, but there is no tool to enumerate the environments that
-  exist across the org — the agent (or its operator prompt) must know the
-  resource + tag. Stays out until the evals demand it.
+- **No resource discovery.** `list_workflow_tags` enumerates the workflow
+  environments inside one resource, but nothing enumerates the resources
+  themselves — the agent (or its operator prompt) must arrive holding a
+  resource GDR. Cross-resource and org-wide enumeration stays out until
+  the evals demand it.
 - **No `set_stage` tool.** Admin override; intentionally omitted from
   the LLM surface until we have an eval case that needs it (and a
   story for the actor identity that would authorise the override).