@sanity/workflow-mcp 0.25.0 → 0.27.0

package/dist/index.d.ts

@@ -1,7 +1,8 @@
 import type { ActionParam } from "@sanity/workflow-engine";
 import type { AutonomyVerdict } from "@sanity/workflow-engine";
+import { DeclaredExecutionContext } from "@sanity/workflow-engine";
 import type { Diagnosis } from "@sanity/workflow-engine";
-import type { Engine } from "@sanity/workflow-engine";
+import { Engine } from "@sanity/workflow-engine";
 import type { ExecutorClassification } from "@sanity/workflow-engine";
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import type { RequestHandlerExtra } from "@modelcontextprotocol/sdk/shared/protocol.js";
@@ -12,10 +13,24 @@ import type { StuckCause } from "@sanity/workflow-engine";
 import type { SuggestedRemediation } from "@sanity/workflow-engine";
 import type { TelemetryLogger } from "@sanity/telemetry";
 import type { ToolAnnotations } from "@modelcontextprotocol/sdk/types.js";
+import { WorkflowClient } from "@sanity/workflow-engine";
 import type { WorkflowDefinition } from "@sanity/workflow-engine";
 import { WorkflowResource } from "@sanity/workflow-engine";
+import { WorkflowTelemetryLogger } from "@sanity/workflow-engine";
 import { ZodRawShape } from "zod/v3";
 
+/**
+ * An engine bound to one workflow environment. `executionContext` is the host's
+ * declaration of the advisory "via what" stamped on history entries; identity is
+ * whatever token backs the supplied client.
+ */
+export declare function createWorkflowEngine(args: {
+  address: WorkflowEnvironmentAddress;
+  client: WorkflowClient;
+  executionContext?: DeclaredExecutionContext;
+  telemetry?: WorkflowTelemetryLogger;
+}): Engine;
+
 export declare const deployWorkflowDefinitionTool: WorkflowToolDef;
 
 export declare const diagnoseWorkflowTool: WorkflowToolDef;
@@ -56,7 +71,7 @@ export declare const LIST_WORKFLOW_TAGS_DESCRIPTION: string;
  * registration site because the address vocabulary refers to it in prose a model
  * reads — a rename must not leave that prose naming a tool nobody registers.
  */
-export declare const LIST_WORKFLOW_TAGS_TOOL_NAME = "list_workflow_tags";
+export declare const LIST_WORKFLOW_TAGS_TOOL_NAME = "workflows_list_tags";
 
 export declare const listWorkflowDefinitionsTool: WorkflowToolDef;
 
