@classytic/arc 2.4.1 → 2.4.2

package/dist/index.mjs

@@ -126,6 +126,6 @@ function transform(name, handlerOrOptions) {
 }
 //#endregion
 //#region src/index.ts
-const version = "2.4.1";
+const version = "2.4.2";
 //#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, createDynamicPermissionMatrix, createMongooseAdapter, createOrgPermissions, createPrismaAdapter, defineResource, denyAll, fields, formatValidationErrors, fullPublic, getControllerScope, guard, intercept, middleware, ownerWithAdminBypass, presets_exports as permissions, pipe, publicRead, publicReadAdminWrite, readOnly, requestContext, requireAuth, requireOrgMembership, requireOrgRole, requireOwnership, requireRoles, requireTeamMembership, sortMiddlewares, transform, validateResourceConfig, version, when };

package/dist/integrations/mcp/index.mjs

@@ -1,4 +1,4 @@
-import { n as fieldRulesToZod, r as createMcpServer, t as resourceToTools } from "../../resourceToTools-B6ZN9Ing.mjs";
+import { n as fieldRulesToZod, r as createMcpServer, t as resourceToTools } from "../../resourceToTools-PMFE8HIv.mjs";
 import { createHash } from "node:crypto";
 import fp from "fastify-plugin";
 //#region src/integrations/mcp/definePrompt.ts

package/dist/integrations/mcp/testing.mjs

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

package/dist/migrations/index.d.mts

@@ -1,6 +1,41 @@
-import mongoose from "mongoose";
-
 //#region src/migrations/index.d.ts
