@blokjs/trigger-mcp 0.6.18 → 0.6.20

package/README.md

@@ -0,0 +1,131 @@
+# @blokjs/trigger-mcp
+
+Model Context Protocol (MCP) trigger for [Blok](https://github.com/well-prado/blok)
+workflows. Expose a workflow as an MCP **tool** or **resource** so AI
+clients — Claude Code, Cursor, Claude Desktop, or your own agent — can
+discover and call it. Serves both transports (Streamable-HTTP + legacy
+SSE) on the shared Hono HTTP port.
+
+> **Full reference:** [Blok docs → Triggers → MCP](https://github.com/well-prado/blok/blob/main/docs/d/triggers/mcp.mdx)
+
+## What it does
+
+- Scans the workflow registry for workflows with a `trigger.mcp` block and
+  exposes each one to MCP clients.
+- Generates each tool's JSON `inputSchema` from the workflow's Zod `input`
+  (via `zod-to-json-schema`).
+- Runs `tools/call` / `resources/read` through the normal Blok runner — so
+  retries, idempotency, middleware, cancellation, and Studio tracing all
+  apply.
+- Mounts on the HTTP trigger's Hono app (same port, same process). No
+  separate listener.
+
+## Authoring a tool
+
+A `trigger.mcp` workflow is a normal v2 workflow. The `input` schema is the
+tool contract; the final step's output is the tool result.
+
+```ts
+import { workflow } from "@blokjs/helper";
+import { z } from "zod";
+
+export default workflow({
+  name: "mcp-greeter",
+  version: "1.0.0",
+  input: z.object({
+    name: z.string().min(1).describe("Name of the person to greet"),
+    excited: z.boolean().default(false),
+  }),
+  trigger: {
+    mcp: {
+      path: "/mcp",
+      serverName: "blok-examples",
+      tool: { name: "greet", description: "Greet a person by name." },
+    },
+  },
+  steps: [
+    {
+      id: "greet",
+      use: "@blokjs/expr",
+      inputs: {
+        expression:
+          '({ greeting: "Hello, " + (ctx.request.body.name || "there") + (ctx.request.body.excited ? "!" : ".") })',
+      },
+    },
+  ],
+});
+```
+
+Scaffold a project with this exact example:
+
+```bash
+npx blokctl@latest create project --triggers http,mcp --examples
+```
+
+## Transports & routes
+
+Both default on; override per workflow with `transports: [...]`.
+
+| Transport | Route(s) | State |
+| --- | --- | --- |
+| Streamable-HTTP | `ALL <path>` (e.g. `POST /mcp`) | Stateless |
+| SSE (legacy) | `GET <path>/sse` + `POST <path>/messages?sessionId=…` | Stateful |
+
+On start the trigger logs each mounted server and route:
+
+```
+[blok][mcp] server "blok-examples" at /mcp — 1 tool(s), 0 resource(s), transports=[sse,streamable-http]
+[blok][mcp]   GET  /mcp/sse   POST /mcp/messages  (sse)
+[blok][mcp]   ALL  /mcp  (streamable-http)
+```
+
+## Connecting a client
+
+Give the client the URL `http://localhost:4000/mcp` (Streamable-HTTP) or
+`http://localhost:4000/mcp/sse` (SSE).
+
+```bash
+# Claude Code
+claude mcp add --transport http blok http://localhost:4000/mcp
+
+# Interactive debugging
+npx @modelcontextprotocol/inspector   # → connect to http://localhost:4000/mcp
+```
+
+```json
+// Cursor — .cursor/mcp.json
+{ "mcpServers": { "blok": { "url": "http://localhost:4000/mcp" } } }
+```
+
+Raw JSON-RPC (send `Accept: application/json, text/event-stream`):
+
+```bash
+curl -sS http://localhost:4000/mcp \
+  -H 'Content-Type: application/json' \
+  -H 'Accept: application/json, text/event-stream' \
+  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"greet","arguments":{"name":"Ada","excited":true}}}'
+```
+
+## Config reference
+
+| Field | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `path` | `string` | `"/mcp"` | Base path; workflows sharing a path aggregate into one server. |
+| `serverName` | `string` | `"blok-mcp"` | Advertised to clients — set something project-specific. |
+| `serverVersion` | `string` | `"1.0.0"` | Advertised server version. |
+| `transports` | `("sse" \| "streamable-http")[]` | both | At least one required. |
+| `tool` | `{ name?, description? }` | — | Tool mode (default). `name` defaults to the workflow name. |
+| `resource` | `{ uri, name?, description?, mimeType? }` | — | Resource mode. `uri` required; `mimeType` defaults to `application/json`. |
+| `middleware` | `string[]` | — | Trigger-level middleware chain. |
+
+## Identity is not authorization
+
+An `x-user-context` header (base64 `{ userId, email }`) or `?user_context=`
+query param is parsed and exposed at `ctx._mcp.userContext`. This is
+**credential injection only** — the trigger does not verify it or scope
+access. Enforce authorization yourself via trigger middleware or an auth
+proxy in front of the endpoint.
+
+## License
+
+Part of the Blok framework. See the repository root for license details.

package/package.json

@@ -1,6 +1,7 @@
 {
 	"name": "@blokjs/trigger-mcp",
-	"version": "0.6.18",
+	"version": "0.6.20",
+	"files": ["dist"],
 	"description": "Model Context Protocol (MCP) trigger for Blok workflows — expose workflows as MCP tools over SSE + Streamable-HTTP on the shared Hono port.",
 	"type": "module",
 	"main": "dist/index.js",
@@ -14,9 +15,9 @@
 	"author": "Deskree Technologies Inc.",
 	"license": "Apache-2.0",
 	"dependencies": {
-		"@blokjs/helper": "^0.6.18",
-		"@blokjs/runner": "^0.6.18",
-		"@blokjs/shared": "^0.6.18",
+		"@blokjs/helper": "^0.6.20",
+		"@blokjs/runner": "^0.6.20",
+		"@blokjs/shared": "^0.6.20",
 		"@modelcontextprotocol/sdk": "^1.29.0",
 		"@opentelemetry/api": "^1.9.0",
 		"hono": "^4.11.7",

package/src/McpTrigger.integration.test.ts

@@ -1,277 +0,0 @@
-/**
- * MCP trigger end-to-end integration test.
- *
- * Spins up a real Hono app + `@hono/node-server` with a real McpTrigger, then
- * drives it with the official MCP SDK **client** over BOTH transports:
- *   - SSE (GET /mcp/sse + POST /mcp/messages)
- *   - Streamable-HTTP (POST /mcp)
- *
- * Asserts the client can list tools (with an inputSchema generated from the
- * workflow's Zod `input`) and call a tool that runs through the runner and
- * returns the workflow's `ctx.response.data`.
- */
-
-import type { Server } from "node:http";
-import { NodeMap, WorkflowRegistry, defineNode } from "@blokjs/runner";
-import { serve } from "@hono/node-server";
-import { Client } from "@modelcontextprotocol/sdk/client/index.js";
-import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js";
-import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
-import { Hono } from "hono";
-import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
-import { z } from "zod";
-
-vi.mock("@opentelemetry/api", () => ({
-	trace: {
-		getTracer: () => ({
-			startActiveSpan: (_name: string, fn: (span: unknown) => unknown) =>
-				fn({
-					setAttribute: vi.fn(),
-					setStatus: vi.fn(),
-					recordException: vi.fn(),
-					end: vi.fn(),
-				}),
-		}),
-	},
-	metrics: {
-		getMeter: () => ({
-			createCounter: () => ({ add: vi.fn() }),
-			createHistogram: () => ({ record: vi.fn() }),
-			createGauge: () => ({ record: vi.fn() }),
-			createObservableGauge: () => ({ addCallback: vi.fn() }),
-		}),
-	},
-	SpanStatusCode: { OK: 0, ERROR: 1 },
-}));
-
-import McpTriggerClass, { _setActiveMcpTrigger } from "./McpTrigger";
-
-// Unique port per test — avoids same-port sequential-teardown (ECONNRESET /
-// TIME_WAIT) races when several real HTTP servers start/stop in a row.
-let nextPort = 4913;
-let BASE = `http://localhost:${nextPort}`;
-
-/** Inline tool node — echoes the input back so we can assert the round-trip. */
-const echoNode = defineNode({
-	name: "echo-node",
-	description: "test fixture — echo the input",
-	input: z.object({ msg: z.string() }),
-	output: z.object({ echoed: z.string(), upper: z.string() }),
-	async execute(_ctx, input) {
-		return { echoed: input.msg, upper: input.msg.toUpperCase() };
-	},
-});
-
-/** Returns the caller identity from the parsed x-user-context (credential injection). */
-const whoamiNode = defineNode({
-	name: "whoami-node",
-	description: "test fixture — echo the caller identity",
-	input: z.object({}).passthrough(),
-	output: z.object({ userId: z.string().optional(), email: z.string().optional() }),
-	async execute(ctx) {
-		const raw = (ctx.request?.headers as Record<string, string> | undefined)?.["x-user-context"];
-		if (!raw) return {};
-		const d = JSON.parse(Buffer.from(raw, "base64").toString("utf-8")) as { userId?: string; email?: string };
-		return { userId: d.userId, email: d.email };
-	},
-});
-
-/** Resource body provider. */
-const agentsNode = defineNode({
-	name: "agents-node",
-	description: "test fixture — resource body",
-	input: z.object({}).passthrough(),
-	output: z.object({ agents: z.array(z.string()) }),
-	async execute() {
-		return { agents: ["codebase", "infra"] };
-	},
-});
-
-function registerWorkflows(): void {
-	const reg = WorkflowRegistry.getInstance();
-	reg.register({
-		name: "echo_tool",
-		source: "/test/echo.ts",
-		workflow: {
-			name: "echo_tool",
-			version: "1.0.0",
-			trigger: {
-				mcp: {
-					path: "/mcp",
-					serverName: "test-mcp",
-					serverVersion: "1.0.0",
-					transports: ["sse", "streamable-http"],
-					tool: { description: "Echo the input back" },
-				},
-			},
-			input: z.object({ msg: z.string().describe("Message to echo") }),
-			steps: [{ id: "echo", node: "echo-node", type: "module", inputs: { msg: "js/ctx.request.body.msg" } }],
-			nodes: { echo: { inputs: { msg: "js/ctx.request.body.msg" } } },
-		},
-	});
-	reg.register({
-		name: "whoami",
-		source: "/test/whoami.ts",
-		workflow: {
-			name: "whoami",
-			version: "1.0.0",
-			trigger: { mcp: { path: "/mcp", serverName: "test-mcp", tool: { description: "Who am I" } } },
-			steps: [{ id: "who", node: "whoami-node", type: "module", inputs: {} }],
-			nodes: { who: { inputs: {} } },
-		},
-	});
-	reg.register({
-		name: "agents_resource",
-		source: "/test/agents.ts",
-		workflow: {
-			name: "agents_resource",
-			version: "1.0.0",
-			trigger: {
-				mcp: {
-					path: "/mcp",
-					serverName: "test-mcp",
-					resource: { uri: "test://agents", name: "Agents", mimeType: "application/json" },
-				},
-			},
-			steps: [{ id: "a", node: "agents-node", type: "module", inputs: {} }],
-			nodes: { a: { inputs: {} } },
-		},
-	});
-}
-
-describe("McpTrigger — integration (real MCP SDK client over SSE + Streamable-HTTP)", () => {
-	let app: Hono;
-	let trigger: InstanceType<typeof McpTriggerClass>;
-	let httpServer: Server | null = null;
-
-	beforeEach(async () => {
-		WorkflowRegistry.resetInstance();
-		_setActiveMcpTrigger(null);
-		app = new Hono();
-
-		const nodes = new NodeMap();
-		nodes.addNode("echo-node", echoNode);
-		nodes.addNode("whoami-node", whoamiNode);
-		nodes.addNode("agents-node", agentsNode);
-		registerWorkflows();
-
-		trigger = new McpTriggerClass(app);
-		trigger.setNodeMap({ nodes });
-		await trigger.listen();
-
-		const port = nextPort++;
-		BASE = `http://localhost:${port}`;
-		await new Promise<void>((resolve) => {
-			httpServer = serve({ fetch: app.fetch, port }, () => resolve()) as Server;
-		});
-	});
-
-	afterEach(
-		() =>
-			new Promise<void>((resolve) => {
-				if (trigger) void trigger.stop();
-				if (httpServer) {
-					httpServer.close(() => {
-						httpServer = null;
-						WorkflowRegistry.resetInstance();
-						_setActiveMcpTrigger(null);
-						resolve();
-					});
-				} else {
-					WorkflowRegistry.resetInstance();
-					_setActiveMcpTrigger(null);
-					resolve();
-				}
-			}),
-	);
-
-	it("lists + calls a tool over Streamable-HTTP", async () => {
-		const client = new Client({ name: "test-client", version: "1.0.0" }, { capabilities: {} });
-		const transport = new StreamableHTTPClientTransport(new URL(`${BASE}/mcp`));
-		await client.connect(transport);
-
-		const tools = await client.listTools();
-		expect(tools.tools.map((t) => t.name)).toContain("echo_tool");
-		const echo = tools.tools.find((t) => t.name === "echo_tool");
-		expect(echo?.description).toBe("Echo the input back");
-		// inputSchema generated from the workflow's Zod input
-		expect(echo?.inputSchema?.type).toBe("object");
-		expect(Object.keys((echo?.inputSchema?.properties ?? {}) as object)).toContain("msg");
-
-		const result = (await client.callTool({ name: "echo_tool", arguments: { msg: "hello" } })) as {
-			content: Array<{ type: string; text: string }>;
-			isError?: boolean;
-		};
-		expect(result.isError).toBeFalsy();
-		const payload = JSON.parse(result.content[0].text) as { echoed: string; upper: string };
-		expect(payload).toEqual({ echoed: "hello", upper: "HELLO" });
-
-		await client.close();
-	}, 20_000);
-
-	it("lists + calls a tool over SSE (GET /mcp/sse + POST /mcp/messages)", async () => {
-		const client = new Client({ name: "test-client-sse", version: "1.0.0" }, { capabilities: {} });
-		const transport = new SSEClientTransport(new URL(`${BASE}/mcp/sse`));
-		await client.connect(transport);
-
-		const tools = await client.listTools();
-		expect(tools.tools.map((t) => t.name)).toContain("echo_tool");
-
-		const result = (await client.callTool({ name: "echo_tool", arguments: { msg: "world" } })) as {
-			content: Array<{ type: string; text: string }>;
-			isError?: boolean;
-		};
-		expect(result.isError).toBeFalsy();
-		const payload = JSON.parse(result.content[0].text) as { echoed: string; upper: string };
-		expect(payload).toEqual({ echoed: "world", upper: "WORLD" });
-
-		await client.close();
-	}, 20_000);
-
-	it("returns an MCP tool error (not a transport crash) for an unknown tool", async () => {
-		const client = new Client({ name: "test-client-err", version: "1.0.0" }, { capabilities: {} });
-		const transport = new StreamableHTTPClientTransport(new URL(`${BASE}/mcp`));
-		await client.connect(transport);
-
-		const result = (await client.callTool({ name: "does_not_exist", arguments: {} })) as {
-			content: Array<{ type: string; text: string }>;
-			isError?: boolean;
-		};
-		expect(result.isError).toBe(true);
-		expect(result.content[0].text).toMatch(/unknown tool/i);
-
-		await client.close();
-	}, 20_000);
-
-	it("lists + reads an MCP resource", async () => {
-		const client = new Client({ name: "test-client-res", version: "1.0.0" }, { capabilities: {} });
-		const transport = new StreamableHTTPClientTransport(new URL(`${BASE}/mcp`));
-		await client.connect(transport);
-
-		const resources = await client.listResources();
-		expect(resources.resources.map((r) => r.uri)).toContain("test://agents");
-
-		const read = await client.readResource({ uri: "test://agents" });
-		const payload = JSON.parse(read.contents[0].text as string) as { agents: string[] };
-		expect(payload.agents).toEqual(["codebase", "infra"]);
-
-		await client.close();
-	}, 20_000);
-
-	it("parses x-user-context and passes it to the workflow ctx", async () => {
-		const userCtx = Buffer.from(JSON.stringify({ userId: "u-1", email: "dev@tetrix.io" }), "utf-8").toString("base64");
-		const client = new Client({ name: "test-client-ctx", version: "1.0.0" }, { capabilities: {} });
-		const transport = new StreamableHTTPClientTransport(new URL(`${BASE}/mcp`), {
-			requestInit: { headers: { "x-user-context": userCtx } },
-		});
-		await client.connect(transport);
-
-		const result = (await client.callTool({ name: "whoami", arguments: {} })) as {
-			content: Array<{ type: string; text: string }>;
-		};
-		const payload = JSON.parse(result.content[0].text) as { userId?: string; email?: string };
-		expect(payload).toEqual({ userId: "u-1", email: "dev@tetrix.io" });
-
-		await client.close();
-	}, 20_000);
-});

package/src/McpTrigger.ts

@@ -1,555 +0,0 @@
-/**
- * McpTrigger — Model Context Protocol trigger. Exposes Blok workflows as
- * MCP **tools** (and **resources**) to external clients (Cursor, Claude
- * Code, …) over two transports multiplexed on the shared Hono port:
- *
- *   - **SSE (legacy 2024-11-05)** — `GET <path>/sse` opens the stream and
- *     announces `POST <path>/messages?sessionId=…` for JSON-RPC. This is the
- *     2-endpoint shape existing IDE configs expect (drop-in parity).
- *   - **Streamable-HTTP** — a single `<path>` endpoint (the current official
- *     remote transport), served statelessly via the SDK's web-standard
- *     transport directly off `c.req.raw`.
- *
- * **Authoring surface** — a workflow opts in with `trigger.mcp`:
- *
- * ```ts
- * export default workflow({
- *   name: "search_code",
- *   version: "1.0.0",
- *   input: z.object({ query: z.string(), limit: z.number().optional() }),
- *   trigger: { mcp: { path: "/mcp", serverName: "tetrix-platform",
- *                     tool: { description: "Full-text search the indexed code" } } },
- *   steps: [ { id: "search", use: "@tetrix/meili-search", inputs: { query: $.req.body.query } } ],
- * });
- * ```
- *
- * Every workflow sharing the same `path` + `serverName` is aggregated into one
- * MCP server. Each tool's `inputSchema` is generated from the workflow's `input`
- * Zod schema (via zod-to-json-schema). On `tools/call` the trigger runs the
- * mapped workflow through the runner — so every call is a Blok Studio run with
- * tracing / retries / idempotency for free.
- *
- * **Hono integration:** identical to `SSETrigger`/`WebhookTrigger` — accepts the
- * shared `Hono` app + an optional `HttpTriggerLike` exposing `addPreCatchAllHook`
- * so routes register AFTER the workflow registry is populated but BEFORE the
- * legacy `/:workflow{.+}` catch-all.
- *
- * **Identity:** an `x-user-context` header (or `?user_context=`) carrying base64
- * `{userId,email}` is parsed per connection and passed to the workflow ctx for
- * credential injection. It is NOT access control — there is no scoping here
- * (that's the app's call). Tokens are never logged (the global sanitizer middleware
- * handles redaction).
- */
-
-import type { IncomingMessage, ServerResponse } from "node:http";
-import {
-	DefaultLogger,
-	type GlobalOptions as RunnerGlobalOptions,
-	TriggerBase,
-	WorkflowRegistry,
-} from "@blokjs/runner";
-import type { Context, RequestContext } from "@blokjs/shared";
-import { RESPONSE_ALREADY_SENT } from "@hono/node-server/utils/response";
-import { Server as McpSdkServer } from "@modelcontextprotocol/sdk/server/index.js";
-import { SSEServerTransport } from "@modelcontextprotocol/sdk/server/sse.js";
-import { WebStandardStreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js";
-import {
-	CallToolRequestSchema,
-	ListResourcesRequestSchema,
-	ListToolsRequestSchema,
-	ReadResourceRequestSchema,
-} from "@modelcontextprotocol/sdk/types.js";
-import { type Span, SpanStatusCode, metrics, trace } from "@opentelemetry/api";
-import type { Hono, Context as HonoContext } from "hono";
-import { v4 as uuid } from "uuid";
-import { zodToJsonSchema } from "zod-to-json-schema";
-
-// -----------------------------------------------------------------------------
-// Types
-// -----------------------------------------------------------------------------
-
-/** Parsed `x-user-context` identity (credential injection only — never scoping). */
-export interface McpUserContext {
-	userId: string;
-	email: string;
-}
-
-type McpTransportKind = "sse" | "streamable-http";
-
-interface McpToolMeta {
-	name?: string;
-	description?: string;
-}
-interface McpResourceMeta {
-	uri: string;
-	name?: string;
-	description?: string;
-	mimeType?: string;
-}
-
-/** Loosely-read `trigger.mcp` config (validated at workflow load by the helper). */
-interface McpTriggerConfig {
-	path: string;
-	serverName?: string;
-	serverVersion?: string;
-	transports?: McpTransportKind[];
-	tool?: McpToolMeta;
-	resource?: McpResourceMeta;
-	middleware?: string[];
-}
-
-interface HttpTriggerLike {
-	addPreCatchAllHook(cb: () => void | Promise<void>): void;
-}
-
-/** A workflow exposed as an MCP tool. */
-interface ToolEntry {
-	workflowName: string;
-	toolName: string;
-	description: string;
-	// biome-ignore lint/suspicious/noExplicitAny: workflow `input` is an opaque ZodType
-	inputZod: any | undefined;
-}
-
-/** A workflow exposed as an MCP resource. */
-interface ResourceEntry {
-	workflowName: string;
-	uri: string;
-	name: string;
-	description?: string;
-	mimeType: string;
-}
-
-/** All workflows that share a (path, serverName) form one MCP server. */
-interface ServerGroup {
-	path: string;
-	serverName: string;
-	serverVersion: string;
-	transports: McpTransportKind[];
-	tools: ToolEntry[];
-	resources: ResourceEntry[];
-}
-
-const DEFAULT_SERVER_NAME = "blok-mcp";
-const DEFAULT_SERVER_VERSION = "1.0.0";
-const DEFAULT_TRANSPORTS: McpTransportKind[] = ["sse", "streamable-http"];
-
-// -----------------------------------------------------------------------------
-// Helpers
-// -----------------------------------------------------------------------------
-
-/** Parse a base64-encoded `{userId,email}` identity string. Returns null on any failure. */
-export function parseUserContext(value: string | undefined | null): McpUserContext | null {
-	if (!value || typeof value !== "string") return null;
-	try {
-		const decoded = Buffer.from(value, "base64").toString("utf-8");
-		if (!decoded || decoded.trim() === "null") return null;
-		const ctx = JSON.parse(decoded) as { userId?: string; email?: string };
-		if (!ctx || typeof ctx.userId !== "string") return null;
-		return { userId: ctx.userId, email: typeof ctx.email === "string" ? ctx.email : "unknown" };
-	} catch {
-		return null;
-	}
-}
-
-/** Convert a Zod schema to a JSON-Schema object suitable for an MCP tool `inputSchema`. */
-// biome-ignore lint/suspicious/noExplicitAny: zod schema is opaque here
-function toInputJsonSchema(inputZod: any | undefined): { type: "object"; [k: string]: unknown } {
-	const empty = { type: "object" as const, properties: {}, additionalProperties: true };
-	if (!inputZod || typeof inputZod !== "object" || typeof inputZod.safeParse !== "function") {
-		return empty;
-	}
-	try {
-		const json = zodToJsonSchema(inputZod, { target: "jsonSchema7", $refStrategy: "none" }) as Record<string, unknown>;
-		// biome-ignore lint/performance/noDelete: strip JSON-Schema meta the MCP client doesn't need
-		delete json.$schema;
-		if (json.type !== "object") {
-			return { ...empty, _wrapped: json } as { type: "object"; [k: string]: unknown };
-		}
-		return json as { type: "object"; [k: string]: unknown };
-	} catch {
-		return empty;
-	}
-}
-
-// -----------------------------------------------------------------------------
-// Trigger
-// -----------------------------------------------------------------------------
-
-export default class McpTrigger extends TriggerBase {
-	protected nodeMap: RunnerGlobalOptions = {} as RunnerGlobalOptions;
-	protected readonly logger = new DefaultLogger();
-	protected readonly tracer = trace.getTracer(
-		process.env.PROJECT_NAME || "trigger-mcp-workflow",
-		process.env.PROJECT_VERSION || "0.0.1",
-	);
-	private readonly meter = metrics.getMeter("blok");
-	private readonly counterToolCalls = this.meter.createCounter("blok_mcp_tool_calls_total", {
-		description: "MCP tools/call dispatches.",
-		unit: "1",
-	});
-	private readonly counterSessions = this.meter.createCounter("blok_mcp_sse_sessions_total", {
-		description: "MCP SSE sessions opened.",
-		unit: "1",
-	});
-
-	// biome-ignore lint/suspicious/noExplicitAny: Hono generic propagation (matches SSE/WS triggers)
-	private readonly app: Hono<any, any, any>;
-	private readonly httpTrigger: HttpTriggerLike | null;
-	private wired = false;
-
-	/** Live SSE sessions: sessionId → { transport, server, userContext }. */
-	private sseSessions = new Map<
-		string,
-		{ transport: SSEServerTransport; server: McpSdkServer; userContext: McpUserContext | null }
-	>();
-
-	// biome-ignore lint/suspicious/noExplicitAny: matches `app` field generic
-	constructor(app: Hono<any, any, any>, httpTrigger?: HttpTriggerLike) {
-		super();
-		this.app = app;
-		this.httpTrigger = httpTrigger ?? null;
-		_setActiveMcpTrigger(this);
-	}
-
-	/** Inject the runner's GlobalOptions (nodes + workflows). Called before `listen()`. */
-	setNodeMap(nodeMap: RunnerGlobalOptions): void {
-		this.nodeMap = nodeMap;
-	}
-
-	async listen(): Promise<number> {
-		const startTime = this.startCounter();
-		if (this.wired) {
-			this.logger.log("[blok][mcp] listen() called twice; ignoring");
-			return this.endCounter(startTime);
-		}
-		this.wired = true;
-
-		if (this.httpTrigger) {
-			this.httpTrigger.addPreCatchAllHook(() => this.registerRoutesFromRegistry());
-		} else {
-			this.registerRoutesFromRegistry();
-		}
-		return this.endCounter(startTime);
-	}
-
-	async stop(): Promise<void> {
-		for (const { transport } of this.sseSessions.values()) {
-			try {
-				await transport.close();
-			} catch {
-				/* ignore */
-			}
-		}
-		this.sseSessions.clear();
-		this.wired = false;
-		if (_getActiveMcpTrigger() === this) _setActiveMcpTrigger(null);
-		this.destroyMonitoring();
-		this.logger.log("[blok][mcp] stopped");
-	}
-
-	getStats(): { sessions: number } {
-		return { sessions: this.sseSessions.size };
-	}
-
-	// ---------------------------------------------------------------------------
-	// Registry scan + grouping
-	// ---------------------------------------------------------------------------
-
-	private registerRoutesFromRegistry(): void {
-		const groups = this.getServerGroups();
-		if (groups.length === 0) {
-			this.logger.log("[blok][mcp] no workflows with trigger.mcp found");
-			return;
-		}
-		for (const group of groups) {
-			this.registerGroupRoutes(group);
-		}
-	}
-
-	private getServerGroups(): ServerGroup[] {
-		const registry = WorkflowRegistry.getInstance();
-		const byPath = new Map<string, ServerGroup>();
-
-		for (const entry of registry.list()) {
-			// Workflows registered as builders expose config on `_config`; plain
-			// objects (tests / JSON) expose it at the top level.
-			const wf = (entry.workflow as { _config?: unknown })?._config ?? entry.workflow;
-			const cfg = (wf as { trigger?: { mcp?: McpTriggerConfig } })?.trigger?.mcp;
-			if (!cfg || typeof cfg.path !== "string") continue;
-
-			const path = cfg.path;
-			let group = byPath.get(path);
-			if (!group) {
-				group = {
-					path,
-					serverName: cfg.serverName || DEFAULT_SERVER_NAME,
-					serverVersion: cfg.serverVersion || DEFAULT_SERVER_VERSION,
-					transports: Array.isArray(cfg.transports) && cfg.transports.length > 0 ? cfg.transports : DEFAULT_TRANSPORTS,
-					tools: [],
-					resources: [],
-				};
-				byPath.set(path, group);
-			}
-
-			if (cfg.resource && typeof cfg.resource.uri === "string") {
-				group.resources.push({
-					workflowName: entry.name,
-					uri: cfg.resource.uri,
-					name: cfg.resource.name || entry.name,
-					description: cfg.resource.description,
-					mimeType: cfg.resource.mimeType || "application/json",
-				});
-			} else {
-				const inputZod = (wf as { input?: unknown })?.input;
-				group.tools.push({
-					workflowName: entry.name,
-					toolName: cfg.tool?.name || entry.name,
-					description: cfg.tool?.description || `Run the "${entry.name}" workflow.`,
-					inputZod,
-				});
-			}
-		}
-
-		return [...byPath.values()];
-	}
-
-	// ---------------------------------------------------------------------------
-	// MCP server factory (one per request/session, bound to a user context)
-	// ---------------------------------------------------------------------------
-
-	private buildServer(group: ServerGroup, getUserContext: () => McpUserContext | null): McpSdkServer {
-		const server = new McpSdkServer(
-			{ name: group.serverName, version: group.serverVersion },
-			{ capabilities: { tools: {}, resources: {} } },
-		);
-
-		server.setRequestHandler(ListToolsRequestSchema, async () => ({
-			tools: group.tools.map((t) => ({
-				name: t.toolName,
-				description: t.description,
-				inputSchema: toInputJsonSchema(t.inputZod),
-			})),
-		}));
-
-		server.setRequestHandler(CallToolRequestSchema, async (req) => {
-			const toolName = req.params.name;
-			const tool = group.tools.find((t) => t.toolName === toolName);
-			if (!tool) {
-				return { content: [{ type: "text", text: `Unknown tool: ${toolName}` }], isError: true };
-			}
-			const args = (req.params.arguments ?? {}) as Record<string, unknown>;
-			return this.dispatchTool(tool, args, getUserContext());
-		});
-
-		if (group.resources.length > 0) {
-			server.setRequestHandler(ListResourcesRequestSchema, async () => ({
-				resources: group.resources.map((r) => ({
-					uri: r.uri,
-					name: r.name,
-					description: r.description,
-					mimeType: r.mimeType,
-				})),
-			}));
-
-			server.setRequestHandler(ReadResourceRequestSchema, async (req) => {
-				const uri = req.params.uri;
-				const resource = group.resources.find((r) => r.uri === uri);
-				if (!resource) throw new Error(`Unknown resource: ${uri}`);
-				const result = await this.dispatchResource(resource, getUserContext());
-				const text = typeof result === "string" ? result : JSON.stringify(result, null, 2);
-				return { contents: [{ uri: resource.uri, mimeType: resource.mimeType, text }] };
-			});
-		}
-
-		return server;
-	}
-
-	// ---------------------------------------------------------------------------
-	// Workflow dispatch (tools/call + resources/read run through the runner)
-	// ---------------------------------------------------------------------------
-
-	private async dispatchTool(
-		tool: ToolEntry,
-		args: Record<string, unknown>,
-		userContext: McpUserContext | null,
-	): Promise<{ content: Array<{ type: "text"; text: string }>; isError?: boolean }> {
-		this.counterToolCalls.add(1, { tool: tool.toolName });
-		try {
-			const data = await this.runWorkflow(tool.workflowName, args, userContext, `mcp.tool:${tool.toolName}`);
-			const text = typeof data === "string" ? data : JSON.stringify(data, null, 2);
-			return { content: [{ type: "text", text }] };
-		} catch (err) {
-			const msg = err instanceof Error ? err.message : String(err);
-			this.logger.error(`[blok][mcp] tool "${tool.toolName}" failed: ${msg}`);
-			// Tool failure → MCP tool error result, NOT a transport crash.
-			return { content: [{ type: "text", text: `Error: ${msg}` }], isError: true };
-		}
-	}
-
-	private async dispatchResource(resource: ResourceEntry, userContext: McpUserContext | null): Promise<unknown> {
-		return this.runWorkflow(resource.workflowName, {}, userContext, `mcp.resource:${resource.uri}`);
-	}
-
-	/**
-	 * Run a workflow through the runner and return `ctx.response.data`. Mirrors
-	 * the WebhookTrigger request→response dispatch (init → context → middleware →
-	 * run). MCP tool calls within a session are serial, matching the shared
-	 * `this.configuration` lifecycle the other triggers use.
-	 */
-	private async runWorkflow(
-		workflowName: string,
-		args: Record<string, unknown>,
-		userContext: McpUserContext | null,
-		spanLabel: string,
-	): Promise<unknown> {
-		const requestId = uuid();
-		return this.tracer.startActiveSpan(`mcp:${workflowName}`, async (span: Span) => {
-			try {
-				const registry = WorkflowRegistry.getInstance();
-				const entry = registry.get(workflowName);
-				if (!entry) throw new Error(`workflow "${workflowName}" not found in registry`);
-				await this.configuration.init(workflowName, this.nodeMap, entry.workflow);
-
-				const headers: Record<string, string> = {};
-				if (userContext) {
-					// Carry identity to the workflow exactly as HTTP would (base64 header).
-					headers["x-user-context"] = Buffer.from(JSON.stringify(userContext), "utf-8").toString("base64");
-				}
-
-				const ctx: Context = this.createContext(undefined, workflowName, requestId);
-				ctx.request = {
-					body: args,
-					headers,
-					params: {},
-					query: {},
-				} as unknown as RequestContext;
-				(ctx as Record<string, unknown>)._mcp = { userContext };
-
-				await this.applyMiddlewareChain(ctx, this.nodeMap);
-				await this.run(ctx);
-
-				span.setAttribute("workflow_name", workflowName);
-				span.setAttribute("mcp_label", spanLabel);
-				span.setStatus({ code: SpanStatusCode.OK });
-				return ctx.response?.data;
-			} catch (err) {
-				const msg = err instanceof Error ? err.message : String(err);
-				span.recordException(err as Error);
-				span.setStatus({ code: SpanStatusCode.ERROR, message: msg });
-				throw err;
-			} finally {
-				span.end();
-			}
-		});
-	}
-
-	// ---------------------------------------------------------------------------
-	// Route registration (SSE + Streamable-HTTP)
-	// ---------------------------------------------------------------------------
-
-	private registerGroupRoutes(group: ServerGroup): void {
-		this.logger.log(
-			`[blok][mcp] server "${group.serverName}" at ${group.path} — ${group.tools.length} tool(s), ${group.resources.length} resource(s), transports=[${group.transports.join(",")}]`,
-		);
-
-		if (group.transports.includes("sse")) {
-			this.registerSseRoutes(group);
-		}
-		if (group.transports.includes("streamable-http")) {
-			this.registerStreamableHttpRoute(group);
-		}
-	}
-
-	private registerSseRoutes(group: ServerGroup): void {
-		const ssePath = `${group.path}/sse`;
-		const messagesPath = `${group.path}/messages`;
-		this.logger.log(`[blok][mcp]   GET  ${ssePath}   POST ${messagesPath}  (sse)`);
-
-		// GET <path>/sse — open the SSE stream; SDK announces the messages endpoint.
-		this.app.get(ssePath, async (c: HonoContext) => {
-			const env = c.env as unknown as { incoming: IncomingMessage; outgoing: ServerResponse };
-			if (!env?.outgoing) {
-				return c.text("MCP SSE transport requires the Node server (@hono/node-server).", 500);
-			}
-			const rawUserCtx =
-				c.req.header("x-user-context") || (new URL(c.req.url).searchParams.get("user_context") ?? undefined);
-			const userContext = parseUserContext(rawUserCtx);
-
-			const transport = new SSEServerTransport(messagesPath, env.outgoing);
-			const sessionId = transport.sessionId;
-			const server = this.buildServer(group, () => this.sseSessions.get(sessionId)?.userContext ?? null);
-			this.sseSessions.set(sessionId, { transport, server, userContext });
-			this.counterSessions.add(1, { server: group.serverName });
-
-			transport.onclose = () => {
-				this.sseSessions.delete(sessionId);
-			};
-
-			try {
-				await server.connect(transport);
-			} catch (err) {
-				this.sseSessions.delete(sessionId);
-				const msg = err instanceof Error ? err.message : String(err);
-				this.logger.error(`[blok][mcp] sse connect failed: ${msg}`);
-			}
-			return RESPONSE_ALREADY_SENT;
-		});
-
-		// POST <path>/messages?sessionId=… — JSON-RPC messages for an open stream.
-		this.app.post(messagesPath, async (c: HonoContext) => {
-			const env = c.env as unknown as { incoming: IncomingMessage; outgoing: ServerResponse };
-			const sessionId = new URL(c.req.url).searchParams.get("sessionId") ?? undefined;
-			if (!sessionId) return c.text("Missing sessionId query parameter", 400);
-			const session = this.sseSessions.get(sessionId);
-			if (!session) return c.text("Session not found", 404);
-			const body = await c.req.json().catch(() => undefined);
-			try {
-				await session.transport.handlePostMessage(env.incoming, env.outgoing, body);
-			} catch (err) {
-				const msg = err instanceof Error ? err.message : String(err);
-				this.logger.error(`[blok][mcp] handlePostMessage failed: ${msg}`);
-				if (!env.outgoing.headersSent) return c.text("Error handling MCP message", 500);
-			}
-			return RESPONSE_ALREADY_SENT;
-		});
-	}
-
-	private registerStreamableHttpRoute(group: ServerGroup): void {
-		this.logger.log(`[blok][mcp]   ALL  ${group.path}  (streamable-http)`);
-
-		// Stateless Streamable-HTTP: a fresh server + transport per request, served
-		// directly off the Fetch `Request` (works on any Hono runtime).
-		this.app.all(group.path, async (c: HonoContext) => {
-			const rawUserCtx =
-				c.req.header("x-user-context") || (new URL(c.req.url).searchParams.get("user_context") ?? undefined);
-			const userContext = parseUserContext(rawUserCtx);
-
-			const server = this.buildServer(group, () => userContext);
-			const transport = new WebStandardStreamableHTTPServerTransport({ sessionIdGenerator: undefined });
-			try {
-				await server.connect(transport);
-				const res = await transport.handleRequest(c.req.raw);
-				return res;
-			} catch (err) {
-				const msg = err instanceof Error ? err.message : String(err);
-				this.logger.error(`[blok][mcp] streamable-http request failed: ${msg}`);
-				return c.json({ jsonrpc: "2.0", error: { code: -32603, message: msg }, id: null }, 500);
-			}
-		});
-	}
-}
-
-// -----------------------------------------------------------------------------
-// Singleton accessor (parity with SSE/Webhook triggers)
-// -----------------------------------------------------------------------------
-
-let activeTrigger: McpTrigger | null = null;
-export function _setActiveMcpTrigger(trigger: McpTrigger | null): void {
-	activeTrigger = trigger;
-}
-export function _getActiveMcpTrigger(): McpTrigger | null {
-	return activeTrigger;
-}
-
-export type { McpTriggerConfig };

package/src/index.ts

@@ -1,41 +0,0 @@
-/**
- * @blokjs/trigger-mcp
- *
- * Model Context Protocol (MCP) trigger for Blok workflows. Exposes workflows as
- * MCP tools + resources to external clients (Cursor, Claude Code, …) over SSE
- * (legacy 2-endpoint) and Streamable-HTTP transports, multiplexed on the shared
- * Hono port alongside HTTP / WS / SSE / Webhook routes — same registry, same
- * runner, same Studio tracing.
- *
- * A workflow opts in with `trigger.mcp` and declares its tool input via the
- * workflow's `input` Zod schema:
- *
- * ```ts
- * import { workflow, $ } from "@blokjs/helper";
- * import { z } from "zod";
- *
- * export default workflow({
- *   name: "search_code",
- *   version: "1.0.0",
- *   input: z.object({ query: z.string() }),
- *   trigger: { mcp: { path: "/mcp", serverName: "tetrix-platform",
- *                     tool: { description: "Search the indexed codebase" } } },
- *   steps: [ { id: "s", use: "@tetrix/meili-search", inputs: { query: $.req.body.query } } ],
- * });
- * ```
- *
- * Mounting (in an app's HTTP entry, mirroring SSE/Webhook):
- *
- * ```ts
- * const mcp = new McpTrigger(httpTrigger.getApp(), httpTrigger);
- * mcp.setNodeMap({ nodes, workflows });
- * await mcp.listen();
- * ```
- */
-
-import McpTrigger, { _getActiveMcpTrigger, _setActiveMcpTrigger, parseUserContext } from "./McpTrigger";
-
-export default McpTrigger;
-export { McpTrigger, _getActiveMcpTrigger, _setActiveMcpTrigger, parseUserContext };
-export type { McpTriggerConfig, McpUserContext } from "./McpTrigger";
-export type { McpTriggerOpts } from "@blokjs/helper";

package/tsconfig.json

@@ -1,32 +0,0 @@
-{
-	"ts-node": {
-		"transpileOnly": true
-	},
-	"compilerOptions": {
-		"target": "ES2022",
-		"module": "es2022",
-		"lib": ["ES2022"],
-		"declaration": true,
-		"strict": true,
-		"noImplicitAny": true,
-		"strictNullChecks": true,
-		"noImplicitThis": true,
-		"alwaysStrict": true,
-		"noUnusedLocals": false,
-		"noUnusedParameters": false,
-		"noImplicitReturns": true,
-		"noFallthroughCasesInSwitch": false,
-		"inlineSourceMap": true,
-		"inlineSources": true,
-		"experimentalDecorators": true,
-		"emitDecoratorMetadata": true,
-		"skipLibCheck": true,
-		"esModuleInterop": true,
-		"resolveJsonModule": true,
-		"outDir": "./dist",
-		"rootDir": "./src",
-		"moduleResolution": "bundler"
-	},
-	"include": ["src/**/*"],
-	"exclude": ["node_modules", "dist", "**/*.test.ts"]
-}