@classytic/arc 2.8.5 → 2.9.1

package/dist/integrations/mcp/index.d.mts

@@ -1,5 +1,5 @@
-import { qt as ResourceDefinition } from "../../interface-CMRutPfe.mjs";
-import { a as McpAuthResolver, c as McpResourceConfig, d as SessionEntry, f as ToolAnnotations, i as CrudOperation, l as PromptDefinition, m as ToolDefinition, n as CallToolResult, o as McpAuthResult, p as ToolContext, r as CreateMcpServerConfig, s as McpPluginOptions, t as BetterAuthHandler, u as PromptResult } from "../../types-BsbNMEDR.mjs";
+import { Kt as ResourceDefinition } from "../../interface-YrWsmKqE.mjs";
+import { a as McpAuthResolver, c as McpResourceConfig, d as SessionEntry, f as ToolAnnotations, i as CrudOperation, l as PromptDefinition, m as ToolDefinition, n as CallToolResult, o as McpAuthResult, p as ToolContext, r as CreateMcpServerConfig, s as McpPluginOptions, t as BetterAuthHandler, u as PromptResult } from "../../types-CoSzA-s-.mjs";
 import { FastifyPluginAsync } from "fastify";
 import { z } from "zod";
 
@@ -233,14 +233,32 @@ declare class McpSessionCache {
 }
 //#endregion
 //#region src/integrations/mcp/mcpPlugin.d.ts
+/**
+ * Per-prefix MCP registration info. A single fastify instance can register
+ * mcpPlugin multiple times under different prefixes (e.g. `/mcp/catalog`,
+ * `/mcp/orders`). The decorator is a map keyed by prefix so multi-registration
+ * setups can inspect any endpoint's tool list, not just the first one.
+ */
+interface McpRegistration {
+  sessions: McpSessionCache | null;
+  toolNames: string[];
+  resourceNames: string[];
+  stateful: boolean;
+}
+interface McpDecorator {
+  /** Map of prefix → registration info. Iterate for all endpoints. */
+  registrations: Map<string, McpRegistration>;
+  /** Shortcut for the first registered prefix (back-compat for single-endpoint apps) */
+  readonly sessions: McpSessionCache | null;
+  readonly toolNames: string[];
+  readonly resourceNames: string[];
+  readonly stateful: boolean;
+  /** Look up a specific prefix */
+  get(prefix: string): McpRegistration | undefined;
+}
 declare module "fastify" {
   interface FastifyInstance {
-    mcp?: {
-      sessions: McpSessionCache | null;
-      toolNames: string[];
-      resourceNames: string[];
-      stateful: boolean;
-    };
+    mcp?: McpDecorator;
   }
 }
 declare const mcpPlugin: FastifyPluginAsync<McpPluginOptions>;

package/dist/integrations/mcp/index.mjs

