feat(worker): expose MCP workflow graph read and enabled toggle (AIW-286)

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015kfeohXE66xx7RJPxZ2pvH

Author: outof-place

apps/worker/src/mcp/contracts.test.ts

@@ -56,6 +56,8 @@ describe("MCP public contracts", () => {
       "blocks.list",
       "blocks.get",
       "runs.stats",
+      "workflows.get_graph",
+      "workflows.set_enabled",
     ]);
     expect(new Set(FIRST_SLICE_TOOLS).size).toBe(FIRST_SLICE_TOOLS.length);
   });

apps/worker/src/mcp/contracts.ts

@@ -86,6 +86,16 @@ export const FIRST_SLICE_TOOLS = [
   // per-run detail and nothing that rolled runs up, the same gap prompts.list
   // once closed for prompts.get.
   "runs.stats",
+  // Appended last, again to keep the published order of everything before them
+  // byte-identical. These two close the last gap in authoring a workflow from a
+  // client: workflows.save_draft takes a WHOLE graph, but nothing returned an
+  // existing definition's graph with its per-node configuration and the revision
+  // tokens a save or a publish is gated on, so an agent could only edit a graph it
+  // had itself just composed; and workflows.set_enabled is the definition's own
+  // enable switch, the field workflows.publish inherits rather than sets, so an
+  // agent could deploy a graph but never turn the definition on or off.
+  "workflows.get_graph",
+  "workflows.set_enabled",
 ] as const;
 export type McpToolName = (typeof FIRST_SLICE_TOOLS)[number];
 

apps/worker/src/mcp/contracts/mcp-contract.json

@@ -1,5 +1,5 @@
 {
-  "contractHash": "9d49bdaa24bf72887ec0477a779ab5f81f88e8805afd4806685b0ddb6b3561fe",
+  "contractHash": "623636ee5d127b0d2b69418f8d1c25b23c5a009e140eca520f75ed646cb09ed3",
   "errorCodes": [
     "UNAUTHENTICATED",
     "INSUFFICIENT_SCOPE",
@@ -915,6 +915,65 @@
         "idempotentHint": true,
         "openWorldHint": false
       }
+    },
+    {
+      "name": "workflows.get_graph",
+      "description": "Read a definition's workflow graph, in the exact `{schemaVersion, nodes, edges}` shape workflows.save_draft accepts, for BOTH the current draft and the deployed version. Every node carries its full `configuration`, `inputs` and `additionalInputs`, and the pinned `repositoryScope` rides along too, so a graph fetched here can be edited and sent straight back to workflows.save_draft without losing anything: saving the unmodified draft yields the same `graphHash` this tool reports for it in `draftGraphHash`. `draftRevision` is the token workflows.save_draft takes as `expectedDraftRevision` (0 for a definition that has never been saved, where `draft` is null), and `deployedVersion` is the token workflows.publish takes as `expectedDeployedVersion` (null when nothing is deployed yet, where `deployed` is null). `draftGraphHash` and `deployedGraphHash` are sha256 over the canonical JSON of each stored version, directly comparable with the `graphHash` workflows.save_draft and workflows.publish report for the same version. Any secret configured for this deployment is redacted from the reply exactly as everywhere else on this surface; a stored graph does not carry one, so that redaction leaves the round trip lossless. An unknown or archived definition is NOT_FOUND.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "definitionId": {
+            "type": "integer",
+            "exclusiveMinimum": 0,
+            "maximum": 2147483647
+          }
+        },
+        "required": [
+          "definitionId"
+        ],
+        "additionalProperties": false,
+        "$schema": "http://json-schema.org/draft-07/schema#"
+      },
+      "annotations": {
+        "readOnlyHint": true,
+        "destructiveHint": false,
+        "idempotentHint": true,
+        "openWorldHint": false
+      }
+    },
+    {
+      "name": "workflows.set_enabled",
+      "description": "Turn a definition's `enabled` switch on or off, independent of publishing: this is the one field workflows.publish inherits rather than sets. Runs through exactly the dashboard's own guardrails. Enabling a definition with no deployable version is refused with CONFLICT, and enabling one whose deployed graph no longer passes the deployment gate with VALIDATION_FAILED. Enabling a definition whose trigger another enabled definition already owns is refused with CONFLICT naming that definition (for example, a second `trigger_ticket_ai` while one is already enabled), so two definitions cannot silently answer the same event. Enabling arms the deployed head's real-event triggers, minting webhook endpoints and syncing schedule rows, so from then on real ticket and pull request events execute this graph; disabling releases those bindings, so they stop. `enabled` in the reply is the resulting state and `triggerTypes` the triggers now (or no longer) live. Idempotent per idempotencyKey. A concurrent change to the definition is refused with CONFLICT: reload before retrying.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "definitionId": {
+            "type": "integer",
+            "exclusiveMinimum": 0,
+            "maximum": 2147483647
+          },
+          "enabled": {
+            "type": "boolean"
+          },
+          "idempotencyKey": {
+            "type": "string",
+            "format": "uuid"
+          }
+        },
+        "required": [
+          "definitionId",
+          "enabled",
+          "idempotencyKey"
+        ],
+        "additionalProperties": false,
+        "$schema": "http://json-schema.org/draft-07/schema#"
+      },
+      "annotations": {
+        "readOnlyHint": false,
+        "destructiveHint": true,
+        "idempotentHint": true,
+        "openWorldHint": true
+      }
     }
   ]
 }