@@ -70,7 +85,7 @@ export declare const listWorkflowInstancesTool: WorkflowToolDef;
  * {@link ProjectedAutomation} instead — the engine fires it, no caller can.
  */
 export declare interface ProjectedActionVerdict {
-  /** Action name — what to pass to `fire_workflow_action` as `action`. */
+  /** Action name — what to pass to `workflows_fire_action` as `action`. */
   action: string;
   /** Human label for the action, if the definition provides one. */
   title?: string;
@@ -78,14 +93,14 @@ export declare interface ProjectedActionVerdict {
   allowed: boolean;
   /** When `allowed` is false, a short reason describing why. */
   disabledReason?: string;
-  /** The action's declared params — what `fire_workflow_action`'s `params` object must
+  /** The action's declared params — what `workflows_fire_action`'s `params` object must
    *  satisfy (each entry names the param and whether it is required). Absent
    *  when the action declares none. */
   params?: ActionParam[];
 }
 
 export declare interface ProjectedActivity {
-  /** Activity name — what to pass to `fire_workflow_action` as `activity`. */
+  /** Activity name — what to pass to `workflows_fire_action` as `activity`. */
   activity: string;
   /** Human label, if provided. */
   title?: string;
@@ -126,10 +141,10 @@ export declare interface ProjectedActivity {
 /**
  * One cascade-fired (`when`) action, narrated as automation: the engine fires
  * it on its own the moment the trigger holds — it is never invocable via
- * `fire_workflow_action`, so it must not read as a button.
+ * `workflows_fire_action`, so it must not read as a button.
  */
 export declare interface ProjectedAutomation {
-  /** The cascade-fired action's name. Not accepted by `fire_workflow_action`. */
+  /** The cascade-fired action's name. Not accepted by `workflows_fire_action`. */
   action: string;
   /** Human label, if provided. */
   title?: string;
@@ -142,12 +157,12 @@ export declare interface ProjectedAutomation {
 }
 
 /**
- * Result of `get_workflow_definition` — one deployed version's content.
+ * Result of `workflows_get_definition` — one deployed version's content.
  * `definition` is the stored (desugared) form with the document envelope
  * stripped — valid input for the validate/deploy tools as-is (their parse
  * accepts stored form; parts of it, e.g. resolved guard `idRefs`, are NOT
  * valid authoring shape): modify it and redeploy via
- * `deploy_workflow_definition` to mint the next version.
+ * `workflows_deploy_definition` to mint the next version.
  */
 export declare interface ProjectedDefinition {
   /** Definition `name`. */
@@ -160,12 +175,12 @@ export declare interface ProjectedDefinition {
 
 /**
  * One deployed workflow definition, latest version only — what
- * `list_workflow_definitions` returns per name. Deploys are create-only
+ * `workflows_list_definitions` returns per name. Deploys are create-only
  * (every deploy mints a new version), but the LLM only ever needs the
  * head: it's the version `startInstance` picks by default.
  */
 export declare interface ProjectedDefinitionSummary {
-  /** Definition `name` — the value `list_workflow_instances` filters on. */
+  /** Definition `name` — the value `workflows_list_instances` filters on. */
   name: string;
   /** Human-readable workflow title. */
   title: string;
@@ -189,7 +204,7 @@ export declare interface ProjectedDefinitionSummary {
  * LLM-friendly, so `remediations` passes through verbatim rather than
  * being re-projected. The verbose `WorkflowEvaluation` the engine returns
  * alongside the diagnosis is dropped — per-activity action detail belongs to
- * {@link ProjectedInstanceState} (get_workflow_state), not here.
+ * {@link ProjectedInstanceState} (workflows_get_state), not here.
  */
 export declare interface ProjectedDiagnosis {
   /** Sanity document id of the diagnosed workflow.instance. */
@@ -344,7 +359,7 @@ export declare type ValidateDefinitionResult =
     };
 
 /**
- * Result of `validate_workflow_definition`. `results` pairs positionally with
+ * Result of `workflows_validate_definition`. `results` pairs positionally with
  * the input `definitions`; `valid` is true only when every definition passed.
  */
 export declare interface ValidateDefinitionsResult {
@@ -354,6 +369,14 @@ export declare interface ValidateDefinitionsResult {
 
 export declare const validateWorkflowDefinitionTool: WorkflowToolDef;
 
+/**
+ * What the model is told about the `tag` parameter itself. Lives here beside the
+ * tool name it cites because every host declares this parameter in its own
+ * vocabulary — a host that paraphrases weakens a caveat that was tuned
+ * deliberately, and nothing warns you it has drifted.
+ */
+export declare const WORKFLOW_TAG_DESCRIPTION: string;
+
 export declare const WORKFLOW_TOOLS: readonly WorkflowToolDef[];
 
 /**
@@ -366,12 +389,64 @@ export declare function workflowAddressFromInput(
   input: unknown,
 ): WorkflowEnvironmentAddress;
 
+/**
+ * The client configuration engine traffic requires, layered over whatever base
+ * config the host supplies — its requester, its headers, its `apiHost`. Engine
+ * policy deliberately wins over that base: a host's own defaults are tuned for
+ * content reads, not for the engine's documents.
+ *
+ * The base is generic rather than `@sanity/client`'s `ClientConfig` so that a
+ * host resolving a different copy of that package still type-checks — the same
+ * reason the engine states its client structurally. The host's own config type
+ * flows through to the result, which stays assignable to it.
+ */
+export declare function workflowClientConfig<Base extends object>(args: {
+  resource: WorkflowResource;
+  token?: string;
+  /** The host's own client config. Pass `{}` if it has no opinions to preserve. */
+  base: Base;
+}): Base & WorkflowClientPolicy & WorkflowResourceAddressing;
+
+/**
+ * The client settings engine traffic pins, whatever base a host layers them over.
+ * Literal types so the result stays assignable to a host's own client config.
+ */
+declare interface WorkflowClientPolicy {
+  apiVersion: string;
+  useCdn: false;
+  requestTagPrefix: string;
+  perspective: "published";
+}
+
 /** Where one tool call reads/writes workflow data: resource + tag. */
 export declare interface WorkflowEnvironmentAddress {
   workflowResource: WorkflowResource;
   tag: string;
 }
 
+/**
+ * One rendering of a failed tool call, shared by every host. A structured
+ * error's stable `kind` leads the text so the model can branch on the failure
+ * without parsing the human-readable message — a host that re-derives this
+ * prefix drifts from the wording the descriptions and evals were tuned against.
+ */
+export declare function workflowErrorText(error: unknown): string;
+
+/**
+ * How the resulting config names the environment. Exactly one branch is
+ * populated — a dataset target carries the classic pair, anything else carries
+ * the resource — but both are stated optional so the result assigns to a host's
+ * client config without narrowing the union first. The unused branch is removed
+ * from the result so a leftover from the host's base cannot survive the merge:
+ * `@sanity/client` prefers `resource` over `projectId`/`dataset` whenever both
+ * are present, which would otherwise silently address the wrong environment.
+ */
+declare interface WorkflowResourceAddressing {
+  projectId?: string;
+  dataset?: string;
+  resource?: WorkflowResource;
+}
+
 /**
  * Everything a tool call needs from its host: the engine to operate on.
  * Identity is the token behind the engine's client (`/users/me`) — a host

package/dist/index.js

@@ -1,3 +1,3 @@
-import { LIST_WORKFLOW_TAGS_DESCRIPTION, LIST_WORKFLOW_TAGS_TOOL_NAME, WORKFLOW_TOOLS, deployWorkflowDefinitionTool, diagnoseWorkflowTool, fireActionTool, getWorkflowAuthoringGuideTool, getWorkflowDefinitionTool, getWorkflowStateTool, listWorkflowDefinitionsTool, listWorkflowInstancesTool, registerWorkflowTools, startWorkflowTool, toolInputJsonSchema, validateWorkflowDefinitionTool, workflowAddressFromInput } from "./_chunks-es/index.js";
+import { LIST_WORKFLOW_TAGS_DESCRIPTION, LIST_WORKFLOW_TAGS_TOOL_NAME, WORKFLOW_TAG_DESCRIPTION, WORKFLOW_TOOLS, createWorkflowEngine, deployWorkflowDefinitionTool, diagnoseWorkflowTool, fireActionTool, getWorkflowAuthoringGuideTool, getWorkflowDefinitionTool, getWorkflowStateTool, listWorkflowDefinitionsTool, listWorkflowInstancesTool, registerWorkflowTools, startWorkflowTool, toolInputJsonSchema, validateWorkflowDefinitionTool, workflowAddressFromInput, workflowClientConfig, workflowErrorText } from "./_chunks-es/index.js";
 
-export { LIST_WORKFLOW_TAGS_DESCRIPTION, LIST_WORKFLOW_TAGS_TOOL_NAME, WORKFLOW_TOOLS, deployWorkflowDefinitionTool, diagnoseWorkflowTool, fireActionTool, getWorkflowAuthoringGuideTool, getWorkflowDefinitionTool, getWorkflowStateTool, listWorkflowDefinitionsTool, listWorkflowInstancesTool, registerWorkflowTools, startWorkflowTool, toolInputJsonSchema, validateWorkflowDefinitionTool, workflowAddressFromInput };
+export { LIST_WORKFLOW_TAGS_DESCRIPTION, LIST_WORKFLOW_TAGS_TOOL_NAME, WORKFLOW_TAG_DESCRIPTION, WORKFLOW_TOOLS, createWorkflowEngine, deployWorkflowDefinitionTool, diagnoseWorkflowTool, fireActionTool, getWorkflowAuthoringGuideTool, getWorkflowDefinitionTool, getWorkflowStateTool, listWorkflowDefinitionsTool, listWorkflowInstancesTool, registerWorkflowTools, startWorkflowTool, toolInputJsonSchema, validateWorkflowDefinitionTool, workflowAddressFromInput, workflowClientConfig, workflowErrorText };

package/dist/stdio.js

@@ -2,52 +2,14 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 
-import { ENGINE_API_VERSION, clientConfigFromResource, resourceGdr, createEngine, deployedTagsGroq, parseResourceGdr, datasetResourceParts, EXECUTION_KINDS } from "@sanity/workflow-engine";
+import { deployedTagsGroq, parseResourceGdr, datasetResourceParts, EXECUTION_KINDS } from "@sanity/workflow-engine";
 
-import { LIST_WORKFLOW_TAGS_TOOL_NAME, workflowAddressFields, LIST_WORKFLOW_TAGS_DESCRIPTION, withToolTelemetry, registerWorkflowTools, workflowAddressFromInput, createMcpTelemetry } from "./_chunks-es/index.js";
+import { LIST_WORKFLOW_TAGS_TOOL_NAME, workflowAddressFields, LIST_WORKFLOW_TAGS_DESCRIPTION, withToolTelemetry, clientForResource, registerWorkflowTools, workflowAddressFromInput, createMcpTelemetry, createEngineCache } from "./_chunks-es/index.js";
 
-import { createClient } from "@sanity/client";
-
-var version = "0.25.0", packageJson = {
+var version = "0.27.0", packageJson = {
     version: version
 };
 
-function clientForResource(args) {
-    const {resource: resource, token: token, apiHost: apiHost} = args;
-    return createClient({
-        token: token,
-        apiHost: apiHost,
-        apiVersion: ENGINE_API_VERSION,
-        useCdn: !1,
-        requestTagPrefix: "sanity.workflows-mcp",
-        ...clientConfigFromResource(resource)
-    });
-}
-
-function createEngineCache({token: token, apiHost: apiHost, executionContext: executionContext, telemetry: telemetry}) {
-    const engines = /* @__PURE__ */ new Map;
-    return ({workflowResource: workflowResource, tag: tag}) => {
-        const key = `${resourceGdr(workflowResource)} ${tag}`, existing = engines.get(key);
-        if (existing !== void 0) return existing;
-        const engine = createEngine({
-            client: clientForResource({
-                resource: workflowResource,
-                token: token,
-                apiHost: apiHost
-            }),
-            workflowResource: workflowResource,
-            tag: tag,
-            ...executionContext !== void 0 ? {
-                executionContext: executionContext
-            } : {},
-            ...telemetry !== void 0 ? {
-                telemetry: telemetry
-            } : {}
-        });
-        return engines.set(key, engine), engine;
-    };
-}
-
 function requireEnv(env, name) {
     const value = env[name];
     if (typeof value != "string" || value === "") throw new Error(`Missing required environment variable: ${name}`);

package/package.json

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