@@ -1,5 +1,5 @@
-import { n as fieldRulesToZod, r as createMcpServer, t as resourceToTools } from "../../resourceToTools-8s-EsCCe.mjs";
-import { createHash } from "node:crypto";
+import { n as fieldRulesToZod, r as createMcpServer, t as resourceToTools } from "../../resourceToTools-C3cWymnW.mjs";
+import { createHash, randomUUID } from "node:crypto";
 import fp from "fastify-plugin";
 //#region src/integrations/mcp/defineTool.ts
 /**
@@ -454,13 +454,46 @@ var McpSessionCache = class {
 };
 //#endregion
 //#region src/integrations/mcp/mcpPlugin.ts
+/**
+* @classytic/arc — MCP Plugin (Level 1)
+*
+* Fastify plugin that auto-generates MCP tools from Arc resources.
+*
+* Two transport modes:
+* - **Stateless** (default) — fresh server per request, no session tracking.
+*   Best for production, horizontal scaling, serverless, edge.
+* - **Stateful** — sessions cached with TTL, reused across requests.
+*   Use when you need server-initiated notifications or long-lived connections.
+*
+* Auth is NOT enforced — the plugin respects whatever auth mode you choose:
+* - `auth: false` — no auth, anonymous access (dev/testing/stdio)
+* - `auth: betterAuthInstance` — OAuth 2.1 via Better Auth's mcp() plugin
+* - `auth: async (headers) => {...}` — custom function (API key, JWT, gateway, etc.)
+*
+* @example
+* ```typescript
+* // Stateless (default) — production, scalable
+* await app.register(mcpPlugin, { resources, auth: false });
+*
+* // Stateful — when you need session persistence
+* await app.register(mcpPlugin, { resources, stateful: true, sessionTtlMs: 600000 });
+*
+* // Multiple MCP endpoints scoped to different resource groups
+* await app.register(mcpPlugin, { resources: catalogResources, prefix: '/mcp/catalog' });
+* await app.register(mcpPlugin, { resources: orderResources, prefix: '/mcp/orders' });
+* ```
+*/
 const mcpPluginImpl = async (fastify, options) => {
 	let StreamableHTTPServerTransport;
 	try {
 		StreamableHTTPServerTransport = (await import("@modelcontextprotocol/sdk/server/streamableHttp.js")).StreamableHTTPServerTransport;
+	} catch {
+		throw new Error("@modelcontextprotocol/sdk is required for MCP support. Install it: npm install @modelcontextprotocol/sdk");
+	}
+	try {
 		await import("zod");
 	} catch {
-		throw new Error("@modelcontextprotocol/sdk and zod are required for MCP support. Install them: npm install @modelcontextprotocol/sdk zod");
+		throw new Error("zod is required for MCP tool schemas. Install it: npm install zod");
 	}
 	let enabledResources;
 	if (options.include) {
@@ -516,18 +549,51 @@ const mcpPluginImpl = async (fastify, options) => {
 		registerStatelessRoutes(fastify, prefix, options, createServerInstance, StreamableHTTPServerTransport, authCache);
 	}
 	if (cache) fastify.addHook("onClose", async () => cache.close());
-	if (!fastify.hasDecorator("mcp")) fastify.decorate("mcp", {
+	const registration = {
 		sessions: cache,
 		toolNames: allTools.map((t) => t.name),
 		resourceNames: enabledResources.map((r) => r.name),
 		stateful
-	});
+	};
+	if (!fastify.hasDecorator("mcp")) {
+		const registrations = /* @__PURE__ */ new Map();
+		registrations.set(prefix, registration);
+		const first = () => registrations.values().next().value;
+		const decorator = {
+			registrations,
+			get(p) {
+				return registrations.get(p);
+			},
+			get sessions() {
+				return first()?.sessions ?? null;
+			},
+			get toolNames() {
+				return first()?.toolNames ?? [];
+			},
+			get resourceNames() {
+				return first()?.resourceNames ?? [];
+			},
+			get stateful() {
+				return first()?.stateful ?? false;
+			}
+		};
+		fastify.decorate("mcp", decorator);
+	} else {
+		const existing = fastify.mcp;
+		if (existing) {
+			if (existing.registrations.has(prefix)) throw new Error(`mcpPlugin: prefix "${prefix}" is already registered`);
+			existing.registrations.set(prefix, registration);
+		}
+	}
 };
 function registerStatelessRoutes(fastify, prefix, options, createServer, Transport, authCache) {
 	fastify.post(prefix, async (request, reply) => {
 		const authResult = await resolveMcpAuth(request.headers, options.auth ?? false, authCache);
 		if (!authResult && options.auth) {
-			fastify.log.warn("mcpPlugin: auth failed — returning 401 (client may silently drop server)");
+			fastify.log.warn({
+				msg: "mcpPlugin: auth failed",
+				status: 401
+			});
 			return reply.code(401).send({
 				jsonrpc: "2.0",
 				error: {
@@ -564,7 +630,10 @@ function registerStatefulRoutes(fastify, prefix, options, cache, createServer, T
 	fastify.post(prefix, async (request, reply) => {
 		const authResult = await resolveMcpAuth(request.headers, options.auth ?? false);
 		if (!authResult && options.auth) {
-			fastify.log.warn("mcpPlugin: auth failed — returning 401 (client may silently drop server)");
+			fastify.log.warn({
+				msg: "mcpPlugin: auth failed",
+				status: 401
+			});
 			return reply.code(401).send({
 				jsonrpc: "2.0",
 				error: {
@@ -592,15 +661,19 @@ function registerStatefulRoutes(fastify, prefix, options, cache, createServer, T
 			}
 		}
 		const authRef = { current: authResult };
-		const transport = new Transport({ sessionIdGenerator: void 0 });
-		await (await createServer(authRef)).connect(transport);
-		cache.set(transport.sessionId, {
-			transport,
-			lastAccessed: Date.now(),
-			organizationId: authResult?.organizationId ?? "",
-			auth: authResult,
-			authRef
+		const transport = new Transport({
+			sessionIdGenerator: () => randomUUID(),
+			onsessioninitialized: (newSessionId) => {
+				cache.set(newSessionId, {
+					transport,
+					lastAccessed: Date.now(),
+					organizationId: authResult?.organizationId ?? "",
+					auth: authResult,
+					authRef
+				});
+			}
 		});
+		await (await createServer(authRef)).connect(transport);
 		await transport.handleRequest(request.raw, reply.raw, request.body);
 	});
 	fastify.get(prefix, async (request, reply) => {
@@ -609,7 +682,10 @@ function registerStatefulRoutes(fastify, prefix, options, cache, createServer, T
 		const entry = cache.get(sessionId);
 		if (!entry) return reply.code(403).send({ error: "Unauthorized" });
 		if (options.auth) {
-			if (!isSessionOwner(entry, await resolveMcpAuth(request.headers, options.auth))) return reply.code(403).send({ error: "Unauthorized" });
+			const authResult = await resolveMcpAuth(request.headers, options.auth);
+			if (!isSessionOwner(entry, authResult)) return reply.code(403).send({ error: "Unauthorized" });
+			entry.auth = authResult;
+			entry.authRef.current = authResult;
 		}
 		cache.touch(sessionId);
 		await entry.transport.handleRequest(request.raw, reply.raw);
@@ -620,7 +696,10 @@ function registerStatefulRoutes(fastify, prefix, options, cache, createServer, T
 		const entry = cache.get(sessionId);
 		if (!entry) return reply.code(204).send();
 		if (options.auth) {
-			if (!isSessionOwner(entry, await resolveMcpAuth(request.headers, options.auth))) return reply.code(403).send({ error: "Unauthorized" });
+			const authResult = await resolveMcpAuth(request.headers, options.auth);
+			if (!isSessionOwner(entry, authResult)) return reply.code(403).send({ error: "Unauthorized" });
+			entry.auth = authResult;
+			entry.authRef.current = authResult;
 		}
 		cache.remove(sessionId);
 		reply.code(204).send();

package/dist/integrations/mcp/testing.d.mts

@@ -1,4 +1,4 @@
-import { o as McpAuthResult, s as McpPluginOptions } from "../../types-BsbNMEDR.mjs";
+import { o as McpAuthResult, s as McpPluginOptions } from "../../types-CoSzA-s-.mjs";
 
 //#region src/integrations/mcp/testing.d.ts
 interface TestMcpClientOptions {

package/dist/integrations/mcp/testing.mjs

@@ -1,4 +1,4 @@
-import { r as createMcpServer, t as resourceToTools } from "../../resourceToTools-8s-EsCCe.mjs";
+import { r as createMcpServer, t as resourceToTools } from "../../resourceToTools-C3cWymnW.mjs";
 //#region src/integrations/mcp/testing.ts
 /**
 * @classytic/arc/mcp/testing — MCP Test Utilities

package/dist/integrations/webhooks.d.mts

@@ -76,6 +76,11 @@ interface VerifySignatureOptions {
  * Works with Arc's own `signPayload` format by default (`sha256=<hex>`),
  * but configurable for any HMAC scheme via options.
  *
+ * ⚠ The `body` argument must be the exact bytes the sender signed. Fastify
+ * parses JSON bodies by default and the re-serialised object will NOT match
+ * the original signature. Register `@fastify/raw-body` or use `preParsing`
+ * to capture `req.rawBody`, then pass that here.
+ *
  * @param body      - Raw request body (string or Buffer — must be the exact bytes the sender signed)
  * @param secret    - Shared secret between sender and receiver
  * @param signature - The signature header value (e.g. `req.headers['x-webhook-signature']`)

package/dist/integrations/webhooks.mjs

@@ -46,6 +46,11 @@ function signPayload(payload, secret) {
 * Works with Arc's own `signPayload` format by default (`sha256=<hex>`),
 * but configurable for any HMAC scheme via options.
 *
+* ⚠ The `body` argument must be the exact bytes the sender signed. Fastify
+* parses JSON bodies by default and the re-serialised object will NOT match
+* the original signature. Register `@fastify/raw-body` or use `preParsing`
+* to capture `req.rawBody`, then pass that here.
+*
 * @param body      - Raw request body (string or Buffer — must be the exact bytes the sender signed)
 * @param secret    - Shared secret between sender and receiver
 * @param signature - The signature header value (e.g. `req.headers['x-webhook-signature']`)
@@ -77,6 +82,7 @@ function signPayload(payload, secret) {
 * ```
 */
 function verifySignature(body, secret, signature, options) {
+	if (typeof body !== "string" && !Buffer.isBuffer(body)) throw new TypeError("verifySignature: body must be a string or Buffer (the exact bytes the sender signed). Register @fastify/raw-body and pass req.rawBody — not req.body.");
 	if (!signature) return false;
 	const prefix = options?.prefix ?? "sha256=";
 	const algorithm = options?.algorithm ?? "sha256";