@classytic/arc 2.3.0 → 2.4.1

package/dist/integrations/mcp/index.mjs

@@ -0,0 +1,572 @@
+import { n as fieldRulesToZod, r as createMcpServer, t as resourceToTools } from "../../resourceToTools-B6ZN9Ing.mjs";
+import { createHash } from "node:crypto";
+import fp from "fastify-plugin";
+//#region src/integrations/mcp/definePrompt.ts
+/**
+* Define a type-safe MCP prompt.
+*
+* @param name - Prompt name (snake_case recommended)
+* @param config - Description, args schema, handler
+*/
+function definePrompt(name, config) {
+	return {
+		name,
+		description: config.description,
+		title: config.title,
+		argsSchema: config.args,
+		handler: config.handler
+	};
+}
+//#endregion
+//#region src/integrations/mcp/defineTool.ts
+/**
+* Define a type-safe MCP tool.
+*
+* @param name - Tool name (snake_case recommended)
+* @param config - Tool description, input schema, annotations, handler
+*/
+function defineTool(name, config) {
+	return {
+		name,
+		description: config.description,
+		title: config.title,
+		inputSchema: config.input,
+		outputSchema: config.output,
+		annotations: config.annotations,
+		handler: config.handler
+	};
+}
+//#endregion
+//#region src/integrations/mcp/guards.ts
+/** Check if the tool context has an authenticated user (not anonymous/null) */
+function isAuthenticated(ctx) {
+	return !!ctx.session && ctx.session.userId !== "anonymous";
+}
+/** Check if the tool context has an organization scope */
+function hasOrg(ctx) {
+	return !!ctx.session?.organizationId;
+}
+/** Check if the tool context matches a specific org */
+function isOrg(ctx, orgId) {
+	return ctx.session?.organizationId === orgId;
+}
+/** Get the current user ID from context (undefined if anonymous/null) */
+function getUserId(ctx) {
+	const id = ctx.session?.userId;
+	return id && id !== "anonymous" ? id : void 0;
+}
+/** Get the current org ID from context */
+function getOrgId(ctx) {
+	return ctx.session?.organizationId;
+}
+/** Create a denied (isError) CallToolResult */
+function denied(reason) {
+	return {
+		content: [{
+			type: "text",
+			text: reason
+		}],
+		isError: true
+	};
+}
+/**
+* Wrap a tool handler with one or more guards.
+* If any guard returns a string, the tool returns an error with that message.
+*
+* @example
+* ```ts
+* defineTool('delete_all', {
+*   description: 'Delete everything',
+*   handler: guard(requireAuth, requireOrg, async (input, ctx) => {
+*     // only runs if authenticated + has org
+*   }),
+* });
+* ```
+*/
+function guard(...args) {
+	const handler = args.pop();
+	const guards = args;
+	return async (input, ctx) => {
+		for (const g of guards) {
+			const err = await g(ctx);
+			if (err) return denied(err);
+		}
+		return handler(input, ctx);
+	};
+}
+/** Require authenticated user (not anonymous) */
+const requireAuth = (ctx) => isAuthenticated(ctx) ? null : "Authentication required";
+/** Require organization context */
+const requireOrg = (ctx) => hasOrg(ctx) ? null : "Organization context required";
+/** Require specific user role (checks session metadata if available) */
+function requireRole(...roles) {
+	return (ctx) => {
+		if (!isAuthenticated(ctx)) return "Authentication required";
+		const userRoles = ctx.session?.roles ?? [];
+		return roles.some((r) => userRoles.includes(r)) ? null : `Required role: ${roles.join(" or ")}`;
+	};
+}
+/** Require specific organization */
+function requireOrgId(orgId) {
+	return (ctx) => isOrg(ctx, orgId) ? null : `Access restricted to organization ${orgId}`;
+}
+/**
+* Custom guard from a predicate function.
+*
+* @example
+* ```ts
+* const businessHoursOnly = customGuard(
+*   (ctx) => new Date().getHours() >= 9 && new Date().getHours() < 17,
+*   'This tool is only available during business hours (9-5)',
+* );
+* ```
+*/
+function customGuard(check, errorMessage) {
+	return async (ctx) => {
+		return await check(ctx) ? null : errorMessage;
+	};
+}
+//#endregion
+//#region src/integrations/mcp/authBridge.ts
+/**
+* @classytic/arc — MCP Auth Bridge
+*
+* Resolves MCP session identity from request headers.
+* Supports three modes — the user chooses:
+*
+* 1. `false` — no auth, anonymous access
+* 2. `BetterAuthHandler` — OAuth 2.1 via Better Auth
+* 3. `McpAuthResolver` — custom function (API key, JWT, gateway headers, etc.)
+*/
+/** Distinguish BetterAuthHandler from McpAuthResolver */
+function isBetterAuth(auth) {
+	return typeof auth === "object" && auth !== null && "api" in auth && "handler" in auth;
+}
+/**
+* Resolve MCP session identity from request headers.
+*
+* @param headers - HTTP request headers
+* @param auth - false | BetterAuthHandler | McpAuthResolver
+* @param authCache - Optional short-lived cache to avoid redundant auth lookups
+*/
+async function resolveMcpAuth(headers, auth, authCache) {
+	if (auth === false) return { userId: "anonymous" };
+	const cacheKey = authCache ? extractAuthCacheKey(headers) : null;
+	if (cacheKey && authCache) {
+		const cached = authCache.get(cacheKey);
+		if (cached !== void 0) return cached;
+	}
+	let result = null;
+	if (typeof auth === "function") try {
+		result = await auth(headers);
+	} catch {
+		result = null;
+	}
+	else if (isBetterAuth(auth)) try {
+		const session = await auth.api.getMcpSession({ headers });
+		if (!session?.userId) result = null;
+		else result = {
+			userId: session.userId,
+			organizationId: session.activeOrganizationId
+		};
+	} catch {
+		result = null;
+	}
+	if (cacheKey && authCache) authCache.set(cacheKey, result);
+	return result;
+}
+const DEFAULT_AUTH_CACHE_TTL_MS = 5e3;
+const DEFAULT_AUTH_CACHE_MAX = 500;
+/** Short-lived auth cache to avoid redundant auth resolver calls in stateless mode */
+var McpAuthCache = class {
+	cache = /* @__PURE__ */ new Map();
+	ttlMs;
+	maxEntries;
+	constructor(opts) {
+		this.ttlMs = opts?.ttlMs ?? DEFAULT_AUTH_CACHE_TTL_MS;
+		this.maxEntries = opts?.maxEntries ?? DEFAULT_AUTH_CACHE_MAX;
+	}
+	get(key) {
+		const entry = this.cache.get(key);
+		if (!entry) return void 0;
+		if (Date.now() > entry.expires) {
+			this.cache.delete(key);
+			return;
+		}
+		return entry.result;
+	}
+	set(key, result) {
+		if (this.cache.size >= this.maxEntries) {
+			const now = Date.now();
+			for (const [k, v] of this.cache) if (now > v.expires) this.cache.delete(k);
+			if (this.cache.size >= this.maxEntries) {
+				const firstKey = this.cache.keys().next().value;
+				if (firstKey) this.cache.delete(firstKey);
+			}
+		}
+		this.cache.set(key, {
+			result,
+			expires: Date.now() + this.ttlMs
+		});
+	}
+};
+/**
+* Extract a cache key from auth-related headers.
+* Uses SHA-256 hash of header values to prevent cache key collisions
+* and avoid storing raw credentials in memory.
+*/
+function extractAuthCacheKey(headers) {
+	if (headers.authorization) return `authz:${hashForCache(headers.authorization)}`;
+	if (headers["x-api-key"]) return `apikey:${hashForCache(headers["x-api-key"])}`;
+	return null;
+}
+function hashForCache(value) {
+	return createHash("sha256").update(value).digest("hex").slice(0, 32);
+}
+/**
+* Register OAuth 2.1 discovery endpoints for MCP clients.
+* Only relevant when using Better Auth — custom auth doesn't need these.
+*/
+async function registerOAuthDiscovery(fastify, auth) {
+	fastify.get("/.well-known/oauth-authorization-server", async (req, reply) => {
+		await forwardResponse(reply, await auth.handler(toWebRequest(req)));
+	});
+	fastify.get("/.well-known/oauth-protected-resource", async (req, reply) => {
+		await forwardResponse(reply, await auth.handler(toWebRequest(req)));
+	});
+}
+function toWebRequest(req) {
+	const protocol = req.protocol ?? "http";
+	const host = req.hostname ?? "localhost";
+	return new Request(`${protocol}://${host}${req.url}`, {
+		method: req.method,
+		headers: req.headers
+	});
+}
+async function forwardResponse(reply, response) {
+	reply.status(response.status);
+	response.headers.forEach((value, key) => {
+		if (key.toLowerCase() !== "transfer-encoding") reply.header(key, value);
+	});
+	reply.send(await response.text());
+}
+//#endregion
+//#region src/integrations/mcp/schemaResources.ts
+/**
+* Register MCP Resources for schema discovery.
+*/
+function registerSchemaResources(server, resources, overrides) {
+	const srv = server;
+	srv.resource("schemas", "arc://schemas", {
+		title: "Arc Resource Schemas",
+		description: "All available resources",
+		mimeType: "application/json"
+	}, async () => ({ contents: [{
+		uri: "arc://schemas",
+		mimeType: "application/json",
+		text: JSON.stringify(resources.map((r) => ({
+			name: r.name,
+			displayName: r.displayName,
+			fieldCount: r.schemaOptions?.fieldRules ? Object.keys(r.schemaOptions.fieldRules).length : 0,
+			operations: getOps(r, overrides?.[r.name]?.operations),
+			presets: r._appliedPresets ?? []
+		})), null, 2)
+	}] }));
+	for (const r of resources) {
+		const uri = `arc://schemas/${r.name}`;
+		const schemaOpts = r.schemaOptions;
+		srv.resource(`schema-${r.name}`, uri, {
+			title: `${r.displayName} Schema`,
+			description: `Schema for ${r.displayName}`,
+			mimeType: "application/json"
+		}, async () => ({ contents: [{
+			uri,
+			mimeType: "application/json",
+			text: JSON.stringify({
+				name: r.name,
+				displayName: r.displayName,
+				operations: getOps(r, overrides?.[r.name]?.operations),
+				fields: r.schemaOptions?.fieldRules ?? {},
+				filterableFields: schemaOpts?.filterableFields ?? [],
+				presets: r._appliedPresets ?? []
+			}, null, 2)
+		}] }));
+	}
+}
+function getOps(r, override) {
+	let ops = [
+		"list",
+		"get",
+		"create",
+		"update",
+		"delete"
+	].filter((op) => !r.disabledRoutes?.includes(op));
+	if (override) ops = ops.filter((op) => override.includes(op));
+	return ops;
+}
+//#endregion
+//#region src/integrations/mcp/sessionCache.ts
+const DEFAULT_TTL_MS = 1800 * 1e3;
+const DEFAULT_MAX_SESSIONS = 1e3;
+var McpSessionCache = class {
+	sessions = /* @__PURE__ */ new Map();
+	ttlMs;
+	maxSessions;
+	cleanupTimer = null;
+	constructor(opts = {}) {
+		this.ttlMs = opts.ttlMs ?? DEFAULT_TTL_MS;
+		this.maxSessions = opts.maxSessions ?? DEFAULT_MAX_SESSIONS;
+		if (this.ttlMs > 0) {
+			this.cleanupTimer = setInterval(() => this.cleanup(), Math.max(this.ttlMs / 2, 5e3));
+			if (this.cleanupTimer.unref) this.cleanupTimer.unref();
+		}
+	}
+	/** Get an existing session by ID */
+	get(sessionId) {
+		const entry = this.sessions.get(sessionId);
+		if (!entry) return void 0;
+		if (Date.now() - entry.lastAccessed > this.ttlMs) {
+			this.remove(sessionId);
+			return;
+		}
+		return entry;
+	}
+	/** Store a new session */
+	set(sessionId, entry) {
+		if (this.sessions.size >= this.maxSessions && !this.sessions.has(sessionId)) this.evictOldest();
+		entry.lastAccessed = Date.now();
+		this.sessions.set(sessionId, entry);
+	}
+	/** Refresh the TTL on a session */
+	touch(sessionId) {
+		const entry = this.sessions.get(sessionId);
+		if (entry) entry.lastAccessed = Date.now();
+	}
+	/** Remove and close a session */
+	remove(sessionId) {
+		const entry = this.sessions.get(sessionId);
+		if (entry) {
+			this.closeTransport(entry);
+			this.sessions.delete(sessionId);
+		}
+	}
+	/** Remove all expired sessions */
+	cleanup() {
+		const now = Date.now();
+		for (const [id, entry] of this.sessions) if (now - entry.lastAccessed > this.ttlMs) {
+			this.closeTransport(entry);
+			this.sessions.delete(id);
+		}
+	}
+	/** Close all sessions and stop cleanup timer */
+	close() {
+		if (this.cleanupTimer) {
+			clearInterval(this.cleanupTimer);
+			this.cleanupTimer = null;
+		}
+		for (const [id, entry] of this.sessions) {
+			this.closeTransport(entry);
+			this.sessions.delete(id);
+		}
+	}
+	/** Current session count */
+	get size() {
+		return this.sessions.size;
+	}
+	/** Evict the oldest (least recently accessed) session */
+	evictOldest() {
+		let oldestId = null;
+		let oldestTime = Infinity;
+		for (const [id, entry] of this.sessions) if (entry.lastAccessed < oldestTime) {
+			oldestTime = entry.lastAccessed;
+			oldestId = id;
+		}
+		if (oldestId) this.remove(oldestId);
+	}
+	/** Safely close a transport */
+	closeTransport(entry) {
+		try {
+			const transport = entry.transport;
+			if (transport && typeof transport.close === "function") transport.close();
+		} catch {}
+	}
+};
+//#endregion
+//#region src/integrations/mcp/mcpPlugin.ts
+const mcpPluginImpl = async (fastify, options) => {
+	let StreamableHTTPServerTransport;
+	try {
+		StreamableHTTPServerTransport = (await import("@modelcontextprotocol/sdk/server/streamableHttp.js")).StreamableHTTPServerTransport;
+		await import("zod");
+	} catch {
+		throw new Error("@modelcontextprotocol/sdk and zod are required for MCP support. Install them: npm install @modelcontextprotocol/sdk zod");
+	}
+	let enabledResources;
+	if (options.include) {
+		const includeSet = new Set(options.include);
+		enabledResources = options.resources.filter((r) => includeSet.has(r.name));
+	} else {
+		const excludeSet = new Set(options.exclude ?? []);
+		enabledResources = options.resources.filter((r) => !excludeSet.has(r.name));
+	}
+	const overrides = options.overrides ?? {};
+	const allTools = enabledResources.flatMap((r) => {
+		const resOverrides = overrides[r.name] ?? {};
+		return resourceToTools(r, {
+			...resOverrides,
+			toolNamePrefix: resOverrides.toolNamePrefix ?? options.toolNamePrefix
+		});
+	});
+	if (options.extraTools) allTools.push(...options.extraTools);
+	fastify.log.info(`mcpPlugin: ${allTools.length} tools from ${enabledResources.length} resources`);
+	const overrideOpsMap = {};
+	for (const [name, cfg] of Object.entries(overrides)) overrideOpsMap[name] = { operations: cfg.operations };
+	const stateful = options.stateful === true;
+	const cache = stateful ? new McpSessionCache({
+		ttlMs: options.sessionTtlMs,
+		maxSessions: options.maxSessions
+	}) : null;
+	async function createServerInstance(authRef) {
+		const server = await createMcpServer({
+			name: options.serverName ?? "arc-mcp",
+			version: options.serverVersion ?? "1.0.0",
+			instructions: options.instructions,
+			tools: allTools,
+			prompts: options.extraPrompts
+		}, authRef);
+		registerSchemaResources(server, enabledResources, overrideOpsMap);
+		return server;
+	}
+	if (options.auth && isBetterAuth(options.auth)) await registerOAuthDiscovery(fastify, options.auth);
+	const prefix = options.prefix ?? "/mcp";
+	fastify.get(`${prefix}/health`, async (_request, reply) => {
+		reply.send({
+			status: "ok",
+			mode: stateful ? "stateful" : "stateless",
+			tools: allTools.length,
+			resources: enabledResources.length,
+			toolNames: allTools.map((t) => t.name),
+			sessions: cache?.size ?? null
+		});
+	});
+	if (stateful) registerStatefulRoutes(fastify, prefix, options, cache, createServerInstance, StreamableHTTPServerTransport);
+	else {
+		const authCache = options.auth && options.authCacheTtlMs !== 0 ? new McpAuthCache({ ttlMs: options.authCacheTtlMs }) : void 0;
+		registerStatelessRoutes(fastify, prefix, options, createServerInstance, StreamableHTTPServerTransport, authCache);
+	}
+	if (cache) fastify.addHook("onClose", async () => cache.close());
+	if (!fastify.hasDecorator("mcp")) fastify.decorate("mcp", {
+		sessions: cache,
+		toolNames: allTools.map((t) => t.name),
+		resourceNames: enabledResources.map((r) => r.name),
+		stateful
+	});
+};
+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)");
+			return reply.code(401).send({
+				jsonrpc: "2.0",
+				error: {
+					code: -32e3,
+					message: "Unauthorized"
+				}
+			});
+		}
+		const authRef = { current: authResult };
+		const transport = new Transport({ sessionIdGenerator: void 0 });
+		await (await createServer(authRef)).connect(transport);
+		await transport.handleRequest(request.raw, reply.raw, request.body);
+	});
+	fastify.get(prefix, async (_request, reply) => {
+		reply.code(405).send({
+			jsonrpc: "2.0",
+			error: {
+				code: -32e3,
+				message: "SSE not available in stateless mode. Use stateful: true for server-initiated messages."
+			}
+		});
+	});
+	fastify.delete(prefix, async (_request, reply) => {
+		reply.code(200).send();
+	});
+}
+function registerStatefulRoutes(fastify, prefix, options, cache, createServer, Transport) {
+	/** Check if the requesting user owns the session */
+	function isSessionOwner(entry, authResult) {
+		if (!options.auth || !entry.auth || !authResult) return true;
+		return entry.auth.userId === authResult.userId && entry.auth.organizationId === authResult.organizationId;
+	}
+	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)");
+			return reply.code(401).send({
+				jsonrpc: "2.0",
+				error: {
+					code: -32e3,
+					message: "Unauthorized"
+				}
+			});
+		}
+		const sessionId = request.headers["mcp-session-id"];
+		if (sessionId) {
+			const entry = cache.get(sessionId);
+			if (entry) {
+				if (!isSessionOwner(entry, authResult)) return reply.code(403).send({
+					jsonrpc: "2.0",
+					error: {
+						code: -32e3,
+						message: "Session ownership mismatch"
+					}
+				});
+				cache.touch(sessionId);
+				entry.auth = authResult;
+				entry.authRef.current = authResult;
+				await entry.transport.handleRequest(request.raw, reply.raw, request.body);
+				return;
+			}
+		}
+		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
+		});
+		await transport.handleRequest(request.raw, reply.raw, request.body);
+	});
+	fastify.get(prefix, async (request, reply) => {
+		const sessionId = request.headers["mcp-session-id"];
+		if (!sessionId) return reply.code(400).send({ error: "Missing Mcp-Session-Id header" });
+		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" });
+		}
+		cache.touch(sessionId);
+		await entry.transport.handleRequest(request.raw, reply.raw);
+	});
+	fastify.delete(prefix, async (request, reply) => {
+		const sessionId = request.headers["mcp-session-id"];
+		if (!sessionId) return reply.code(400).send({ error: "Missing Mcp-Session-Id header" });
+		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" });
+		}
+		cache.remove(sessionId);
+		reply.code(204).send();
+	});
+}
+const mcpPlugin = fp(mcpPluginImpl, {
+	name: "arc-mcp",
+	fastify: "5.x"
+});
+//#endregion
+export { createMcpServer, customGuard, definePrompt, defineTool, denied, fieldRulesToZod, getOrgId, getUserId, guard, hasOrg, isAuthenticated, isOrg, mcpPlugin, requireAuth, requireOrg, requireOrgId, requireRole, resourceToTools };

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

