Merge pull request #290 from Blazity/feat/aiw-239-mcp-block-catalog

feat(worker): expose MCP block catalog and run stats for agent authors (AIW-239)

Author: outof-place

SETUP.md

@@ -621,6 +621,52 @@ The key is **required for the feature but optional at boot**: the worker starts
 
 > **Security warning.** The shipped `webhook-ticket-triage` template feeds external input (a support ticket body) straight through to an automatically opened pull request with **no human gate**. HMAC authenticates the **channel**, not the **content**: anyone who can file a ticket into a connected Zendesk or Sentry controls the agent's prompt, and therefore the PR it opens. Before pointing a real sender at this template, add a human-approval gate before the `open_pr` block, or treat the workflow as triage-and-notify only.
 
+### Remote MCP — connect your agent
+
+A deployment can expose an [MCP](https://modelcontextprotocol.io) endpoint so an external agent (Claude, or any MCP-capable client) can inspect this deployment's workflows, block catalog and run history, and — if you grant it the scope — author and dispatch workflows itself. It is off by default and entirely additive: nothing here is required for the bot to run.
+
+| Variable | Value |
+| --- | --- |
+| `MCP_ENABLED` | `true` to turn the endpoint on. Defaults to `false`. |
+| `MCP_ALLOW_PUBLIC_DCR` | `true` to let a connecting client register itself via OAuth Dynamic Client Registration, with no client pre-provisioned. Defaults to `false`. This is the path a customer engineer wiring up their own agent normally wants. |
+
+```bash
+vercel env add MCP_ENABLED production
+vercel env add MCP_ALLOW_PUBLIC_DCR production
+```
+
+Redeploy after setting either variable.
+
+**Connecting.** Point your agent's MCP client at:
+
+```
+https://<your-worker>.vercel.app/mcp
+```
+
+using the Streamable HTTP transport at protocol version `2025-11-25` (`2025-06-18` is also accepted). Authentication is standard MCP OAuth: an MCP-compliant client discovers the authorization requirements from the endpoint itself (`WWW-Authenticate`, then `.well-known/oauth-protected-resource` and `.well-known/oauth-authorization-server`), registers itself if `MCP_ALLOW_PUBLIC_DCR` is on, and opens a browser tab for the connecting person to log in and approve a consent screen — nothing is pasted or configured by hand. Approve only the scopes the agent actually needs:
+
+| Scope | Grants |
+| --- | --- |
+| `mcp:read` | Read tickets, runs, workflows, prompts and the block catalog. Enough to inspect a deployment without changing anything. |
+| `runs:dispatch` | Start a manual run, answer a run's clarification, cancel a run. |
+| `workflows:write` | Author workflows: create a definition, save a draft graph, publish it live. |
+| `prompts:write` | Edit the prompt library. |
+| `tickets:write` | Comment on, transition, or create a ticket in the connected tracker. |
+
+**Verifying the connection.** Ask the connected agent to call `system.capabilities` (confirms the handshake and reports the enabled tool domains) and then `blocks.list` (confirms it can read this deployment's block catalog — every block type the editor offers, with its input and output contract, so an authoring agent can compose a valid graph without guessing a field name and finding out from a `VALIDATION_FAILED`).
+
+**A worked example: a loop and a branch together.** [`docs/example-workflows/loop-branch-workflow.json`](./docs/example-workflows/loop-branch-workflow.json) is a complete, valid workflow graph an agent can read for a concrete pattern rather than reasoning from the block catalog alone. Shape:
+
+```
+trigger_ticket_ai -> planning_agent -> branch(gate)
+  gate --true--> send_slack_message -> terminate       (needs a human, stop and say so)
+  gate --false--> implementation_agent -> run_pre_pr_checks -> branch(verdict)
+    verdict --true--> finalize_workspace -> open_pr     (checks passed, ship it)
+    verdict --false--> loop(retry) --continue--> review_agent(fix) -> back to run_pre_pr_checks
+```
+
+`branch` reads a `condition` param and fires its `true` or `false` port; `loop` re-enters its `continue` port up to `maxAttempts` times before taking `onExhaust`. To try it against a real deployment, hand the file to `workflows.create` + `workflows.save_draft` (the same graph the dashboard editor would save), then `workflows.publish` when ready to go live — publishing arms whatever triggers the graph contains, so read each tool's description before calling it against anything but a scratch definition.
+
 ---
 
 ## 13. Troubleshooting

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

@@ -53,6 +53,9 @@ describe("MCP public contracts", () => {
       "tickets.comment",
       "tickets.transition",
       "tickets.create",
+      "blocks.list",
+      "blocks.get",
+      "runs.stats",
     ]);
     expect(new Set(FIRST_SLICE_TOOLS).size).toBe(FIRST_SLICE_TOOLS.length);
   });