+/**
+ * Schema Versioning and Migrations System
+ *
+ * Manages database schema changes over time with version tracking.
+ * Supports forward migrations, rollbacks, and schema compatibility layers.
+ *
+ * DB-agnostic: the `db` parameter is typed as `unknown` — the user passes
+ * whatever connection object their adapter uses (Mongoose db, Prisma client,
+ * Knex instance, etc.) and their `up`/`down` functions cast it internally.
+ *
+ * @example
+ * import { defineMigration, MigrationRunner } from '@classytic/arc/migrations';
+ *
+ * const productV2 = defineMigration({
+ *   version: 2,
+ *   resource: 'product',
+ *   up: async (db) => {
+ *     const mongo = db as import('mongoose').mongo.Db;
+ *     await mongo.collection('products').updateMany(
+ *       {},
+ *       { $rename: { 'oldField': 'newField' } }
+ *     );
+ *   },
+ *   down: async (db) => {
+ *     const mongo = db as import('mongoose').mongo.Db;
+ *     await mongo.collection('products').updateMany(
+ *       {},
+ *       { $rename: { 'newField': 'oldField' } }
+ *     );
+ *   },
+ * });
+ *
+ * const runner = new MigrationRunner(mongoose.connection.db, {
+ *   store: new MongoMigrationStore(mongoose.connection.db),
+ * });
+ * await runner.up(migrations);
+ */
 interface Migration {
   /** Migration version (sequential number) */
   version: number;
@@ -9,17 +44,18 @@ interface Migration {
   /** Description of the migration */
   description?: string;
   /**
-   * Forward migration (apply schema change)
+   * Forward migration (apply schema change).
+   * The `db` parameter is whatever connection object you pass to the runner.
    */
-  up: (db: mongoose.mongo.Db) => Promise<void>;
+  up: (db: unknown) => Promise<void>;
   /**
-   * Backward migration (revert schema change)
+   * Backward migration (revert schema change).
    */
-  down: (db: mongoose.mongo.Db) => Promise<void>;
+  down: (db: unknown) => Promise<void>;
   /**
    * Optional validation that data is compatible after migration
    */
-  validate?: (db: mongoose.mongo.Db) => Promise<boolean>;
+  validate?: (db: unknown) => Promise<boolean>;
 }
 interface MigrationRecord {
   version: number;
@@ -28,6 +64,54 @@ interface MigrationRecord {
   appliedAt: Date;
   executionTime: number;
 }
+/**
+ * DB-agnostic migration store interface.
+ *
+ * Users implement this for their database:
+ * - MongoMigrationStore (uses a `_migrations` collection)
+ * - PrismaMigrationStore (uses a `_migrations` table)
+ * - or any custom store
+ */
+interface MigrationStore {
+  /** Get all applied migration records, sorted by appliedAt ascending */
+  getApplied(): Promise<MigrationRecord[]>;
+  /** Record a completed migration */
+  record(migration: Migration, executionTime: number): Promise<void>;
+  /** Remove a migration record (for rollback) */
+  remove(migration: Migration): Promise<void>;
+}
+/**
+ * Minimal logger interface — matches Fastify's logger, pino, console, etc.
+ */
+interface MigrationLogger {
+  info(msg: string): void;
+  error(msg: string): void;
+}
+/**
+ * MongoDB-backed migration store.
+ *
+ * Uses a `_migrations` collection in the same database.
+ * The `db` parameter accepts any object with a `.collection()` method
+ * (Mongoose db, native MongoDB Db, etc.)
+ */
+declare class MongoMigrationStore implements MigrationStore {
+  private readonly collectionName;
+  private readonly db;
+  constructor(db: {
+    collection(name: string): any;
+  }, opts?: {
+    collectionName?: string;
+  });
+  getApplied(): Promise<MigrationRecord[]>;
+  record(migration: Migration, executionTime: number): Promise<void>;
+  remove(migration: Migration): Promise<void>;
+}
+interface MigrationRunnerOptions {
+  /** Migration store (required — use MongoMigrationStore or implement your own) */
+  store: MigrationStore;
+  /** Logger (defaults to process.stdout/stderr) */
+  logger?: MigrationLogger;
+}
 /**
  * Define a migration
  */
@@ -35,12 +119,30 @@ declare function defineMigration(migration: Migration): Migration;
 /**
  * Migration Runner
  *
- * Manages execution of migrations with tracking and rollback support.
+ * DB-agnostic. Manages execution of migrations with tracking and rollback.
+ * The `db` parameter is passed through to migration `up`/`down` functions
+ * as-is — the runner never touches it directly.
+ *
+ * @example
+ * ```typescript
+ * // MongoDB
+ * const runner = new MigrationRunner(mongoose.connection.db, {
+ *   store: new MongoMigrationStore(mongoose.connection.db),
+ * });
+ *
+ * // Prisma
+ * const runner = new MigrationRunner(prisma, {
+ *   store: new PrismaMigrationStore(prisma), // user-implemented
+ * });
+ *
+ * await runner.up(migrations);
+ * ```
  */
 declare class MigrationRunner {
-  private readonly collectionName;
   private readonly db;
-  constructor(db: mongoose.mongo.Db);
+  private readonly store;
+  private readonly log;
+  constructor(db: unknown, opts: MigrationRunnerOptions);
   /**
    * Run all pending migrations
    */
@@ -69,14 +171,6 @@ declare class MigrationRunner {
    * Run a single migration
    */
   private runMigration;
-  /**
-   * Record a completed migration
-   */
-  private recordMigration;
-  /**
-   * Remove a migration record
-   */
-  private removeMigration;
 }
 /**
  * Schema version definition for resources
@@ -127,30 +221,5 @@ declare class MigrationRegistry {
    */
   clear(): void;
 }
-/**
- * Global migration registry instance
- */
-declare const migrationRegistry: MigrationRegistry;
-/**
- * Common migration helpers
- */
-declare const migrationHelpers: {
-  /**
-   * Rename a field across all documents
-   */
-  renameField: (collection: string, oldName: string, newName: string) => Migration;
-  /**
-   * Add a new field with default value
-   */
-  addField: (collection: string, fieldName: string, defaultValue: unknown) => Migration;
-  /**
-   * Remove a field
-   */
-  removeField: (collection: string, fieldName: string) => Migration;
-  /**
-   * Create an index
-   */
-  createIndex: (collection: string, fields: Record<string, 1 | -1>, options?: Record<string, unknown>) => Migration;
-};
 //#endregion
-export { Migration, MigrationRecord, MigrationRegistry, MigrationRunner, SchemaVersion, defineMigration, migrationHelpers, migrationRegistry, withSchemaVersion };
+export { Migration, MigrationLogger, MigrationRecord, MigrationRegistry, MigrationRunner, MigrationRunnerOptions, MigrationStore, MongoMigrationStore, SchemaVersion, defineMigration, withSchemaVersion };

package/dist/migrations/index.mjs

@@ -1,4 +1,42 @@
 //#region src/migrations/index.ts
+/** Default logger that writes to stdout/stderr */
+const defaultLogger = {
+	info: (msg) => process.stdout.write(`${msg}\n`),
+	error: (msg) => process.stderr.write(`${msg}\n`)
+};
+/**
+* MongoDB-backed migration store.
+*
+* Uses a `_migrations` collection in the same database.
+* The `db` parameter accepts any object with a `.collection()` method
+* (Mongoose db, native MongoDB Db, etc.)
+*/
+var MongoMigrationStore = class {
+	collectionName;
+	db;
+	constructor(db, opts) {
+		this.db = db;
+		this.collectionName = opts?.collectionName ?? "_migrations";
+	}
+	async getApplied() {
+		return await this.db.collection(this.collectionName).find({}).sort({ appliedAt: 1 }).toArray();
+	}
+	async record(migration, executionTime) {
+		await this.db.collection(this.collectionName).insertOne({
+			version: migration.version,
+			resource: migration.resource,
+			description: migration.description,
+			appliedAt: /* @__PURE__ */ new Date(),
+			executionTime
+		});
+	}
+	async remove(migration) {
+		await this.db.collection(this.collectionName).deleteOne({
+			version: migration.version,
+			resource: migration.resource
+		});
+	}
+};
 /**
 * Define a migration
 */
@@ -8,77 +46,97 @@ function defineMigration(migration) {
 /**
 * Migration Runner
 *
-* Manages execution of migrations with tracking and rollback support.
+* DB-agnostic. Manages execution of migrations with tracking and rollback.
+* The `db` parameter is passed through to migration `up`/`down` functions
+* as-is — the runner never touches it directly.
+*
+* @example
+* ```typescript
+* // MongoDB
+* const runner = new MigrationRunner(mongoose.connection.db, {
+*   store: new MongoMigrationStore(mongoose.connection.db),
+* });
+*
+* // Prisma
+* const runner = new MigrationRunner(prisma, {
+*   store: new PrismaMigrationStore(prisma), // user-implemented
+* });
+*
+* await runner.up(migrations);
+* ```
 */
 var MigrationRunner = class {
-	collectionName = "_migrations";
 	db;
-	constructor(db) {
+	store;
+	log;
+	constructor(db, opts) {
 		this.db = db;
+		this.store = opts.store;
+		this.log = opts.logger ?? defaultLogger;
 	}
 	/**
 	* Run all pending migrations
 	*/
 	async up(migrations) {
-		const applied = await this.getAppliedMigrations();
+		const applied = await this.store.getApplied();
 		const appliedVersions = new Set(applied.map((m) => `${m.resource}:${m.version}`));
 		const pending = migrations.filter((m) => !appliedVersions.has(`${m.resource}:${m.version}`)).sort((a, b) => a.version - b.version);
 		if (pending.length === 0) {
-			console.log("No pending migrations");
+			this.log.info("No pending migrations");
 			return;
 		}
-		console.log(`Running ${pending.length} migration(s)...\n`);
+		this.log.info(`Running ${pending.length} migration(s)...`);
 		for (const migration of pending) await this.runMigration(migration, "up");
-		console.log("\nAll migrations completed successfully");
+		this.log.info("All migrations completed successfully");
 	}
 	/**
 	* Rollback last migration
 	*/
 	async down(migrations) {
-		const applied = await this.getAppliedMigrations();
+		const applied = await this.store.getApplied();
 		if (applied.length === 0) {
-			console.log("No migrations to rollback");
+			this.log.info("No migrations to rollback");
 			return;
 		}
 		const last = applied[applied.length - 1];
 		if (!last) {
-			console.log("No migrations to rollback");
+			this.log.info("No migrations to rollback");
 			return;
 		}
 		const migration = migrations.find((m) => m.resource === last.resource && m.version === last.version);
 		if (!migration) throw new Error(`Migration ${last.resource}:${last.version} not found in migration files`);
-		console.log(`Rolling back ${migration.resource} v${migration.version}...`);
+		this.log.info(`Rolling back ${migration.resource} v${migration.version}...`);
 		await this.runMigration(migration, "down", true);
-		console.log("Rollback completed");
+		this.log.info("Rollback completed");
 	}
 	/**
 	* Rollback to specific version
 	*/
 	async downTo(migrations, targetVersion) {
-		const toRollback = (await this.getAppliedMigrations()).filter((m) => m.version > targetVersion).reverse();
+		const toRollback = (await this.store.getApplied()).filter((m) => m.version > targetVersion).reverse();
 		if (toRollback.length === 0) {
-			console.log(`Already at or below version ${targetVersion}`);
+			this.log.info(`Already at or below version ${targetVersion}`);
 			return;
 		}
-		console.log(`Rolling back ${toRollback.length} migration(s)...\n`);
+		this.log.info(`Rolling back ${toRollback.length} migration(s)...`);
 		for (const record of toRollback) {
 			const migration = migrations.find((m) => m.resource === record.resource && m.version === record.version);
 			if (!migration) throw new Error(`Migration ${record.resource}:${record.version} not found`);
 			await this.runMigration(migration, "down", true);
 		}
-		console.log("\nRollback completed");
+		this.log.info("Rollback completed");
 	}
 	/**
 	* Get all applied migrations
 	*/
 	async getAppliedMigrations() {
-		return await this.db.collection(this.collectionName).find({}).sort({ appliedAt: 1 }).toArray();
+		return this.store.getApplied();
 	}
 	/**
 	* Get pending migrations
 	*/
 	async getPendingMigrations(migrations) {
-		const applied = await this.getAppliedMigrations();
+		const applied = await this.store.getApplied();
 		const appliedVersions = new Set(applied.map((m) => `${m.resource}:${m.version}`));
 		return migrations.filter((m) => !appliedVersions.has(`${m.resource}:${m.version}`));
 	}
@@ -93,46 +151,28 @@ var MigrationRunner = class {
 	*/
 	async runMigration(migration, direction, isRollback = false) {
 		const start = Date.now();
-		console.log(`${direction === "up" ? "Applying" : "Rolling back"} ${migration.resource} v${migration.version}${migration.description ? `: ${migration.description}` : ""}...`);
+		const action = direction === "up" ? "Applying" : "Rolling back";
+		const label = `${migration.resource} v${migration.version}`;
+		const desc = migration.description ? `: ${migration.description}` : "";
+		this.log.info(`${action} ${label}${desc}...`);
 		try {
 			if (direction === "up") {
 				await migration.up(this.db);
 				if (migration.validate) {
 					if (!await migration.validate(this.db)) throw new Error("Migration validation failed");
 				}
-				await this.recordMigration(migration, Date.now() - start);
+				await this.store.record(migration, Date.now() - start);
 			} else {
 				await migration.down(this.db);
-				if (isRollback) await this.removeMigration(migration);
+				if (isRollback) await this.store.remove(migration);
 			}
 			const duration = Date.now() - start;
-			console.log(`✅ ${migration.resource} v${migration.version} (${duration}ms)`);
+			this.log.info(`${label} completed (${duration}ms)`);
 		} catch (error) {
-			console.error(`❌ ${migration.resource} v${migration.version} failed:`, error.message);
+			this.log.error(`${label} failed: ${error.message}`);
 			throw error;
 		}
 	}
-	/**
-	* Record a completed migration
-	*/
-	async recordMigration(migration, executionTime) {
-		await this.db.collection(this.collectionName).insertOne({
-			version: migration.version,
-			resource: migration.resource,
-			description: migration.description,
-			appliedAt: /* @__PURE__ */ new Date(),
-			executionTime
-		});
-	}
-	/**
-	* Remove a migration record
-	*/
-	async removeMigration(migration) {
-		await this.db.collection(this.collectionName).deleteOne({
-			version: migration.version,
-			resource: migration.resource
-		});
-	}
 };
 /**
 * Add versioning to resource definition
@@ -198,59 +238,5 @@ var MigrationRegistry = class {
 		this.migrations.clear();
 	}
 };
-/**
-* Global migration registry instance
-*/
-const migrationRegistry = new MigrationRegistry();
-/**
-* Common migration helpers
-*/
-const migrationHelpers = {
-	renameField: (collection, oldName, newName) => defineMigration({
-		version: 0,
-		resource: collection,
-		description: `Rename ${oldName} to ${newName}`,
-		up: async (db) => {
-			await db.collection(collection).updateMany({}, { $rename: { [oldName]: newName } });
-		},
-		down: async (db) => {
-			await db.collection(collection).updateMany({}, { $rename: { [newName]: oldName } });
-		}
-	}),
-	addField: (collection, fieldName, defaultValue) => defineMigration({
-		version: 0,
-		resource: collection,
-		description: `Add ${fieldName} field`,
-		up: async (db) => {
-			await db.collection(collection).updateMany({ [fieldName]: { $exists: false } }, { $set: { [fieldName]: defaultValue } });
-		},
-		down: async (db) => {
-			await db.collection(collection).updateMany({}, { $unset: { [fieldName]: "" } });
-		}
-	}),
-	removeField: (collection, fieldName) => defineMigration({
-		version: 0,
-		resource: collection,
-		description: `Remove ${fieldName} field`,
-		up: async (db) => {
-			await db.collection(collection).updateMany({}, { $unset: { [fieldName]: "" } });
-		},
-		down: async (_db) => {
-			console.warn(`Cannot restore ${fieldName} field - data was deleted`);
-		}
-	}),
-	createIndex: (collection, fields, options) => defineMigration({
-		version: 0,
-		resource: collection,
-		description: `Create index on ${Object.keys(fields).join(", ")}`,
-		up: async (db) => {
-			await db.collection(collection).createIndex(fields, options);
-		},
-		down: async (db) => {
-			const indexName = typeof options?.name === "string" ? options.name : Object.keys(fields).join("_");
-			await db.collection(collection).dropIndex(indexName);
-		}
-	})
-};
 //#endregion
-export { MigrationRegistry, MigrationRunner, defineMigration, migrationHelpers, migrationRegistry, withSchemaVersion };
+export { MigrationRegistry, MigrationRunner, MongoMigrationStore, defineMigration, withSchemaVersion };

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.4.1";
+	const resolvedVersion = serviceVersion ?? "2.4.2";
 	const exporter = new OTLPTraceExporter({ url: exporterUrl });
 	const provider = new NodeTracerProvider({ resource: { attributes: {
 		"service.name": serviceName,

package/dist/{resourceToTools-B6ZN9Ing.mjs → resourceToTools-PMFE8HIv.mjs}

@@ -174,18 +174,19 @@ function buildListShape(fieldRules, options) {
 * | update    | { id }     | {}                   | input minus id      |
 * | delete    | { id }     | {}                   | undefined           |
 */
-function buildRequestContext(input, auth, operation) {
+function buildRequestContext(input, auth, operation, policyFilters) {
 	const scope = buildScope(auth);
 	const base = {
 		user: auth ? {
 			id: auth.userId,
-			_id: auth.userId
+			_id: auth.userId,
+			...auth
 		} : null,
 		headers: {},
 		context: {},
 		metadata: {
 			_scope: scope,
-			_policyFilters: {}
+			_policyFilters: policyFilters ?? {}
 		}
 	};
 	switch (operation) {
@@ -315,7 +316,7 @@ function resourceToTools(resource, config = {}) {
 				extraHideFields: config.hideFields,
 				filterableFields
 			}),
-			handler: createHandler(op, controller, resource.name)
+			handler: createHandler(op, controller, resource.name, resource.permissions)
 		});
 	}
 	for (const route of resource.additionalRoutes ?? []) {
@@ -381,7 +382,7 @@ function buildInputSchema(op, fieldRules, opts) {
 		case "delete": return { id: z.string().describe("Resource ID") };
 	}
 }
-function createHandler(op, controller, resourceName) {
+function createHandler(op, controller, resourceName, permissions) {
 	const ctrl = controller;
 	return async (input, ctx) => {
 		try {
@@ -393,7 +394,15 @@ function createHandler(op, controller, resourceName) {
 				}],
 				isError: true
 			};
-			return toCallToolResult(await method(buildRequestContext(input, ctx.session, op)));
+			const policyFilters = await evaluatePermission(permissions?.[op], ctx.session, resourceName, op, input);
+			if (policyFilters === false) return {
+				content: [{
+					type: "text",
+					text: `Permission denied: ${op} on ${resourceName}`
+				}],
+				isError: true
+			};
+			return toCallToolResult(await method(buildRequestContext(input, ctx.session, op, policyFilters || void 0)));
 		} catch (err) {
 			const msg = err instanceof Error ? err.message : String(err);
 			ctx.log("error", `${resourceName}.${op}: ${msg}`).catch(() => {});
@@ -432,6 +441,41 @@ function createAdditionalRouteHandler(route, controller, hasId) {
 		}
 	};
 }
+/**
+* Evaluate a resource's permission check in MCP context.
+*
+* Returns:
+* - `false` if permission denied
+* - `Record<string, unknown>` if granted with filters (ownership patterns)
+* - `null` if granted without filters (or no permission check defined)
+*/
+async function evaluatePermission(check, session, resource, action, input) {
+	if (!check) return null;
+	const user = session ? {
+		id: session.userId,
+		_id: session.userId,
+		...session
+	} : null;
+	const result = await check({
+		user,
+		request: {
+			user,
+			headers: {},
+			params: {},
+			query: {},
+			body: input
+		},
+		resource,
+		action,
+		resourceId: typeof input.id === "string" ? input.id : void 0,
+		params: {},
+		data: input
+	});
+	if (typeof result === "boolean") return result ? null : false;
+	const permResult = result;
+	if (!permResult.granted) return false;
+	return permResult.filters ?? null;
+}
 function toCallToolResult(result) {
 	if (!result.success) return {
 		content: [{

package/package.json

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

package/skills/arc/SKILL.md

@@ -8,11 +8,11 @@ description: |
   Triggers: arc, fastify resource, defineResource, createApp, BaseController, arc preset,
   arc auth, arc events, arc jobs, arc websocket, arc mcp, arc plugin, arc testing, arc cli,
   arc permissions, arc hooks, arc pipeline, arc factory, arc cache, arc QueryCache.
-version: 2.4.0
+version: 2.4.2
 license: MIT
 metadata:
   author: Classytic
-  version: "2.4.0"
+  version: "2.4.1"
 tags:
   - fastify
   - rest-api
@@ -452,6 +452,18 @@ auth: async (headers) => {
 
 **Multi-tenancy**: `organizationId` from auth flows into BaseController org-scoping automatically.
 
+**Permission filters**: `PermissionResult.filters` from resource permissions flow into MCP tools — same as REST. Define once, works everywhere:
+
+```typescript
+permissions: {
+  list: (ctx) => ({
+    granted: !!ctx.user,
+    filters: { orgId: ctx.user?.orgId, branchId: ctx.user?.branchId },
+  }),
+}
+// MCP tools automatically scope queries by orgId + branchId
+```
+
 **Project structure** — custom MCP tools co-located with resources:
 
 ```

package/skills/arc/references/mcp.md

@@ -35,9 +35,11 @@ Tool handlers call `BaseController` — same pipeline as REST (auth, org-scoping
 | `serverName` | `string` | `'arc-mcp'` | Server identity |
 | `serverVersion` | `string` | `'1.0.0'` | Server version |
 | `instructions` | `string` | — | LLM guidance on tool usage |
+| `include` | `string[]` | — | Only these resources get tools (overrides `exclude`) |
 | `exclude` | `string[]` | — | Resource names to exclude |
-| `toolNamePrefix` | `string` | — | Prefix: `'crm'` → `crm_list_products` |
-| `overrides` | `Record<string, McpResourceConfig>` | — | Per-resource operation/field overrides |
+| `toolNamePrefix` | `string` | — | Global prefix: `'crm'` → `crm_list_products` |
+| `overrides` | `Record<string, McpResourceConfig>` | — | Per-resource overrides (see below) |
+| `authCacheTtlMs` | `number` | — | Cache auth results for N ms in stateless mode |
 | `extraTools` | `ToolDefinition[]` | — | Hand-written tools alongside auto-generated |
 | `extraPrompts` | `PromptDefinition[]` | — | Custom prompts |
 | `stateful` | `boolean` | `false` | `false` = stateless (default, scalable). `true` = session-cached. |
@@ -52,6 +54,49 @@ Tool handlers call `BaseController` — same pipeline as REST (auth, org-scoping
 | `create` | `destructiveHint: false` |
 | `update`, `delete` | `destructiveHint: true, idempotentHint: true` |
 
+### Per-Resource Overrides
+
+```typescript
+await app.register(mcpPlugin, {
+  resources,
+  include: ['job', 'project'],                // only expose these
+  overrides: {
+    job: {
+      operations: ['list', 'get'],             // restrict ops
+      toolNamePrefix: 'db',                    // db_list_jobs, db_get_job
+      names: { get: 'get_job_by_id' },         // custom name for specific op
+      hideFields: ['internalScore'],           // strip from schema
+      descriptions: { list: 'Browse jobs' },   // custom descriptions
+    },
+  },
+});
+```
+
+### Permission Filters (v2.4.2)
+
+Resource permissions with `filters` are automatically enforced in MCP tools — same as REST:
+
+```typescript
+defineResource({
+  name: 'task',
+  permissions: {
+    list: (ctx) => ({
+      granted: !!ctx.user,
+      filters: { orgId: ctx.user?.orgId, branchId: ctx.user?.branchId },
+    }),
+    create: (ctx) => !!ctx.user,                    // boolean works too
+    delete: (ctx) => ({ granted: false, reason: 'Read-only' }),  // deny
+  },
+});
+
+// MCP tools automatically:
+// - list_tasks scopes by orgId + branchId from permission filters
+// - create_task allowed if user is authenticated
+// - delete_task returns "Permission denied: delete on task"
+```
+
+No extra config. `PermissionResult.filters` flow into `_policyFilters` → `BaseController.AccessControl`.
+
 ### Multiple MCP Endpoints
 
 Mount separate servers scoped to different resource groups: