@classytic/arc 2.8.3 → 2.8.4

package/README.md

@@ -2,7 +2,7 @@
 
 Database-agnostic resource framework for Fastify. Define resources, get CRUD routes, permissions, presets, caching, events, OpenAPI, and MCP tools — without boilerplate.
 
-**v2.8.3** | Fastify 5+ | Node.js 22+ | ESM only | 278+ test files, 3844+ tests
+**v2.8.4** | Fastify 5+ | Node.js 22+ | ESM only | 279+ test files, 3867+ tests
 
 ## Install
 
@@ -694,6 +694,27 @@ npx @classytic/arc doctor                                        # Health check
 | `@classytic/arc/docs` | OpenAPI generation |
 | `@classytic/arc/cli` | CLI commands (programmatic) |
 
+## v2.8.4 Highlights
+
+- **MCP ↔ AI SDK bridge** — expose AI SDK `tool()` definitions over MCP without duplicating code. `bridgeToMcp(bridge)` adapts any AI SDK tool into an MCP tool with automatic auth, guard delegation, and `{ error } → isError` envelope translation. `buildMcpToolsFromBridges(bridges, { include, exclude })` registers a whole catalog at once with per-environment filtering.
+
+```typescript
+import { bridgeToMcp, buildMcpToolsFromBridges, type McpBridge } from '@classytic/arc/mcp';
+
+export const triggerJobBridge: McpBridge = {
+  name: 'trigger_job',
+  description: 'Start a job.',
+  inputSchema: { phase: z.enum(['investigate', 'fix']) },
+  annotations: { destructiveHint: true },
+  buildTool: (ctx) => buildTriggerJobTool(getUserId(ctx) ?? ''),
+};
+
+await app.register(mcpPlugin, {
+  resources,
+  extraTools: buildMcpToolsFromBridges([triggerJobBridge]),
+});
+```
+
 ## v2.8.1 Highlights
 
 - **Per-action discriminated validation** — `actions` schemas now enforce required fields via a `oneOf` body schema; missing inputs are rejected at the HTTP layer by AJV (no more silent bypass)

package/dist/index.mjs

@@ -128,6 +128,6 @@ function transform(name, handlerOrOptions) {
 }
 //#endregion
 //#region src/index.ts
-const version = "2.8.3";
+const version = "2.8.4";
 //#endregion
 export { ArcError, BaseController, CRUD_OPERATIONS, DEFAULT_ID_FIELD, DEFAULT_LIMIT, DEFAULT_MAX_LIMIT, DEFAULT_SORT, DEFAULT_TENANT_FIELD, DEFAULT_UPDATE_METHOD, ForbiddenError, HOOK_OPERATIONS, HOOK_PHASES, MAX_FILTER_DEPTH, MAX_REGEX_LENGTH, MAX_SEARCH_LENGTH, MUTATION_OPERATIONS, MongooseAdapter, NotFoundError, PrismaAdapter, RESERVED_QUERY_PARAMS, ResourceDefinition, SYSTEM_FIELDS, UnauthorizedError, ValidationError, adminOnly, allOf, allowPublic, anyOf, applyFieldReadPermissions, applyFieldWritePermissions, arcLog, assertValidConfig, authenticated, configureArcLogger, createDomainError, createDynamicPermissionMatrix, createMongooseAdapter, createOrgPermissions, createPrismaAdapter, defineResource, defineResourceVariants, denyAll, envelope, fields, formatValidationErrors, fullPublic, getControllerScope, guard, intercept, middleware, ownerWithAdminBypass, presets_exports as permissions, pipe, publicRead, publicReadAdminWrite, readOnly, requestContext, requireAuth, requireOrgInScope, requireOrgMembership, requireOrgRole, requireOwnership, requireRoles, requireScopeContext, requireServiceScope, requireTeamMembership, sortMiddlewares, transform, validateResourceConfig, version, when };

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

@@ -3,6 +3,54 @@ import { a as McpAuthResolver, c as McpResourceConfig, d as SessionEntry, f as T
 import { FastifyPluginAsync } from "fastify";
 import { z } from "zod";
 
+//#region src/integrations/mcp/aiSdkBridge.d.ts
+/** Minimal AI SDK tool shape we need to invoke. */
+interface AiSdkExecutable {
+  execute: (input: unknown, options?: unknown) => Promise<unknown>;
+}
+interface McpBridge {
+  /** MCP tool name. */
+  name: string;
+  /** LLM-facing description. */
+  description: string;
+  /** Zod input schema — matches the AI SDK tool's inputSchema. */
+  inputSchema: Record<string, z.ZodType>;
+  /** MCP annotations — same shape as `defineTool`. */
+  annotations?: ToolAnnotations;
+  /**
+   * Build the AI SDK tool from MCP session context. Called per-request.
+   * The caller injects deps (companyId, projectId, etc.) from `ctx`.
+   */
+  buildTool: (ctx: ToolContext) => AiSdkExecutable;
+  /**
+   * Optional pre-execution guard. Return an error message to reject, or
+   * `null` to proceed. Runs after `isAuthenticated`.
+   */
+  guard?: (ctx: ToolContext) => string | null;
+}
+/** Convert a McpBridge into a registered MCP tool. */
+declare function bridgeToMcp(bridge: McpBridge): ToolDefinition;
+interface BuildMcpToolsFromBridgesOptions {
+  /** If set, only bridges whose `name` is in this array are registered. */
+  include?: string[];
+  /** If set, bridges whose `name` is in this array are skipped. */
+  exclude?: string[];
+}
+/**
+ * Take a list of McpBridge objects and produce a ready-to-register MCP tool
+ * array, with optional include/exclude filtering for per-environment config.
+ *
+ * @example
+ * ```typescript
+ * // All bridges
+ * extraTools: [...buildMcpToolsFromBridges(allBridges)]
+ *
+ * // Read-only deployment — hide destructive tools
+ * extraTools: [...buildMcpToolsFromBridges(allBridges, { exclude: ['trigger_job'] })]
+ * ```
+ */
+declare function buildMcpToolsFromBridges(bridges: readonly McpBridge[], options?: BuildMcpToolsFromBridgesOptions): ToolDefinition[];
+//#endregion
 //#region src/integrations/mcp/createMcpServer.d.ts
 /**
  * Mutable auth ref — updated per-request by mcpPlugin.
@@ -218,4 +266,4 @@ interface ResourceToToolsConfig extends McpResourceConfig {
  */
 declare function resourceToTools(resource: ResourceDefinition, config?: ResourceToToolsConfig): ToolDefinition[];
 //#endregion
-export { type AuthRef, type BetterAuthHandler, type CallToolResult, type CreateMcpServerConfig, type CrudOperation, type DefinePromptConfig, type DefineToolConfig, type FieldRuleEntry, type FieldRulesToZodOptions, type McpAuthResolver, type McpAuthResult, type McpGuard, type McpPluginOptions, type McpResourceConfig, type McpServerInstance, type PromptDefinition, type PromptResult, type ResourceToToolsConfig, type ToolAnnotations, type ToolContext, type ToolDefinition, createMcpServer, customGuard, definePrompt, defineTool, denied, fieldRulesToZod, getOrgId, getUserId, guard, hasOrg, isAuthenticated, isOrg, mcpPlugin, requireAuth, requireOrg, requireOrgId, requireRole, resourceToTools };
+export { type AuthRef, type BetterAuthHandler, type BuildMcpToolsFromBridgesOptions, type CallToolResult, type CreateMcpServerConfig, type CrudOperation, type DefinePromptConfig, type DefineToolConfig, type FieldRuleEntry, type FieldRulesToZodOptions, type McpAuthResolver, type McpAuthResult, type McpBridge, type McpGuard, type McpPluginOptions, type McpResourceConfig, type McpServerInstance, type PromptDefinition, type PromptResult, type ResourceToToolsConfig, type ToolAnnotations, type ToolContext, type ToolDefinition, bridgeToMcp, buildMcpToolsFromBridges, createMcpServer, customGuard, definePrompt, defineTool, denied, fieldRulesToZod, getOrgId, getUserId, guard, hasOrg, isAuthenticated, isOrg, mcpPlugin, requireAuth, requireOrg, requireOrgId, requireRole, resourceToTools };

package/dist/integrations/mcp/index.mjs

@@ -1,23 +1,6 @@
 import { n as fieldRulesToZod, r as createMcpServer, t as resourceToTools } from "../../resourceToTools-O_HwWXFa.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.
@@ -127,6 +110,82 @@ function customGuard(check, errorMessage) {
 	};
 }
 //#endregion