apps/worker/src/mcp/contracts.ts

@@ -72,6 +72,20 @@ export const FIRST_SLICE_TOOLS = [
   "tickets.comment",
   "tickets.transition",
   "tickets.create",
+  // A new domain, appended rather than interleaved with the read tools above for
+  // the same reason every earlier addition was: the published order of what
+  // already shipped stays byte-identical. blocks.list/blocks.get close the gap
+  // an authoring agent hit first -- workflows.save_draft takes a graph, but
+  // nothing published what a node's params, inputs or output actually look like,
+  // so a caller could only learn a block's contract by trial and VALIDATION_FAILED.
+  "blocks.list",
+  "blocks.get",
+  // Named under the "runs" domain it belongs to, even though (per the rule above)
+  // it registers last rather than beside runs.get/runs.trace/runs.result/
+  // runs.diagnose: an agent asking "how has this deployment been doing" had
+  // per-run detail and nothing that rolled runs up, the same gap prompts.list
+  // once closed for prompts.get.
+  "runs.stats",
 ] as const;
 export type McpToolName = (typeof FIRST_SLICE_TOOLS)[number];
 

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

@@ -1,5 +1,5 @@
 {
-  "contractHash": "881de2fae17a183a44645d8d6c6c8c8089e604fcc2197d98d4f27acb66ec2f7b",
+  "contractHash": "9d49bdaa24bf72887ec0477a779ab5f81f88e8805afd4806685b0ddb6b3561fe",
   "errorCodes": [
     "UNAUTHENTICATED",
     "INSUFFICIENT_SCOPE",
@@ -845,6 +845,76 @@
         "idempotentHint": true,
         "openWorldHint": true
       }
+    },
+    {
+      "name": "blocks.list",
+      "description": "List every block type this deployment's workflow editor offers, with its presentation (label, group, description), its input contract, its output contract and the status variants it can report. `availability.available` is false for a block this deployment cannot run today (no provider configured), naming why in `unavailableReason`; the block still lists, because a graph authored now may become runnable once the provider is.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {}
+      },
+      "annotations": {
+        "readOnlyHint": true,
+        "destructiveHint": false,
+        "idempotentHint": true,
+        "openWorldHint": false
+      }
+    },
+    {
+      "name": "blocks.get",
+      "description": "Read one block type's contract by name: the same object blocks.list returns for it. An unrecognized `type` is refused with NOT_FOUND rather than VALIDATION_FAILED, since block types are versioned by the deployment, not by this catalog.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "type": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 64
+          }
+        },
+        "required": [
+          "type"
+        ],
+        "additionalProperties": false,
+        "$schema": "http://json-schema.org/draft-07/schema#"
+      },
+      "annotations": {
+        "readOnlyHint": true,
+        "destructiveHint": false,
+        "idempotentHint": true,
+        "openWorldHint": false
+      }
+    },
+    {
+      "name": "runs.stats",
+      "description": "Roll up recent run outcomes and aggregate spend for a time window (default 24h, matching the dashboard's own default). `runs` is the newest page of outcomes in the window (`runsTruncated` says whether more exist); `cost` is the same windowed total, per-workflow breakdown and daily series the dashboard's cost view reads, computed from persisted per-run cost rather than an external provider.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "window": {
+            "type": "string",
+            "enum": [
+              "24h",
+              "7d",
+              "30d",
+              "all"
+            ]
+          },
+          "limit": {
+            "type": "integer",
+            "minimum": 1,
+            "maximum": 100
+          }
+        },
+        "additionalProperties": false,
+        "$schema": "http://json-schema.org/draft-07/schema#"
+      },
+      "annotations": {
+        "readOnlyHint": true,
+        "destructiveHint": false,
+        "idempotentHint": true,
+        "openWorldHint": false
+      }
     }
   ]
 }

apps/worker/src/mcp/policy.ts

