@sanity/workflow-mcp 0.24.0 → 0.25.0

package/dist/index.d.ts

@@ -7,13 +7,26 @@ import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import type { RequestHandlerExtra } from "@modelcontextprotocol/sdk/shared/protocol.js";
 import type { ServerNotification } from "@modelcontextprotocol/sdk/types.js";
 import type { ServerRequest } from "@modelcontextprotocol/sdk/types.js";
+import type { StartKind } from "@sanity/workflow-engine";
 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 type { WorkflowDefinition } from "@sanity/workflow-engine";
 import { WorkflowResource } from "@sanity/workflow-engine";
-import { ZodRawShape } from "zod";
+import { ZodRawShape } from "zod/v3";
+
+export declare const deployWorkflowDefinitionTool: WorkflowToolDef;
+
+export declare const diagnoseWorkflowTool: WorkflowToolDef;
+
+export declare const fireActionTool: WorkflowToolDef;
+
+export declare const getWorkflowAuthoringGuideTool: WorkflowToolDef;
+
+export declare const getWorkflowDefinitionTool: WorkflowToolDef;
+
+export declare const getWorkflowStateTool: WorkflowToolDef;
 
 /**
  * The host seam: produce the {@link WorkflowToolContext} for one tool
@@ -30,6 +43,25 @@ export declare type GetWorkflowToolContext = (
   input: unknown,
 ) => WorkflowToolContext | Promise<WorkflowToolContext>;
 
+/**
+ * The model-facing description of the tag-discovery capability. Hosts can't
+ * share the implementation — each owns its client and its resource spelling —
+ * so what the model is told about the answer lives here instead: what the list
+ * means, and that finding a tag is not the same as being allowed to choose one.
+ */
+export declare const LIST_WORKFLOW_TAGS_DESCRIPTION: string;
+
+/**
+ * The wire name of the tag-discovery tool. Declared here rather than at the
+ * 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 listWorkflowDefinitionsTool: WorkflowToolDef;
+
+export declare const listWorkflowInstancesTool: WorkflowToolDef;
+
 /**
  * One invocable (fireAction-fired) action. Two whole classes of action never
  * appear here: an action whose `filter` scoped it out for this actor is
@@ -38,7 +70,7 @@ export declare type GetWorkflowToolContext = (
  * {@link ProjectedAutomation} instead — the engine fires it, no caller can.
  */
 export declare interface ProjectedActionVerdict {
-  /** Action name — what to pass to `fire_action` as `action`. */
+  /** Action name — what to pass to `fire_workflow_action` as `action`. */
   action: string;
   /** Human label for the action, if the definition provides one. */
   title?: string;
@@ -46,14 +78,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_action`'s `params` object must
+  /** The action's declared params — what `fire_workflow_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_action` as `activity`. */
+  /** Activity name — what to pass to `fire_workflow_action` as `activity`. */
   activity: string;
   /** Human label, if provided. */
   title?: string;
@@ -94,10 +126,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_action`, so it must not read as a button.
+ * `fire_workflow_action`, so it must not read as a button.
  */
 export declare interface ProjectedAutomation {
-  /** The cascade-fired action's name. Not accepted by `fire_action`. */
+  /** The cascade-fired action's name. Not accepted by `fire_workflow_action`. */
   action: string;
   /** Human label, if provided. */
   title?: string;
@@ -126,6 +158,30 @@ export declare interface ProjectedDefinition {
   definition: WorkflowDefinition;
 }
 
+/**
+ * One deployed workflow definition, latest version only — what
+ * `list_workflow_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. */
+  name: string;
+  /** Human-readable workflow title. */
+  title: string;
+  /** Author-supplied description, when the definition carries one. */
+  description?: string;
+  /** Latest deployed version. */
+  version: number;
+  /** Whether new instances can be started directly. `false` for spawn-only
+   *  child workflows — those only come to exist under a parent instance. */
+  startable: boolean;
+  /** Who initiates standalone runs: `'interactive'` (a person, from a start
+   *  surface) or `'autonomous'` (a system reacting to a document).
+   *  Classification only — the engine starts either kind for any caller. */
+  startKind: StartKind;
+}
+
 /**
  * The diagnosis projection — why an instance is or isn't progressing.
  *
@@ -242,6 +298,8 @@ export declare function registerWorkflowTools(
   },
 ): void;
 
+export declare const startWorkflowTool: WorkflowToolDef;
+
 /**
  * JSON-schema descriptor for consumers that don't speak zod — e.g. the
  * Anthropic Messages API `input_schema` field. `properties`/`required`
@@ -255,7 +313,16 @@ export declare interface ToolInputJsonSchema {
   [key: string]: unknown;
 }
 
-/** Derive the JSON-schema descriptor from a def's zod shape. */
+/**
+ * Derive the JSON-schema descriptor from a def's own zod shape. The converter
+ * options mirror the ones the MCP SDK derives its wire schema with, so one
+ * shape can't derive two ways.
+ *
+ * A def's own shape is not the whole advertised input: a consumer of a def
+ * declaring {@link WorkflowToolDef.requiresAddress} merges its own workflow
+ * environment parameters in, the way {@link registerWorkflowTools} does for
+ * this package's host.
+ */
 export declare function toolInputJsonSchema(
   def: WorkflowToolDef,
 ): ToolInputJsonSchema;
@@ -285,6 +352,8 @@ export declare interface ValidateDefinitionsResult {
   results: ValidateDefinitionResult[];
 }
 
+export declare const validateWorkflowDefinitionTool: WorkflowToolDef;
+
 export declare const WORKFLOW_TOOLS: readonly WorkflowToolDef[];
 
 /**
@@ -339,6 +408,15 @@ export declare interface WorkflowToolDef {
    * descriptor for non-MCP consumers.
    */
   readonly inputSchema: ZodRawShape;
+  /**
+   * Whether this tool operates on a workflow environment, and so needs the
+   * engine it is handed to address the one the caller means. How a host
+   * satisfies that is its own choice: one that names an environment per call
+   * adds its own address parameters to this tool's schema, one that binds a
+   * single environment when it builds the engine adds nothing. `false` marks
+   * an engine-independent tool — there is no environment to name.
+   */
+  readonly requiresAddress: boolean;
   readonly annotations: ToolAnnotations;
   /**
    * Returns plain projected data (the `Projected*` shapes) — hosts own

package/dist/index.js

@@ -1,3 +1,3 @@
-import { WORKFLOW_TOOLS, registerWorkflowTools, toolInputJsonSchema, workflowAddressFromInput } from "./_chunks-es/index.js";
+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";
 
-export { WORKFLOW_TOOLS, registerWorkflowTools, toolInputJsonSchema, workflowAddressFromInput };
+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 };

package/dist/stdio.js

@@ -2,13 +2,13 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 
-import { ENGINE_API_VERSION, clientConfigFromResource, resourceGdr, createEngine, datasetResourceParts, EXECUTION_KINDS } from "@sanity/workflow-engine";
+import { ENGINE_API_VERSION, clientConfigFromResource, resourceGdr, createEngine, deployedTagsGroq, parseResourceGdr, datasetResourceParts, EXECUTION_KINDS } from "@sanity/workflow-engine";
 
-import { registerWorkflowTools, workflowAddressFromInput, createMcpTelemetry } from "./_chunks-es/index.js";
+import { LIST_WORKFLOW_TAGS_TOOL_NAME, workflowAddressFields, LIST_WORKFLOW_TAGS_DESCRIPTION, withToolTelemetry, registerWorkflowTools, workflowAddressFromInput, createMcpTelemetry } from "./_chunks-es/index.js";
 
 import { createClient } from "@sanity/client";
 
-var version = "0.24.0", packageJson = {
+var version = "0.25.0", packageJson = {
     version: version
 };
 
@@ -54,6 +54,41 @@ function requireEnv(env, name) {
     return value;
 }
 
+const readDeployedTags = ({resource: resource, token: token, apiHost: apiHost}) => clientForResource({
+    resource: resource,
+    token: token,
+    apiHost: apiHost
+}).fetch(deployedTagsGroq(), {}, {
+    tag: "definition.tags"
+});
+
+function registerListWorkflowTagsTool(server, {token: token, apiHost: apiHost, readTags: readTags = readDeployedTags, telemetry: telemetry, onResource: onResource}) {
+    server.registerTool(LIST_WORKFLOW_TAGS_TOOL_NAME, {
+        description: LIST_WORKFLOW_TAGS_DESCRIPTION,
+        inputSchema: {
+            workflow_resource: workflowAddressFields.workflow_resource
+        },
+        annotations: {
+            readOnlyHint: !0
+        }
+    }, args => withToolTelemetry({
+        tool: LIST_WORKFLOW_TAGS_TOOL_NAME,
+        input: args,
+        ...telemetry !== void 0 ? {
+            telemetry: telemetry
+        } : {}
+    }, async () => {
+        const resource = parseResourceGdr(args.workflow_resource);
+        return onResource?.(resource), {
+            tags: await readTags({
+                resource: resource,
+                token: token,
+                apiHost: apiHost
+            })
+        };
+    }));
+}
+
 async function runStdioServer() {
     const token = requireEnv(process.env, "SANITY_AUTH_TOKEN"), apiHost = process.env.SANITY_API_HOST ?? "https://api.sanity.io";
     process.stderr.write(`workflow-mcp MCP starting against ${apiHost} (org-authed; workflow environments are addressed per tool call)\n`);
@@ -66,12 +101,12 @@ async function runStdioServer() {
             if (telemetry === void 0) throw new Error("workflow-mcp: telemetry trace before any environment was addressed");
             return telemetry.logger.trace(event, context);
         }
-    }, initTelemetry = address => {
-        if (telemetry !== void 0 || address.workflowResource.type !== "dataset") return;
-        const {projectId: projectId, dataset: dataset} = datasetResourceParts(address.workflowResource.id);
+    }, initTelemetry = resource => {
+        if (telemetry !== void 0 || resource.type !== "dataset") return;
+        const {projectId: projectId, dataset: dataset} = datasetResourceParts(resource.id);
         telemetry = createMcpTelemetry({
             client: clientForResource({
-                resource: address.workflowResource,
+                resource: resource,
                 token: token,
                 apiHost: apiHost
             }),
@@ -94,11 +129,16 @@ async function runStdioServer() {
     });
     registerWorkflowTools(server, (_extra, input) => {
         const address = workflowAddressFromInput(input);
-        return initTelemetry(address), {
+        return initTelemetry(address.workflowResource), {
             engine: engineFor(address)
         };
     }, {
         telemetry: logger
+    }), registerListWorkflowTagsTool(server, {
+        token: token,
+        apiHost: apiHost,
+        telemetry: logger,
+        onResource: initTelemetry
     });
     const FLUSH_DEADLINE_MS = 3e3;
     let shuttingDown = !1;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sanity/workflow-mcp",
-  "version": "0.24.0",
+  "version": "0.25.0",
   "description": "MCP server exposing Sanity workflow tools to agents — operate running workflow instances and author new definitions.",
   "keywords": [
     "agent",
@@ -52,21 +52,24 @@
     "access": "public"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.29.0",
     "@sanity/client": "^7.22.1",
     "@sanity/telemetry": "^1.1.0",
-    "zod": "^4.4.3"
+    "zod-to-json-schema": "^3.25.2"
   },
   "devDependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
     "@sanity/pkg-utils": "^10.5.2",
     "@types/node": "^24.12.4",
     "vitest": "^4.1.8",
-    "@sanity/workflow-engine": "0.24.0",
-    "@sanity/workflow-engine-test": "0.24.0",
-    "@sanity/workflow-examples": "0.10.3"
+    "zod": "^4.4.3",
+    "@sanity/workflow-engine": "0.25.0",
+    "@sanity/workflow-engine-test": "0.25.0",
+    "@sanity/workflow-examples": "0.10.4"
   },
   "peerDependencies": {
-    "@sanity/workflow-engine": "0.24.0"
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "zod": "^3.25.28 || ^4",
+    "@sanity/workflow-engine": "0.25.0"
   },
   "engines": {
     "node": ">=20"