@sanity/workflow-mcp 0.5.1 → 0.6.0

package/dist/index.d.cts

@@ -1,42 +1,31 @@
 import type { Diagnosis } from "@sanity/workflow-engine";
-import { Engine } from "@sanity/workflow-engine";
+import type { Engine } 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.
- */
-export declare function buildTools(
-  engine: Engine,
-  options?: BuildToolsOptions,
-): BuiltTools;
-
-/**
- * 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.
+ * 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 interface BuildToolsOptions {
-  access?: WorkflowAccessOverride;
-}
-
-export declare interface BuiltTools {
-  descriptors: ToolDescriptor[];
-  impls: Record<string, ToolImpl>;
-}
+export declare type GetWorkflowToolContext = (
+  extra: WorkflowToolExtra,
+  input: unknown,
+) => WorkflowToolContext | Promise<WorkflowToolContext>;
 
 export declare interface ProjectedActionVerdict {
   /** Action name — what to pass to `fire_action` as `action`. */
@@ -80,6 +69,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 +85,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,73 +156,35 @@ 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
@@ -245,4 +201,78 @@ export declare type ValidateDefinitionResult =
       error: string;
     };
 
+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 {};

package/dist/index.d.ts

@@ -1,42 +1,31 @@
 import type { Diagnosis } from "@sanity/workflow-engine";
-import { Engine } from "@sanity/workflow-engine";
+import type { Engine } 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.
- */
-export declare function buildTools(
-  engine: Engine,
-  options?: BuildToolsOptions,
-): BuiltTools;
-
-/**
- * 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.
+ * 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 interface BuildToolsOptions {
-  access?: WorkflowAccessOverride;
-}
-
-export declare interface BuiltTools {
-  descriptors: ToolDescriptor[];
-  impls: Record<string, ToolImpl>;
-}
+export declare type GetWorkflowToolContext = (
+  extra: WorkflowToolExtra,
+  input: unknown,
+) => WorkflowToolContext | Promise<WorkflowToolContext>;
 
 export declare interface ProjectedActionVerdict {
   /** Action name — what to pass to `fire_action` as `action`. */
@@ -80,6 +69,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 +85,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,73 +156,35 @@ 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
@@ -245,4 +201,78 @@ export declare type ValidateDefinitionResult =
       error: string;
     };
 
+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 {};