@@ -259,6 +259,15 @@ const TOOL_POLICY = {
   "tickets.comment": TICKET_WRITE_POLICY,
   "tickets.transition": TICKET_TRANSITION_POLICY,
   "tickets.create": TICKET_WRITE_POLICY,
+  // Plain reads, same reasoning as workflows.list above: the block catalog is
+  // this deployment's own static configuration, not a customer's data, and an
+  // agent needs it BEFORE it knows whether it may author or dispatch anything.
+  "blocks.list": READ_POLICY,
+  "blocks.get": READ_POLICY,
+  // A rollup over runs.get's own data, gated the same way: seeing how the fleet
+  // has been doing costs nothing beyond what runs.get already exposes one run
+  // at a time.
+  "runs.stats": READ_POLICY,
 } satisfies Record<McpToolName, McpToolPolicy>;
 
 export function policyFor(tool: McpToolName): McpToolPolicy {

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

@@ -52,6 +52,9 @@ const PUBLISHED: McpToolName[] = [
   "tickets.comment",
   "tickets.transition",
   "tickets.create",
+  "blocks.list",
+  "blocks.get",
+  "runs.stats",
 ];
 
 const cleanups: Array<() => Promise<void>> = [];
@@ -158,7 +161,7 @@ describe("createMcpServer", () => {
       data: {
         protocolVersions: ["2025-11-25", "2025-06-18"],
         serverVersion: "0.1.0",
-        enabledDomains: ["system", "tickets", "runs", "workflows", "prompts"],
+        enabledDomains: ["system", "tickets", "runs", "workflows", "prompts", "blocks"],
         // These deps carry no messaging adapter, which is the same answer a
         // deployment with no chat credentials gives: the authoring announcements
         // those tools send would reach nobody, and a client is told so rather than

apps/worker/src/mcp/server.ts

@@ -6,9 +6,11 @@ import { executeMcpRead } from "./execute-tool.js";
 import { MCP_CONTRACT_HASH } from "./sanitize-result.js";
 import { MCP_ENABLED_DOMAINS, registerCatalogTool } from "./tool-catalog.js";
 import { authoringAnnouncementDelivery } from "./tools/authoring-support.js";
+import { registerBlockTools } from "./tools/blocks.js";
 import { registerDiscoveryTools } from "./tools/discovery.js";
 import { registerPromptAuthoringTools } from "./tools/prompt-authoring.js";
 import { registerRunControlTools } from "./tools/run-control.js";
+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";
@@ -63,6 +65,8 @@ export function createMcpServer(deps: McpToolDependencies): McpServer {
   registerWorkflowAuthoringTools(server, deps);
   registerRunControlTools(server, deps);
   registerTicketWriteTools(server, deps);
+  registerBlockTools(server, deps);
+  registerRunStatsTools(server, deps);
 
   return server;
 }

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

@@ -41,6 +41,12 @@ const state = vi.hoisted(() => ({
     // just the bearer/GitHub regexes.
     JIRA_API_TOKEN: "jira-e2e-4d9f1b7c3a8e2510-secret",
     MAX_CONCURRENT_AGENTS: 4,
+    // Read by blocks.list/blocks.get through workflowBlockRegistryContextFromEnv,
+    // whose defaultAgent.model feeds resolveLlmProvider (lib/llm-provider.ts),
+    // which crashes on an undefined model rather than defaulting.
+    AGENT_KIND: "claude",
+    CLAUDE_MODEL: "claude-opus-4-8",
+    CODEX_MODEL: "gpt-5.4",
   },
   requireMcpActor: vi.fn(),
   createAdapters: vi.fn<() => Record<string, unknown>>(() => ({})),
@@ -120,6 +126,9 @@ const PUBLISHED = [
   "tickets.comment",
   "tickets.transition",
   "tickets.create",
+  "blocks.list",
+  "blocks.get",
+  "runs.stats",
 ];
 
 const READ_ANNOTATIONS = {
@@ -216,9 +225,15 @@ const EXPECTED_ANNOTATIONS: Record<string, Record<string, boolean>> = {
   "tickets.comment": TICKET_WRITE_ANNOTATIONS,
   "tickets.transition": TICKET_TRANSITION_ANNOTATIONS,
   "tickets.create": TICKET_WRITE_ANNOTATIONS,
+  // The block catalog is this deployment's own static configuration and the
+  // run rollup is read-only over data runs.get already exposes one row at a
+  // time, so both keep the plain read annotations.
+  "blocks.list": READ_ANNOTATIONS,
+  "blocks.get": READ_ANNOTATIONS,
+  "runs.stats": READ_ANNOTATIONS,
 };
 
-const DOMAINS = ["system", "tickets", "runs", "workflows", "prompts"];
+const DOMAINS = ["system", "tickets", "runs", "workflows", "prompts", "blocks"];
 
 // The committed artifact, read as a file. This is the independent source for the
 // contract hash: MCP_CONTRACT_HASH is computed at runtime from the same catalog
@@ -833,6 +848,17 @@ const READ_TOOL_CASES = [
     args: { slug: PROMPT_SLUG },
     data: { slug: PROMPT_SLUG, version: 1, body: PROMPT_BODY, archived: false },
   },
+  // Not blocks.list: the full block catalog runs past this file's deliberately
+  // tight MCP_MAX_RESULT_BYTES (64 KiB, sized for runs.trace's pagination
+  // tests), so it exercises the envelope's own oversized-payload fallback
+  // rather than a normal read -- real coverage of the tool's own shape lives in
+  // tools/blocks.test.ts, against the production-sized budget every other tool
+  // test file uses.
+  {
+    tool: "blocks.get",
+    args: { type: "loop" },
+    data: { type: "loop" },
+  },
 ] as const;
 
 describe("B. every read tool, over HTTP, on seeded data", () => {

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

@@ -60,6 +60,9 @@ const CATALOGUED = [
   "tickets.comment",
   "tickets.transition",
   "tickets.create",
+  "blocks.list",
+  "blocks.get",
+  "runs.stats",
 ] as const;
 
 // Captured off the real McpServer, through the real createMcpServer, because the

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

@@ -109,6 +109,17 @@ const TICKET_LABELS_MAX = 20;
 const TRACE_CURSOR_MAX_LENGTH = 512;
 const PR_URL_MAX_LENGTH = 2_048;
 const TRIGGER_NODE_ID_MAX_LENGTH = 200;
+// The longest WorkflowBlockType literal today ("trigger_pr_checks_failed") is 25
+// characters; this is generous headroom, not a fitted bound. Kept a plain string
+// rather than a zod enum of every block type on purpose: the block registry is
+// worker-internal and the module doc above forbids importing it here, so the one
+// authority on whether a type is real is blocks.get's own lookup, which answers
+// an unknown one with NOT_FOUND instead of a catalog-level VALIDATION_FAILED.
+const BLOCK_TYPE_MAX_LENGTH = 64;
+// Mirrors WINDOWS in db/queries/runs-read.ts (a literal, not imported, for the
+// reason the module doc above gives): tool-catalog.test.ts asserts the two stay
+// equal.
+const RUN_STATS_WINDOWS = ["24h", "7d", "30d", "all"] as const;
 
 const runIdInputSchema = z.object({ runId: z.string().trim().min(1).max(RUN_ID_MAX_LENGTH) });
 
@@ -419,6 +430,31 @@ export const MCP_TOOL_CATALOG = {
       .strict(),
     annotations: policyFor("tickets.create").annotations,
   },
+  "blocks.list": {
+    description:
+      "List every block type this deployment's workflow editor offers, with its presentation (label, group, description), its input contract, its output contract and the status variants it can report. `availability.available` is false for a block this deployment cannot run today (no provider configured), naming why in `unavailableReason`; the block still lists, because a graph authored now may become runnable once the provider is.",
+    inputSchema: z.object({}).strict().default({}),
+    annotations: policyFor("blocks.list").annotations,
+  },
+  "blocks.get": {
+    description:
+      "Read one block type's contract by name: the same object blocks.list returns for it. An unrecognized `type` is refused with NOT_FOUND rather than VALIDATION_FAILED, since block types are versioned by the deployment, not by this catalog.",
+    inputSchema: z
+      .object({ type: z.string().trim().min(1).max(BLOCK_TYPE_MAX_LENGTH) })
+      .strict(),
+    annotations: policyFor("blocks.get").annotations,
+  },
+  "runs.stats": {
+    description:
+      "Roll up recent run outcomes and aggregate spend for a time window (default 24h, matching the dashboard's own default). `runs` is the newest page of outcomes in the window (`runsTruncated` says whether more exist); `cost` is the same windowed total, per-workflow breakdown and daily series the dashboard's cost view reads, computed from persisted per-run cost rather than an external provider.",
+    inputSchema: z
+      .object({
+        window: z.enum(RUN_STATS_WINDOWS).optional(),
+        limit: z.number().int().min(1).max(MAX_RUNS_LIMIT).optional(),
+      })
+      .strict(),
+    annotations: policyFor("runs.stats").annotations,
+  },
 } satisfies Record<McpToolName, McpToolDefinition>;
 
 export const MCP_ENABLED_DOMAINS = [
@@ -427,6 +463,7 @@ export const MCP_ENABLED_DOMAINS = [
   "runs",
   "workflows",
   "prompts",
+  "blocks",
 ] as const;
 
 const CATALOG: Record<McpToolName, McpToolDefinition> = MCP_TOOL_CATALOG;