@@ -0,0 +1,53 @@
+import { o as McpAuthResult, s as McpPluginOptions } from "../../types-BJmgxNbF.mjs";
+
+//#region src/integrations/mcp/testing.d.ts
+interface TestMcpClientOptions {
+  /** MCP plugin options (resources, overrides, etc.) — same as mcpPlugin config */
+  pluginOptions?: Pick<McpPluginOptions, "resources" | "overrides" | "include" | "exclude" | "toolNamePrefix" | "extraTools" | "extraPrompts" | "instructions">;
+  /** Auth identity for the test session */
+  auth?: McpAuthResult | null;
+  /** Server name (default: 'test-mcp') */
+  serverName?: string;
+}
+interface TestMcpClient {
+  /** List all registered tools */
+  listTools(): Promise<Array<{
+    name: string;
+    description?: string;
+  }>>;
+  /** Call a tool by name */
+  callTool(name: string, args?: Record<string, unknown>): Promise<{
+    content: Array<{
+      type: string;
+      text: string;
+    }>;
+    isError?: boolean;
+  }>;
+  /** Disconnect and clean up */
+  close(): Promise<void>;
+}
+/**
+ * Create an in-process MCP test client connected to an Arc MCP server.
+ *
+ * Pass resources and tools directly — no running Fastify server needed.
+ * For HTTP-level integration tests against a running server, use `app.inject()` instead.
+ *
+ * @example
+ * ```typescript
+ * const client = await createTestMcpClient({
+ *   pluginOptions: { resources: [productResource], extraTools: [myTool] },
+ *   auth: { userId: 'test-user', organizationId: 'org-1' },
+ * });
+ *
+ * const tools = await client.listTools();
+ * expect(tools.map(t => t.name)).toContain('list_products');
+ *
+ * const result = await client.callTool('list_products', { limit: 5 });
+ * expect(result.isError).toBeFalsy();
+ *
+ * await client.close();
+ * ```
+ */
+declare function createTestMcpClient(options?: TestMcpClientOptions): Promise<TestMcpClient>;
+//#endregion
+export { TestMcpClient, TestMcpClientOptions, createTestMcpClient };