@blokjs/trigger-mcp 0.6.12

package/dist/index.d.ts

@@ -0,0 +1,39 @@
+/**
+ * @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/dist/index.js

@@ -0,0 +1,38 @@
+/**
+ * @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 };
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi9zcmMvaW5kZXgudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUE7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7OztHQWlDRztBQUVILE9BQU8sVUFBVSxFQUFFLEVBQUUsb0JBQW9CLEVBQUUsb0JBQW9CLEVBQUUsZ0JBQWdCLEVBQUUsTUFBTSxjQUFjLENBQUM7QUFFeEcsZUFBZSxVQUFVLENBQUM7QUFDMUIsT0FBTyxFQUFFLFVBQVUsRUFBRSxvQkFBb0IsRUFBRSxvQkFBb0IsRUFBRSxnQkFBZ0IsRUFBRSxDQUFDIiwic291cmNlc0NvbnRlbnQiOlsiLyoqXG4gKiBAYmxva2pzL3RyaWdnZXItbWNwXG4gKlxuICogTW9kZWwgQ29udGV4dCBQcm90b2NvbCAoTUNQKSB0cmlnZ2VyIGZvciBCbG9rIHdvcmtmbG93cy4gRXhwb3NlcyB3b3JrZmxvd3MgYXNcbiAqIE1DUCB0b29scyArIHJlc291cmNlcyB0byBleHRlcm5hbCBjbGllbnRzIChDdXJzb3IsIENsYXVkZSBDb2RlLCDigKYpIG92ZXIgU1NFXG4gKiAobGVnYWN5IDItZW5kcG9pbnQpIGFuZCBTdHJlYW1hYmxlLUhUVFAgdHJhbnNwb3J0cywgbXVsdGlwbGV4ZWQgb24gdGhlIHNoYXJlZFxuICogSG9ubyBwb3J0IGFsb25nc2lkZSBIVFRQIC8gV1MgLyBTU0UgLyBXZWJob29rIHJvdXRlcyDigJQgc2FtZSByZWdpc3RyeSwgc2FtZVxuICogcnVubmVyLCBzYW1lIFN0dWRpbyB0cmFjaW5nLlxuICpcbiAqIEEgd29ya2Zsb3cgb3B0cyBpbiB3aXRoIGB0cmlnZ2VyLm1jcGAgYW5kIGRlY2xhcmVzIGl0cyB0b29sIGlucHV0IHZpYSB0aGVcbiAqIHdvcmtmbG93J3MgYGlucHV0YCBab2Qgc2NoZW1hOlxuICpcbiAqIGBgYHRzXG4gKiBpbXBvcnQgeyB3b3JrZmxvdywgJCB9IGZyb20gXCJAYmxva2pzL2hlbHBlclwiO1xuICogaW1wb3J0IHsgeiB9IGZyb20gXCJ6b2RcIjtcbiAqXG4gKiBleHBvcnQgZGVmYXVsdCB3b3JrZmxvdyh7XG4gKiAgIG5hbWU6IFwic2VhcmNoX2NvZGVcIixcbiAqICAgdmVyc2lvbjogXCIxLjAuMFwiLFxuICogICBpbnB1dDogei5vYmplY3QoeyBxdWVyeTogei5zdHJpbmcoKSB9KSxcbiAqICAgdHJpZ2dlcjogeyBtY3A6IHsgcGF0aDogXCIvbWNwXCIsIHNlcnZlck5hbWU6IFwidGV0cml4LXBsYXRmb3JtXCIsXG4gKiAgICAgICAgICAgICAgICAgICAgIHRvb2w6IHsgZGVzY3JpcHRpb246IFwiU2VhcmNoIHRoZSBpbmRleGVkIGNvZGViYXNlXCIgfSB9IH0sXG4gKiAgIHN0ZXBzOiBbIHsgaWQ6IFwic1wiLCB1c2U6IFwiQHRldHJpeC9tZWlsaS1zZWFyY2hcIiwgaW5wdXRzOiB7IHF1ZXJ5OiAkLnJlcS5ib2R5LnF1ZXJ5IH0gfSBdLFxuICogfSk7XG4gKiBgYGBcbiAqXG4gKiBNb3VudGluZyAoaW4gYW4gYXBwJ3MgSFRUUCBlbnRyeSwgbWlycm9yaW5nIFNTRS9XZWJob29rKTpcbiAqXG4gKiBgYGB0c1xuICogY29uc3QgbWNwID0gbmV3IE1jcFRyaWdnZXIoaHR0cFRyaWdnZXIuZ2V0QXBwKCksIGh0dHBUcmlnZ2VyKTtcbiAqIG1jcC5zZXROb2RlTWFwKHsgbm9kZXMsIHdvcmtmbG93cyB9KTtcbiAqIGF3YWl0IG1jcC5saXN0ZW4oKTtcbiAqIGBgYFxuICovXG5cbmltcG9ydCBNY3BUcmlnZ2VyLCB7IF9nZXRBY3RpdmVNY3BUcmlnZ2VyLCBfc2V0QWN0aXZlTWNwVHJpZ2dlciwgcGFyc2VVc2VyQ29udGV4dCB9IGZyb20gXCIuL01jcFRyaWdnZXJcIjtcblxuZXhwb3J0IGRlZmF1bHQgTWNwVHJpZ2dlcjtcbmV4cG9ydCB7IE1jcFRyaWdnZXIsIF9nZXRBY3RpdmVNY3BUcmlnZ2VyLCBfc2V0QWN0aXZlTWNwVHJpZ2dlciwgcGFyc2VVc2VyQ29udGV4dCB9O1xuZXhwb3J0IHR5cGUgeyBNY3BUcmlnZ2VyQ29uZmlnLCBNY3BVc2VyQ29udGV4dCB9IGZyb20gXCIuL01jcFRyaWdnZXJcIjtcbmV4cG9ydCB0eXBlIHsgTWNwVHJpZ2dlck9wdHMgfSBmcm9tIFwiQGJsb2tqcy9oZWxwZXJcIjtcbiJdfQ==

package/package.json

@@ -0,0 +1,38 @@
+{
+	"name": "@blokjs/trigger-mcp",
+	"version": "0.6.12",
+	"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",
+	"types": "dist/index.d.ts",
+	"scripts": {
+		"build": "rm -rf dist && bun run tsc",
+		"build:dev": "tsc --watch",
+		"test": "vitest run",
+		"test:dev": "vitest"
+	},
+	"author": "Deskree Technologies Inc.",
+	"license": "Apache-2.0",
+	"dependencies": {
+		"@blokjs/helper": "^0.6.12",
+		"@blokjs/runner": "^0.6.12",
+		"@blokjs/shared": "^0.6.12",
+		"@modelcontextprotocol/sdk": "^1.29.0",
+		"@opentelemetry/api": "^1.9.0",
+		"hono": "^4.11.7",
+		"uuid": "^11.1.0",
+		"zod": "^3.24.2",
+		"zod-to-json-schema": "^3.24.0"
+	},
+	"devDependencies": {
+		"@hono/node-server": "^1.19.9",
+		"@types/node": "^22.15.21",
+		"@types/uuid": "^11.0.0",
+		"typescript": "^5.8.3",
+		"vitest": "^4.0.18"
+	},
+	"private": false,
+	"publishConfig": {
+		"access": "public"
+	}
+}

package/src/McpTrigger.integration.test.ts

@@ -0,0 +1,277 @@
+/**
+ * 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);
+});