apps/worker/src/mcp/policy.ts

@@ -228,6 +228,30 @@ const DISPATCH_PREFLIGHT_POLICY = {
   roles: DISPATCH_POLICY.roles,
 } as const satisfies McpToolPolicy;
 
+// Reading a whole authorable graph: every node's configuration, the pinned
+// repositories, and the revision tokens a save or a publish is gated on. It is the
+// read half of authoring, exactly what workflows.save_draft consumes, so it rides
+// workflows:write and its role list the way dispatch_preflight rides runs:dispatch
+// -- discovery that feeds a privileged action is gated behind that action's scope.
+// workflows.list stays mcp:read because naming what exists is coarse discovery; this
+// hands back the instruction itself, so it costs the authoring consent.
+const WORKFLOW_GRAPH_READ_POLICY = {
+  ...READ_POLICY,
+  scope: WORKFLOW_WRITE_POLICY.scope,
+  roles: WORKFLOW_WRITE_POLICY.roles,
+} as const satisfies McpToolPolicy;
+
+// Flipping a definition's enable switch, the same switch the dashboard's toggle sets
+// and the one workflows.publish INHERITS rather than changes. Enabling arms the
+// deployed head's real-event triggers -- the store mints the webhook endpoints and
+// syncs the schedule rows of a live head -- so from that moment real ticket and pull
+// request events execute the graph, and disabling releases those bindings again. That
+// is the same destructive, open-world replacement of what the platform runs that a
+// publish is, so it takes the publish annotations, and it rides the same
+// workflows:write scope and admin/owner list: deciding what runs for real events is
+// the authoring authority, not the dispatch one.
+const WORKFLOW_SET_ENABLED_POLICY = WORKFLOW_PUBLISH_POLICY;
+
 const TOOL_POLICY = {
   "system.capabilities": READ_POLICY,
   "tickets.get": READ_POLICY,
@@ -249,6 +273,11 @@ const TOOL_POLICY = {
   "workflows.create": WORKFLOW_WRITE_POLICY,
   "workflows.save_draft": WORKFLOW_WRITE_POLICY,
   "workflows.publish": WORKFLOW_PUBLISH_POLICY,
+  // A read shaped like the authoring writes it feeds, and the enable switch those
+  // writes inherit but never set. See the two policies above for why both ride
+  // workflows:write rather than mcp:read or runs:dispatch.
+  "workflows.get_graph": WORKFLOW_GRAPH_READ_POLICY,
+  "workflows.set_enabled": WORKFLOW_SET_ENABLED_POLICY,
   // A plain read: seeing THAT a run is waiting and what it asked is what a
   // read-only client needs to report a stuck run to a person, and gating it behind
   // the dispatch scope would hide the question from the client most likely to be

apps/worker/src/mcp/server.test.ts

@@ -55,6 +55,8 @@ const PUBLISHED: McpToolName[] = [
   "blocks.list",
   "blocks.get",
   "runs.stats",
+  "workflows.get_graph",
+  "workflows.set_enabled",
 ];
 
 const cleanups: Array<() => Promise<void>> = [];

apps/worker/src/mcp/server.ts

@@ -14,7 +14,10 @@ import { registerRunStatsTools } from "./tools/run-stats.js";
 import { registerRunTools } from "./tools/runs.js";
 import { registerTicketWriteTools } from "./tools/ticket-write.js";
 import { registerTicketTools } from "./tools/tickets.js";
-import { registerWorkflowAuthoringTools } from "./tools/workflow-authoring.js";
+import {
+  registerWorkflowAuthoringTools,
+  registerWorkflowGraphTools,
+} from "./tools/workflow-authoring.js";
 import { registerWorkflowTools } from "./tools/workflows.js";
 
 export const MCP_PROTOCOL_VERSION = "2025-11-25" as const;
@@ -67,6 +70,9 @@ export function createMcpServer(deps: McpToolDependencies): McpServer {
   registerTicketWriteTools(server, deps);
   registerBlockTools(server, deps);
   registerRunStatsTools(server, deps);
+  // Last, so workflows.get_graph and workflows.set_enabled enumerate at the end of
+  // tools/list, matching their appended position in FIRST_SLICE_TOOLS.
+  registerWorkflowGraphTools(server, deps);
 
   return server;
 }

apps/worker/src/mcp/surface-e2e.test.ts

@@ -129,6 +129,8 @@ const PUBLISHED = [
   "blocks.list",
   "blocks.get",
   "runs.stats",
+  "workflows.get_graph",
+  "workflows.set_enabled",
 ];
 
 const READ_ANNOTATIONS = {
@@ -231,6 +233,14 @@ const EXPECTED_ANNOTATIONS: Record<string, Record<string, boolean>> = {
   "blocks.list": READ_ANNOTATIONS,
   "blocks.get": READ_ANNOTATIONS,
   "runs.stats": READ_ANNOTATIONS,
+  // Reading a whole authorable graph changes nothing, so it keeps the read
+  // annotations even though it is gated behind workflows:write, exactly as
+  // dispatch_preflight keeps them behind runs:dispatch.
+  "workflows.get_graph": READ_ANNOTATIONS,
+  // Flipping the enable switch arms or releases a live head's real-event triggers,
+  // the same destructive, open-world change to what the platform runs that a publish
+  // is.
+  "workflows.set_enabled": WORKFLOW_PUBLISH_ANNOTATIONS,
 };
 
 const DOMAINS = ["system", "tickets", "runs", "workflows", "prompts", "blocks"];

apps/worker/src/mcp/tool-catalog.test.ts

@@ -63,6 +63,8 @@ const CATALOGUED = [
   "blocks.list",
   "blocks.get",
   "runs.stats",
+  "workflows.get_graph",
+  "workflows.set_enabled",
 ] as const;
 
 // Captured off the real McpServer, through the real createMcpServer, because the

apps/worker/src/mcp/tool-catalog.ts

@@ -455,6 +455,28 @@ export const MCP_TOOL_CATALOG = {
       .strict(),
     annotations: policyFor("runs.stats").annotations,
   },
+  "workflows.get_graph": {
+    description:
+      "Read a definition's workflow graph, in the exact `{schemaVersion, nodes, edges}` shape workflows.save_draft accepts, for BOTH the current draft and the deployed version. Every node carries its full `configuration`, `inputs` and `additionalInputs`, and the pinned `repositoryScope` rides along too, so a graph fetched here can be edited and sent straight back to workflows.save_draft without losing anything: saving the unmodified draft yields the same `graphHash` this tool reports for it in `draftGraphHash`. `draftRevision` is the token workflows.save_draft takes as `expectedDraftRevision` (0 for a definition that has never been saved, where `draft` is null), and `deployedVersion` is the token workflows.publish takes as `expectedDeployedVersion` (null when nothing is deployed yet, where `deployed` is null). `draftGraphHash` and `deployedGraphHash` are sha256 over the canonical JSON of each stored version, directly comparable with the `graphHash` workflows.save_draft and workflows.publish report for the same version. Any secret configured for this deployment is redacted from the reply exactly as everywhere else on this surface; a stored graph does not carry one, so that redaction leaves the round trip lossless. An unknown or archived definition is NOT_FOUND.",
+    inputSchema: z
+      .object({
+        definitionId: z.number().int().positive().max(DEFINITION_ID_MAX),
+      })
+      .strict(),
+    annotations: policyFor("workflows.get_graph").annotations,
+  },
+  "workflows.set_enabled": {
+    description:
+      "Turn a definition's `enabled` switch on or off, independent of publishing: this is the one field workflows.publish inherits rather than sets. Runs through exactly the dashboard's own guardrails. Enabling a definition with no deployable version is refused with CONFLICT, and enabling one whose deployed graph no longer passes the deployment gate with VALIDATION_FAILED. Enabling a definition whose trigger another enabled definition already owns is refused with CONFLICT naming that definition (for example, a second `trigger_ticket_ai` while one is already enabled), so two definitions cannot silently answer the same event. Enabling arms the deployed head's real-event triggers, minting webhook endpoints and syncing schedule rows, so from then on real ticket and pull request events execute this graph; disabling releases those bindings, so they stop. `enabled` in the reply is the resulting state and `triggerTypes` the triggers now (or no longer) live. Idempotent per idempotencyKey. A concurrent change to the definition is refused with CONFLICT: reload before retrying.",
+    inputSchema: z
+      .object({
+        definitionId: z.number().int().positive().max(DEFINITION_ID_MAX),
+        enabled: z.boolean(),
+        idempotencyKey: z.string().uuid(),
+      })
+      .strict(),
+    annotations: policyFor("workflows.set_enabled").annotations,
+  },
 } satisfies Record<McpToolName, McpToolDefinition>;
 
 export const MCP_ENABLED_DOMAINS = [