@sanity/workflow-mcp 0.5.1 → 0.7.0

package/dist/index.d.cts

@@ -1,43 +1,41 @@
+import type { ActionParam } from "@sanity/workflow-engine";
 import type { Diagnosis } from "@sanity/workflow-engine";
-import { Engine } from "@sanity/workflow-engine";
+import type { 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";
+import type { ServerNotification } from "@modelcontextprotocol/sdk/types.js";
+import type { ServerRequest } from "@modelcontextprotocol/sdk/types.js";
 import type { StuckCause } from "@sanity/workflow-engine";
 import type { SuggestedRemediation } from "@sanity/workflow-engine";
-import { WorkflowAccessOverride } 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";
 
 /**
- * Build the MCP tool descriptors and bound implementations against a
- * single engine. Pass the engine the tools should operate on; the
- * returned descriptors are static (safe to cache), the implementations
- * close over the engine.
- *
- * In production this is called once at server boot. In tests it's
- * called per-bench so each eval case has an isolated engine.
+ * The host seam: produce the {@link WorkflowToolContext} for one tool
+ * call. `extra` carries the request (a hosted server derives auth from
+ * it); `input` carries the parsed tool arguments — for the
+ * instance-operating tools that includes the per-call workflow
+ * environment address, which `workflowAddressFromInput` extracts so the
+ * host can build (or reuse) the engine for that environment. The
+ * authoring tools never invoke their context thunk, so this is never
+ * called without an address to read.
  */
-export declare function buildTools(
-  engine: Engine,
-  options?: BuildToolsOptions,
-): BuiltTools;
+export declare type GetWorkflowToolContext = (
+  extra: WorkflowToolExtra,
+  input: unknown,
+) => WorkflowToolContext | Promise<WorkflowToolContext>;
 
 /**
- * Optional knobs for `buildTools`.
- *
- * `access` — override the engine's actor + grants resolution for every
- * call the tools make. In production, leave this unset: the engine
- * resolves the actor from the supplied client's token via `/users/me`.
- * In tests, pass `ALL_ACCESS` (from `@sanity/workflow-engine-test`)
- * because the TestClient has no token and would otherwise throw on
- * the resolution path.
+ * One invocable (fireAction-fired) action. Two whole classes of action never
+ * appear here: an action whose `filter` scoped it out for this actor is
+ * ABSENT (filter is existence — it might as well not exist, never "disabled"),
+ * and a cascade-fired (`when`) action is projected as a
+ * {@link ProjectedAutomation} instead — the engine fires it, no caller can.
  */
-export declare interface BuildToolsOptions {
-  access?: WorkflowAccessOverride;
-}
-
-export declare interface BuiltTools {
-  descriptors: ToolDescriptor[];
-  impls: Record<string, ToolImpl>;
-}
-
 export declare interface ProjectedActionVerdict {
   /** Action name — what to pass to `fire_action` as `action`. */
   action: string;
@@ -47,6 +45,10 @@ 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
+   *  satisfy (each entry names the param and whether it is required). Absent
+   *  when the action declares none. */
+  params?: ActionParam[];
 }
 
 export declare interface ProjectedActivity {
@@ -56,10 +58,57 @@ export declare interface ProjectedActivity {
   title?: string;
   /** Longer prose description, if provided. */
   description?: string;
-  /** Current activity status. */
-  status: "pending" | "active" | "done" | "skipped" | "failed";
-  /** Available actions on this activity, each with its allowed/disabled verdict. */
+  /** Current activity status. Activities are active from stage entry; an
+   *  activity whose `filter` scoped it out of this visit is absent from the
+   *  projection, so `skipped` here always means an action resolved it so. */
+  status: "active" | "done" | "skipped" | "failed";
+  /**
+   * Who, if anyone, the activity waits on — `interactive` (only invocable
+   * actions), `autonomous` (only cascade-fired automation), `off-system`
+   * (work performed outside the system), or `hybrid` (both kinds).
+   */
+  classification: ExecutorClassification;
+  /** Invocable actions on this activity, each with its allowed/disabled
+   *  verdict. See {@link ProjectedActionVerdict} for what never appears. */
   actions: ProjectedActionVerdict[];
+  /** Cascade-fired actions, narrated as automation ("fires when …").
+   *  Present only when the activity declares any. */
+  automations?: ProjectedAutomation[];
+}
+
+/**
+ * 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.
+ */
+export declare interface ProjectedAutomation {
+  /** The cascade-fired action's name. Not accepted by `fire_action`. */
+  action: string;
+  /** Human label, if provided. */
+  title?: string;
+  /** The trigger — the GROQ condition whose truth makes the engine fire it. */
+  firesWhen: string;
+  /** What still stands between the current state and the trigger, as one
+   *  English line ("Needs: …"). Absent when the trigger is already satisfied
+   *  or already fired this stage visit. */
+  pending?: string;
+}
+
+/**
+ * Result of `get_workflow_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.
+ */
+export declare interface ProjectedDefinition {
+  /** Definition `name`. */
+  name: string;
+  /** The deployed version this content came from. */
+  version: number;
+  /** The envelope-stripped definition content. */
+  definition: WorkflowDefinition;
 }
 
 /**
@@ -80,6 +129,10 @@ export declare interface ProjectedDiagnosis {
   summary: string;
   /** When `state` is "stuck", the structured cause kind. */
   cause?: StuckCause["kind"];
+  /** Per unsatisfied exit transition, its insight summary ("the "Publish"
+   *  transition: Needs: «Legal approved» must be true") — present when any
+   *  exit is currently held. */
+  explanations?: string[];
   /**
    * What would unstick the instance — empty unless stuck. Each names a
    * surface-neutral verb, whether it's runnable as an engine operation today
@@ -92,7 +145,8 @@ export declare interface ProjectedDiagnosis {
 export declare interface ProjectedHistoryEntry {
   /** ISO timestamp. */
   at: string;
-  /** Engine history type (e.g. stageEntered). */
+  /** Human-readable entry title from the engine's display metadata
+   *  (e.g. "Stage entered"). */
   type: string;
   /** Free-form one-line summary suitable for an LLM to read. */
   summary: string;
@@ -162,78 +216,41 @@ export declare interface ProjectedSubject {
 }
 
 /**
- * The MCP tool surface for workflow operations — the static descriptors an
- * agent reads to decide what to call. The implementations live in `tools.ts`;
- * these are pure data (descriptions + JSON schemas) and safe to cache.
- *
- * Two jobs: operate running instances, and author new definitions.
- *
- * Operate an instance:
- *
- * - `list_workflow_instances` is the only way to *discover* what's
- *   running without already knowing an id. Filterable, capped.
- * - `get_workflow_state` is the "tell me everything actionable about
- *   one instance" call. It composes the engine's `evaluate` projection
- *   into a flat shape an LLM can reason over without piecing together
- *   raw `WorkflowInstance` documents.
- * - `diagnose_workflow` answers "*why* isn't this moving?" — it
- *   classifies an instance as healthy (waiting/progressing) or genuinely
- *   stuck (a failed effect/activity, a dead-end transition) and names the
- *   remediations that would unstick it. A pure read; the remediations are
- *   advisory (none execute through this server).
- * - `fire_action` is the only write. Mirrors the engine's universal
- *   "something happened" entry point — everything other than admin
- *   override flows through it.
- *
- * Author a definition (both pure, engine-independent, neither deploys):
- *
- * - `get_workflow_authoring_guide` returns the DSL guide an agent reads
- *   before writing a definition — shape, GROQ built-ins, sugars, examples.
- * - `validate_workflow_definition` runs the deploy-time checks (structure +
- *   invariants + GROQ) and returns the desugared definition or a
- *   path-prefixed error list. A human deploys it via the CLI.
- *
- * Surface choices that matter for an LLM consumer:
- *
- *   - Descriptions are written for an agent, not a human reader.
- *     Each one says (a) what the tool does, (b) when to use it,
- *     (c) what *not* to use it for.
- *   - Parameter names use snake_case, matching MCP convention.
- *   - The write tool's description spells out that this is the way
- *     to advance workflow state — not a side door. Without that line,
- *     an LLM tends to look for a `complete_activity` or `set_stage` tool.
- *   - Read tools cap their output. A 50-page `recent_history` would
- *     burn context and is rarely informative; 8 is enough to spot
- *     loops or stuck-in-stage patterns.
+ * Register every workflow tool onto `server`, wired through `getContext`.
+ * A host that owns a telemetry shell passes its logger to log one
+ * adoption event per tool call; without it, calls log nothing.
  */
+export declare function registerWorkflowTools(
+  server: McpServer,
+  getContext: GetWorkflowToolContext,
+  options?: {
+    telemetry?: TelemetryLogger<unknown>;
+  },
+): void;
+
 /**
- * The descriptor shape the Anthropic Messages API + the MCP SDK both
- * accept. Kept here as a small, transport-neutral interface so we can
- * feed the same descriptors to either consumer.
+ * JSON-schema descriptor for consumers that don't speak zod — e.g. the
+ * Anthropic Messages API `input_schema` field. `properties`/`required`
+ * are declared (not left to the index signature) so the shape is
+ * directly assignable to the Anthropic SDK's `Tool.InputSchema`.
  */
-export declare interface ToolDescriptor {
-  name: string;
-  description: string;
-  /** JSON Schema describing the tool's parameters. */
-  input_schema: {
-    type: "object";
-    properties: Record<string, unknown>;
-    required?: string[];
-    additionalProperties?: boolean;
-  };
+export declare interface ToolInputJsonSchema {
+  type: "object";
+  properties?: Record<string, unknown>;
+  required?: string[];
+  [key: string]: unknown;
 }
 
-/**
- * A tool implementation is a function from validated input → JSON-able
- * output. The runner is responsible for serialising the output and for
- * surfacing thrown errors as `is_error` tool results.
- */
-export declare type ToolImpl = (input: unknown) => Promise<unknown>;
+/** Derive the JSON-schema descriptor from a def's zod shape. */
+export declare function toolInputJsonSchema(
+  def: WorkflowToolDef,
+): ToolInputJsonSchema;
 
 /**
- * Result of `validate_workflow_definition`. On `valid: true`, `definition` is the
- * desugared form that would deploy (defaults filled, sugar expanded); on
- * `valid: false`, `error` is the aggregated, path-prefixed list of problems.
+ * Per-definition result inside {@link ValidateDefinitionsResult}. On
+ * `valid: true`, `definition` is the desugared form that would deploy
+ * (defaults filled, sugar expanded); on `valid: false`, `error` is the
+ * aggregated, path-prefixed list of problems.
  */
 export declare type ValidateDefinitionResult =
   | {
@@ -245,4 +262,87 @@ export declare type ValidateDefinitionResult =
       error: string;
     };
 
+/**
+ * Result of `validate_workflow_definition`. `results` pairs positionally with
+ * the input `definitions`; `valid` is true only when every definition passed.
+ */
+export declare interface ValidateDefinitionsResult {
+  valid: boolean;
+  results: ValidateDefinitionResult[];
+}
+
+export declare const WORKFLOW_TOOLS: readonly WorkflowToolDef[];
+
+/**
+ * Parse the {@link WorkflowEnvironmentAddress} out of a tool call's input —
+ * the host side of the address contract: a host's `getContext` reads the
+ * address from the input this parses and builds (or reuses) the engine for
+ * it. Extra input keys (the tool's other parameters) are ignored.
+ */
+export declare function workflowAddressFromInput(
+  input: unknown,
+): WorkflowEnvironmentAddress;
+
+/** Where one tool call reads/writes workflow data: resource + tag. */
+export declare interface WorkflowEnvironmentAddress {
+  workflowResource: WorkflowResource;
+  tag: string;
+}
+
+/**
+ * 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
+ * that should act as someone else supplies an engine over their token, and
+ * declares itself via the engine's `executionContext`.
+ */
+export declare interface WorkflowToolContext {
+  engine: Engine;
+}
+
+/**
+ * Lazy context supplier. A thunk rather than the context itself so a
+ * host never pays for engine construction on tools that don't call it —
+ * the guide and validate tools teach and check the DSL without touching
+ * the lake, and a per-request host would otherwise build a client for
+ * nothing.
+ */
+export declare type WorkflowToolContextThunk =
+  () => Promise<WorkflowToolContext>;
+
+/**
+ * One workflow tool, host-neutral. Hosts iterate {@link WORKFLOW_TOOLS}
+ * and register each def with their own glue (error wrapping, telemetry,
+ * result envelopes); `registerWorkflowTools` is the bundled convenience
+ * for hosts without opinions of their own.
+ */
+export declare interface WorkflowToolDef {
+  readonly name: string;
+  readonly description: string;
+  /**
+   * Raw zod shape — the single schema source of truth: MCP servers
+   * register it directly, {@link parseToolInput} wraps it for runtime
+   * parsing, and {@link toolInputJsonSchema} derives the JSON-schema
+   * descriptor for non-MCP consumers.
+   */
+  readonly inputSchema: ZodRawShape;
+  readonly annotations: ToolAnnotations;
+  /**
+   * Returns plain projected data (the `Projected*` shapes) — hosts own
+   * the serialisation into their transport's result envelope. Takes
+   * `unknown` and parses internally: a heterogeneous list of defs with
+   * typed handler inputs is unassignable under `strictFunctionTypes`,
+   * so the narrowing lives inside each handler instead.
+   */
+  readonly handler: (
+    context: WorkflowToolContextThunk,
+    input: unknown,
+  ) => Promise<unknown>;
+}
+
+/** The per-request extra the MCP SDK hands every registered tool callback. */
+export declare type WorkflowToolExtra = RequestHandlerExtra<
+  ServerRequest,
+  ServerNotification
+>;
+
 export {};