+//#region src/integrations/mcp/aiSdkBridge.ts
+/** Serialize an AI SDK tool result into MCP's text-content envelope. */
+function toMcpEnvelope(result) {
+	if (result && typeof result === "object" && "error" in result) {
+		const msg = result.error;
+		return {
+			content: [{
+				type: "text",
+				text: typeof msg === "string" ? msg : JSON.stringify(msg)
+			}],
+			isError: true
+		};
+	}
+	return { content: [{
+		type: "text",
+		text: typeof result === "string" ? result : JSON.stringify(result, null, 2)
+	}] };
+}
+/** Convert a McpBridge into a registered MCP tool. */
+function bridgeToMcp(bridge) {
+	return defineTool(bridge.name, {
+		description: bridge.description,
+		input: bridge.inputSchema,
+		annotations: bridge.annotations,
+		handler: async (input, ctx) => {
+			if (!isAuthenticated(ctx)) return denied("Authentication required");
+			if (bridge.guard) {
+				const reason = bridge.guard(ctx);
+				if (reason) return denied(reason);
+			}
+			try {
+				return toMcpEnvelope(await bridge.buildTool(ctx).execute(input));
+			} catch (err) {
+				return denied(err instanceof Error ? err.message : String(err));
+			}
+		}
+	});
+}
+/**
+* Take a list of McpBridge objects and produce a ready-to-register MCP tool
+* array, with optional include/exclude filtering for per-environment config.
+*
+* @example
+* ```typescript
+* // All bridges
+* extraTools: [...buildMcpToolsFromBridges(allBridges)]
+*
+* // Read-only deployment — hide destructive tools
+* extraTools: [...buildMcpToolsFromBridges(allBridges, { exclude: ['trigger_job'] })]
+* ```
+*/
+function buildMcpToolsFromBridges(bridges, options = {}) {
+	return bridges.filter((bridge) => {
+		if (options.include) return options.include.includes(bridge.name);
+		if (options.exclude) return !options.exclude.includes(bridge.name);
+		return true;
+	}).map(bridgeToMcp);
+}
+//#endregion
+//#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/authBridge.ts
 /**
 * @classytic/arc — MCP Auth Bridge
@@ -572,4 +631,4 @@ const mcpPlugin = fp(mcpPluginImpl, {
 	fastify: "5.x"
 });
 //#endregion
-export { createMcpServer, customGuard, definePrompt, defineTool, denied, fieldRulesToZod, getOrgId, getUserId, guard, hasOrg, isAuthenticated, isOrg, mcpPlugin, requireAuth, requireOrg, requireOrgId, requireRole, resourceToTools };
+export { bridgeToMcp, buildMcpToolsFromBridges, createMcpServer, customGuard, definePrompt, defineTool, denied, fieldRulesToZod, getOrgId, getUserId, guard, hasOrg, isAuthenticated, isOrg, mcpPlugin, requireAuth, requireOrg, requireOrgId, requireRole, resourceToTools };

package/dist/plugins/tracing-entry.mjs

@@ -44,7 +44,7 @@ try {
 function createTracerProvider(options) {
 	if (!isAvailable) return null;
 	const { serviceName = "@classytic/arc", serviceVersion, exporterUrl = "http://localhost:4318/v1/traces" } = options;
-	const resolvedVersion = serviceVersion ?? "2.8.3";
+	const resolvedVersion = serviceVersion ?? "2.8.4";
 	const exporter = new OTLPTraceExporter({ url: exporterUrl });
 	const provider = new NodeTracerProvider({ resource: { attributes: {
 		"service.name": serviceName,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@classytic/arc",
-  "version": "2.8.3",
+  "version": "2.8.4",
   "description": "Resource-oriented backend framework for Fastify — clean, minimal, powerful, tree-shakable",
   "type": "module",
   "exports": {

package/skills/arc/SKILL.md

@@ -856,6 +856,28 @@ auth: async (headers) => ({
 
 **Guards** for custom tools: `guard(requireAuth, requireOrg, requireRole('admin'), handler)`
 
+**AI SDK bridge** (v2.8.4+) — expose AI SDK `tool()` definitions over MCP without duplicating glue. Handles auth, guards, `{ error } → isError` translation, and thrown-error mapping:
+
+```typescript
+import { bridgeToMcp, buildMcpToolsFromBridges, getUserId, hasOrg, type McpBridge } from '@classytic/arc/mcp';
+
+export const triggerJobBridge: McpBridge = {
+  name: 'trigger_job',
+  description: 'Start a job.',
+  inputSchema: { phase: z.enum(['investigate', 'fix']) },
+  annotations: { destructiveHint: true },
+  buildTool: (ctx) => buildTriggerJobTool(getUserId(ctx) ?? ''),
+  guard: (ctx) => (hasOrg(ctx) ? null : 'Organization scope required'),
+};
+
+await app.register(mcpPlugin, {
+  resources,
+  extraTools: buildMcpToolsFromBridges([triggerJobBridge], {
+    exclude: process.env.DEPLOYMENT === 'readonly' ? ['trigger_job'] : [],
+  }),
+});
+```
+
 **Service scope**: When `clientId` is set in auth result, MCP produces `kind: "service"` RequestScope — works with `requireServiceScope()`, `getClientId()`, `getServiceScopes()`. No synthetic userId needed for machine principals.
 
 **Multi-tenancy**: `organizationId` from auth flows into BaseController org-scoping automatically.

package/skills/arc/references/mcp.md

@@ -430,6 +430,43 @@ const createShape = fieldRulesToZod(resource.schemaOptions.fieldRules, {
 // → { name: z.string(), price: z.number(), category: z.enum([...]) }
 ```
 
+## AI SDK Bridge (v2.8.4+)
+
+Expose AI SDK `tool()` definitions over MCP without duplicating glue. The bridge handles `isAuthenticated` rejection, optional custom guards, `{ error }` → `isError: true` envelope translation, and thrown-error mapping.
+
+```typescript
+import { bridgeToMcp, buildMcpToolsFromBridges, getUserId, hasOrg, type McpBridge } from '@classytic/arc/mcp';
+import { tool } from 'ai';
+import { z } from 'zod';
+
+function buildTriggerJobTool(companyId: string) {
+  return tool({
+    description: 'Start a job.',
+    inputSchema: z.object({ phase: z.enum(['investigate', 'fix']) }),
+    execute: async ({ phase }) => ({ jobId: `${companyId}-${phase}-${Date.now()}` }),
+  });
+}
+
+export const triggerJobBridge: McpBridge = {
+  name: 'trigger_job',
+  description: 'Start a job.',
+  inputSchema: { phase: z.enum(['investigate', 'fix']) },
+  annotations: { destructiveHint: true },
+  buildTool: (ctx) => buildTriggerJobTool(getUserId(ctx) ?? ''),
+  guard: (ctx) => (hasOrg(ctx) ? null : 'Organization scope required'),
+};
+
+await app.register(mcpPlugin, {
+  resources,
+  extraTools: buildMcpToolsFromBridges([triggerJobBridge], {
+    // Per-environment filtering — read-only deployments hide destructive tools
+    exclude: process.env.DEPLOYMENT === 'readonly' ? ['trigger_job'] : [],
+  }),
+});
+```
+
+`buildMcpToolsFromBridges` also accepts `{ include: [...] }` for strict allowlists. `buildTool` is called fresh per request — safe for per-tenant dep resolution. `McpBridge.annotations` is the same `ToolAnnotations` shape as `defineTool`.
+
 ## Schema Discovery — MCP Resources
 
 Auto-registered for agent discovery: