@sanity/workflow-mcp 0.5.1 → 0.7.0

package/README.md

@@ -11,23 +11,30 @@ the tools the evals drive, plus a stdio MCP entry point for real MCP clients.
 
 Operate a running instance:
 
-| Tool                      | Read or write | What it's for                                                                                                                             |
-| ------------------------- | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
-| `list_workflow_instances` | read          | Discover what's running. Filterable, capped.                                                                                              |
-| `get_workflow_state`      | read          | Project one instance into a flat shape: current stage, activities, available actions, recent history.                                     |
-| `diagnose_workflow`       | read          | Explain why an instance is or isn't progressing: a verdict, a one-line summary, and — when stuck — the cause plus suggested remediations. |
-| `fire_action`             | write         | Advance state. The only write. Mirrors the engine's universal "something happened" entry point.                                           |
-
-Author a definition (both pure, engine-independent, neither deploys):
-
-| Tool                           | Read or write | What it's for                                                                                                                                     |
-| ------------------------------ | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `get_workflow_authoring_guide` | read          | Return the DSL guide an agent reads before authoring — shape, GROQ built-ins, sugars, modeling defaults, and two worked JSON examples.            |
-| `validate_workflow_definition` | read          | Check an authored definition the way deploy does (structure + invariants + GROQ). Returns the desugared definition or a path-prefixed error list. |
-
-Each descriptor's `description` field is written for an LLM consumer
-— it says what the tool does, when to use it, and what _not_ to use
-it for. See `src/tools.ts`.
+| Tool                        | Read or write | What it's for                                                                                                                                                                                                                                    |
+| --------------------------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `list_workflow_definitions` | read          | The catalogue: which workflow types are deployed (latest version each), and whether they're startable.                                                                                                                                           |
+| `get_workflow_definition`   | read          | Read one deployed definition's content, envelope-stripped — redeployable as-is, so an agent can iterate on a deployed workflow (deploys are create-only).                                                                                        |
+| `list_workflow_instances`   | read          | Discover what's running. Filterable (`definition`, `document`, `include_completed` — in-flight by default), capped.                                                                                                                              |
+| `get_workflow_state`        | read          | Project one instance into a flat shape: current stage, activities, available actions (with each action's declared params), recent history.                                                                                                       |
+| `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.                                                                                                                                              |
+
+Author a definition (guide → validate → deploy; the first two are pure and
+engine-independent):
+
+| Tool                           | Read or write | What it's for                                                                                                                                                                                                                                                         |
+| ------------------------------ | ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `get_workflow_authoring_guide` | read          | Return the DSL guide an agent reads before authoring — shape, GROQ built-ins, sugars, modeling defaults, and two worked JSON examples.                                                                                                                                |
+| `validate_workflow_definition` | read          | Check authored definitions (a `definitions` batch) the way deploy does (structure + invariants + GROQ). Returns `{valid, results}` — per definition, the desugared form or a path-prefixed error list.                                                                |
+| `deploy_workflow_definition`   | write         | Publish validated definitions into an addressed environment — one `definitions` batch per call (children deploy before the parents that spawn them). Create-only and content-addressed: identical content is an `unchanged` no-op, any change mints the next version. |
+
+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
+schema, annotations, handler together); `src/tools.ts` assembles them
+into the exported `WORKFLOW_TOOLS` surface.
 
 ## Why this surface, why no more
 
@@ -36,9 +43,17 @@ the verbs. An MCP is consumed by an LLM that figures out which tool
 to use from prose alone. Adding tools beyond the minimum increases
 the search space the LLM has to navigate. We stay narrow until the
 evals tell us the LLM is reaching for something we don't expose. The
-authoring pair earns its place because authoring-from-a-description is
-eval-backed; the agent generates the definition and self-corrects against
-`validate_workflow_definition` (deploy stays a deliberate human step).
+authoring trio earns its place because authoring-from-a-description is
+eval-backed; the agent generates the definitions, self-corrects against
+`validate_workflow_definition`, then publishes with
+`deploy_workflow_definition` — safe to hand an agent because deploy is
+create-only: it can never patch or clobber what's already deployed, and
+running instances keep the definition version they started under.
+`get_workflow_definition` closes the loop that create-only would
+otherwise leave open — iterating on a deployed workflow means reading
+it back, modifying, and deploying the next version — and
+`start_workflow` is the lifecycle entry point the catalogue's
+`startable` flag advertises.
 
 ## Run the stdio server
 
@@ -56,44 +71,98 @@ it's `bin/run.js`, and once the package is published this is what
 node packages/workflow-mcp/bin/run.js
 ```
 
-Both share the one boot path in `src/stdio.ts`, which reads its
-configuration from the environment: `SANITY_PROJECT_ID`, `SANITY_DATASET`,
-`SANITY_AUTH_TOKEN`, and `WORKFLOW_TAG` are required; `SANITY_API_HOST`,
-`WORKFLOW_RESOURCE_TYPE`, and `WORKFLOW_RESOURCE_ID` are optional. The `dev`
-script loads them from the repo-root `.env`, so copy `.env.example` to `.env`
-to get started. (The CLI has since moved to a `sanity.workflow.ts` config; the
-MCP still takes plain env vars.)
+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,
+`<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.
+
+### Telemetry
+
+The stdio server reports adoption telemetry to Sanity: one
+`Editorial Workflows MCP Tool Called` event per tool invocation carrying the
+tool name and a success
+flag — never tool arguments or results — plus 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
+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.
 
 ## API
 
+The package is a host-neutral library: it never builds an engine, reads
+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
+`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:
+
 ```ts
-import {createEngine} from '@sanity/workflow-engine'
-import {buildTools} from '@sanity/workflow-mcp'
+import {McpServer} from '@modelcontextprotocol/sdk/server/mcp.js'
+import {createEngine, resourceGdr, type Engine} from '@sanity/workflow-engine'
+import {registerWorkflowTools, workflowAddressFromInput} from '@sanity/workflow-mcp'
+
+const server = new McpServer({name: 'my-host', version: '1.0.0'})
+
+// One engine per addressed environment, reused across calls.
+// clientFor(resource): your host's @sanity/client for that resource —
+// the bundled stdio host's version lives in `src/engine-cache.ts`.
+const engines = new Map<string, Engine>()
+
+registerWorkflowTools(server, (_extra, input) => {
+  const {workflowResource, tag} = workflowAddressFromInput(input)
+  const key = `${resourceGdr(workflowResource)} ${tag}`
+  const engine =
+    engines.get(key) ?? createEngine({client: clientFor(workflowResource), workflowResource, tag})
+  engines.set(key, engine)
+  return {engine}
+})
+```
+
+Hosts with their own wrappers (error handling, telemetry, response
+envelopes) iterate the raw defs instead — and non-MCP consumers derive
+the JSON-schema descriptor from each def's zod shape:
 
-const engine = createEngine({client, workflowResource, tag})
-const {descriptors, impls} = buildTools(engine)
+```ts
+import {toolInputJsonSchema, WORKFLOW_TOOLS} from '@sanity/workflow-mcp'
 
-// descriptors → feed to Anthropic API's `tools:` param, or to an MCP
-//   `tools/list` handler.
-// impls       → call from a `tools/call` handler, or from the eval
-//   harness directly (in-process, no transport).
+for (const def of WORKFLOW_TOOLS) {
+  // def.name, def.description, def.inputSchema (zod), def.annotations
+  // 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.
+
 ## 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 `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).
-- **No `start_instance` tool.** Starting an instance is an operator
-  action that needs context the LLM doesn't have (subject doc ref,
-  initial field values); operators start instances with the workflow
-  CLI's `start` command.
-- **No effect completion.** Same logic — effects are queued by the
-  engine and drained by the runtime, not by a human or LLM.
+- **No effect completion.** Effects are queued by the engine and
+  drained by the runtime, not by a human or LLM.
 - **No subscription / streaming.** MCP supports it; we haven't needed
   it yet. Pull-based polling via `get_workflow_state` covers the eval
   cases.
-- **No `deploy_workflow_definition`.** `validate_workflow_definition` is
-  the authoring tool; a human deploys the validated definition via the
-  CLI. Deploy is a Content Lake write that inherits the actor-identity
-  story, so it stays out of the LLM surface for now.

package/bin/run.js

@@ -1,9 +1,4 @@
 #!/usr/bin/env node
-// Production entry for the published package: loads the compiled boot
-// path from ./dist/stdio.js (built by pkg-utils via the `./stdio`
-// export). The dev counterpart, bin/workflow-mcp.ts, loads the TS
-// source through tsx instead.
-
 import {runStdioServer} from '../dist/stdio.js'
 
 await runStdioServer()