@nextsparkjs/core 0.1.0-beta.184 → 0.1.0-beta.185

package/dist/templates/app/api/mcp/route.ts

@@ -0,0 +1,173 @@
+/**
+ * MCP endpoint — POST /api/mcp (Streamable HTTP, stateless JSON mode).
+ *
+ * Auth: API key ONLY (Authorization: Bearer sk_... or x-api-key). Session
+ * cookies are rejected — this endpoint is for MCP clients, not browsers.
+ * authenticateRequest runs ONCE here; the resolved identity, team context and
+ * api_key id travel to every tool via ToolExecutionContext.
+ *
+ * Tools and overrides are entirely registry-driven: every access.api-enabled
+ * entity in ENTITY_REGISTRY becomes a set of tools automatically, and any
+ * `entities/<slug>/mcp.ts` a theme defines is picked up via the generated
+ * MCP_OVERRIDES registry — no per-app hand-wiring required.
+ *
+ * Security posture:
+ * - kill-switch: MCP_ENABLED (dev: on unless 'false'; production: OFF unless 'true')
+ * - Origin validated when present (DNS-rebinding protection); no CORS reflection
+ * - rate limit: tier 'api' — with the in-process executor this is the ONLY
+ *   rate limit on the whole MCP surface (deploy prerequisite: Redis)
+ * - team-role permissions + scopes + ownership/field guards come from the
+ *   real generic entity handlers the executor calls in-process (#94/#95)
+ * - every tool call is audited to api_audit_log
+ */
+
+import { NextRequest, NextResponse } from 'next/server'
+import {
+  authenticateRequest,
+  resolveTeamContext,
+} from '@nextsparkjs/core/lib/api/auth/dual-auth'
+import { validateApiKey } from '@nextsparkjs/core/lib/api/auth'
+import { withRateLimitTier } from '@nextsparkjs/core/lib/api/rate-limit'
+import { setEntityRegistry } from '@nextsparkjs/core/lib/entities/queries'
+import { createMcpEngine } from '@nextsparkjs/core/lib/mcp'
+import type { ToolExecutionContext } from '@nextsparkjs/core/lib/mcp'
+import type { EntityConfig } from '@nextsparkjs/core/lib/entities/types'
+// Import registries directly - webpack resolves @nextsparkjs/registries alias at compile time
+import { ENTITY_REGISTRY, ENTITY_METADATA } from '@nextsparkjs/registries/entity-registry'
+import { MCP_OVERRIDES } from '@nextsparkjs/registries/mcp-registry'
+import { API_PRESETS_REGISTRY } from '@nextsparkjs/registries/api-presets-registry'
+
+// Initialize registry at module load time (before any handler runs)
+setEntityRegistry(ENTITY_REGISTRY, ENTITY_METADATA)
+
+// Registry entries are wrappers ({ name, config, tableName, ... }) — the
+// engine consumes the EntityConfig map.
+const entityConfigs = Object.fromEntries(
+  Object.entries(ENTITY_REGISTRY as Record<string, { config: EntityConfig }>).map(
+    ([slug, entry]) => [slug, entry.config]
+  )
+)
+
+// Tool descriptions are seeded from api/presets.ts (summary → entity
+// description, presets → few-shot examples) — the same registry the API
+// Explorer already uses, keyed by endpoint instead of slug here.
+const presetsBySlug = Object.fromEntries(
+  Object.entries(API_PRESETS_REGISTRY.endpoints ?? {}).map(([endpoint, data]) => [
+    endpoint.replace(/^\/api\/v1\//, ''),
+    { summary: data.summary, presets: data.presets },
+  ])
+)
+
+const toolPrefix = (process.env.MCP_TOOL_PREFIX || process.env.NEXT_PUBLIC_ACTIVE_THEME || 'app')
+  .toLowerCase()
+  .replace(/[^a-z0-9]+/g, '_')
+  .replace(/^_+|_+$/g, '')
+
+const engine = createMcpEngine(entityConfigs, {
+  toolPrefix,
+  overrides: MCP_OVERRIDES,
+  presets: presetsBySlug,
+})
+
+const API_KEY_HELP =
+  'This endpoint requires an API key: generate one in Settings → API Keys and configure it in your MCP client as the header "Authorization: Bearer sk_...".'
+
+function isMcpEnabled(): boolean {
+  const flag = process.env.MCP_ENABLED
+  if (process.env.NODE_ENV === 'production') return flag === 'true'
+  return flag !== 'false'
+}
+
+function isOriginAllowed(request: NextRequest): boolean {
+  const origin = request.headers.get('origin')
+  if (!origin) return true // non-browser MCP clients don't send Origin
+  const allowed = new Set(
+    [request.nextUrl.origin, process.env.NEXT_PUBLIC_APP_URL, process.env.BETTER_AUTH_URL].filter(
+      Boolean
+    )
+  )
+  return allowed.has(origin)
+}
+
+function jsonRpcError(
+  status: number,
+  code: number,
+  message: string,
+  id: string | number | null = null
+): NextResponse {
+  return NextResponse.json({ jsonrpc: '2.0', error: { code, message }, id }, { status })
+}
+
+async function handleMcpPost(request: NextRequest): Promise<NextResponse> {
+  if (!isMcpEnabled()) {
+    return NextResponse.json({ error: 'Not found' }, { status: 404 })
+  }
+  if (!isOriginAllowed(request)) {
+    return jsonRpcError(403, -32000, 'Origin not allowed')
+  }
+
+  const authResult = await authenticateRequest(request)
+  if (!authResult.success || authResult.type !== 'api-key' || !authResult.user) {
+    return jsonRpcError(401, -32001, API_KEY_HELP)
+  }
+
+  // Same cached lookup the auth already did — needed for the audit trail.
+  const apiKeyAuth = await validateApiKey(request)
+
+  const teamResult = await resolveTeamContext(request, authResult)
+  if (teamResult instanceof Response) {
+    const status = teamResult.status
+    return jsonRpcError(
+      status,
+      -32002,
+      status === 403
+        ? 'The API key user is not a member of the team specified in x-team-id.'
+        : 'Could not resolve the user team. Send the x-team-id header or assign a default team.'
+    )
+  }
+
+  let body: unknown
+  try {
+    body = await request.json()
+  } catch {
+    return jsonRpcError(400, -32700, 'Parse error: body must be JSON-RPC')
+  }
+
+  const ctx: ToolExecutionContext = {
+    userId: authResult.user.id,
+    userRole: authResult.user.role,
+    teamId: teamResult,
+    authHeader:
+      request.headers.get('authorization') ?? `Bearer ${request.headers.get('x-api-key') ?? ''}`,
+    apiKeyId: apiKeyAuth?.keyId ?? null,
+    scopes: authResult.scopes ?? [],
+  }
+
+  try {
+    const result = await engine.handleJsonRpc(body, ctx)
+    if (result === null) {
+      // Notification(s) only — accepted, nothing to return.
+      return new NextResponse(null, { status: 202 })
+    }
+    return NextResponse.json(result, { status: 200 })
+  } catch (error) {
+    console.error('[mcp] request failed:', error)
+    return jsonRpcError(500, -32603, 'Internal error processing MCP request')
+  }
+}
+
+export const POST = withRateLimitTier(handleMcpPost, 'api')
+
+export async function GET(): Promise<NextResponse> {
+  return NextResponse.json(
+    { error: 'Method not allowed. MCP requests must be POST (stateless JSON mode, no SSE).' },
+    { status: 405, headers: { Allow: 'POST' } }
+  )
+}
+
+export async function DELETE(): Promise<NextResponse> {
+  return NextResponse.json(
+    { error: 'Method not allowed. This server is stateless: there is no session to delete.' },
+    { status: 405, headers: { Allow: 'POST' } }
+  )
+}

package/dist/templates/app/api/v1/api-keys/route.ts

@@ -7,7 +7,7 @@ import {
   handleCorsPreflightRequest,
   addCorsHeaders
 } from '@nextsparkjs/core/lib/api/helpers';
-import { authenticateRequest, hasRequiredScope } from '@nextsparkjs/core/lib/api/auth/dual-auth';
+import { authenticateRequest, hasRequiredScope, resolveTeamContext } from '@nextsparkjs/core/lib/api/auth/dual-auth';
 import { ApiKeyManager, API_SCOPES, API_KEY_LIMITS } from '@nextsparkjs/core/lib/api/keys';
 import { validateScopesForUser } from '@nextsparkjs/core/lib/api/auth';
 import { withRateLimitTier } from '@nextsparkjs/core/lib/api/rate-limit';
@@ -177,8 +177,20 @@ export const POST = withRateLimitTier(withApiLogging(async (req: NextRequest): P
       return addCorsHeaders(response);
     }
 
-    // Validar que el usuario pueda crear API keys con estos scopes
-    const userScopeValidation = await validateScopesForUser(authResult.user!.id, validatedData.scopes);
+    // Validar que el usuario pueda crear API keys con estos scopes.
+    // Scope minting is TEAM-role based (see validateScopesForUser) — resolve
+    // the team this key is being minted for, unless the caller is a global
+    // superadmin, which validateScopesForUser bypasses regardless of team.
+    let teamId: string | null = null;
+    if (authResult.user!.role !== 'superadmin') {
+      const teamResult = await resolveTeamContext(req, authResult);
+      if (teamResult instanceof NextResponse) {
+        return teamResult;
+      }
+      teamId = teamResult;
+    }
+
+    const userScopeValidation = await validateScopesForUser(authResult.user!.id, teamId, validatedData.scopes);
     if (!userScopeValidation.valid) {
       const response = createApiError(
         'You do not have permission to create API keys with these scopes', 

package/dist/templates/app/layout.tsx

@@ -5,6 +5,7 @@
  */
 
 import type { Metadata } from "next"
+import { Suspense } from "react"
 import { Geist, Geist_Mono } from "next/font/google"
 import { NextIntlClientProvider } from 'next-intl'
 import { getMessages } from 'next-intl/server'
@@ -13,6 +14,7 @@ import "./globals.css"
 import { getBillingResourceHints } from "@nextsparkjs/core/lib/billing/gateways/factory"
 import { ThemeProvider as NextThemeProvider } from "@nextsparkjs/core/providers/theme-provider"
 import { ThemeProvider as CustomThemeProvider } from "@nextsparkjs/core/lib/theme/ThemeProvider"
+import { Toaster } from "@nextsparkjs/core/components/ui/sonner"
 import { getUserLocale } from '@nextsparkjs/core/lib/locale'
 import { TranslationContextManager } from "@nextsparkjs/core/providers/TranslationContextManager"
 import { PluginService } from '@nextsparkjs/core/lib/services'
@@ -85,6 +87,7 @@ export default async function RootLayout({
             <CustomThemeProvider>
               <TranslationContextManager />
               <main>{children}</main>
+              <Suspense><Toaster position="bottom-left" /></Suspense>
             </CustomThemeProvider>
           </NextThemeProvider>
         </NextIntlClientProvider>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nextsparkjs/core",
-  "version": "0.1.0-beta.184",
+  "version": "0.1.0-beta.185",
   "description": "NextSpark - The complete SaaS framework for Next.js",
   "license": "MIT",
   "author": "NextSpark <hello@nextspark.dev>",
@@ -64,6 +64,10 @@
       "types": "./dist/lib/services/index.d.ts",
       "import": "./dist/lib/services/index.js"
     },
+    "./lib/mcp": {
+      "types": "./dist/lib/mcp/index.d.ts",
+      "import": "./dist/lib/mcp/index.js"
+    },
     "./lib/config": {
       "types": "./dist/lib/config/index.d.ts",
       "import": "./dist/lib/config/index.js"
@@ -403,6 +407,7 @@
     "@dnd-kit/utilities": "^3.2.2",
     "@hookform/resolvers": "^5.2.1",
     "@inquirer/prompts": "^7.2.0",
+    "@modelcontextprotocol/sdk": "^1.30.0",
     "@nextsparkjs/ui": "^0.1.0-beta.2",
     "@polar-sh/sdk": "^0.43.1",
     "@radix-ui/react-accordion": "^1.2.12",
@@ -437,7 +442,7 @@
     "@upstash/ratelimit": "^2.0.3",
     "@upstash/redis": "^1.20.6",
     "@vercel/blob": "^2.0.0",
-    "better-auth": "^1.3.5",
+    "better-auth": "~1.6.30",
     "chalk": "^5.4.1",
     "jiti": "^2.7.0",
     "kysely": "0.28.17",
@@ -470,7 +475,7 @@
     "tailwind-merge": "^3.3.1",
     "uuid": "^13.0.0",
     "zod": "^4.1.5",
-    "@nextsparkjs/testing": "0.1.0-beta.184"
+    "@nextsparkjs/testing": "0.1.0-beta.185"
   },
   "scripts": {
     "postinstall": "node scripts/postinstall.mjs || true",

package/scripts/build/registry/__tests__/mcp-registry.test.mjs

@@ -0,0 +1,64 @@
+/**
+ * Tests for the mcp-registry generator.
+ *
+ * Run: node --test packages/core/scripts/build/registry/__tests__/mcp-registry.test.mjs
+ */
+
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { generateMcpRegistry } from '../generators/mcp-registry.mjs'
+
+const CONFIG = { outputDir: '/project/.nextspark/registries', isNpmMode: false }
+
+test('emits an empty MCP_OVERRIDES map when no overrides were discovered', () => {
+  const out = generateMcpRegistry([], CONFIG)
+  assert.match(out, /export const MCP_OVERRIDES: Record<string, McpEntityOverride> = \{\s*\}/)
+  assert.doesNotMatch(out, /^import .+McpOverride/m)
+})
+
+test('emits one literal import + map entry per discovered override', () => {
+  const out = generateMcpRegistry(
+    [{ slug: 'customers', importPath: '@/contents/themes/default/entities/customers/mcp', themeName: 'default' }],
+    CONFIG
+  )
+  assert.match(out, /import CustomersMcpOverride from '@\/contents\/themes\/default\/entities\/customers\/mcp'/)
+  assert.match(out, /'customers': CustomersMcpOverride,/)
+})
+
+test('imports the McpEntityOverride type from @/core/lib/mcp in monorepo mode', () => {
+  const out = generateMcpRegistry([], CONFIG)
+  assert.match(out, /import type \{ McpEntityOverride \} from '@\/core\/lib\/mcp'/)
+})
+
+test('converts @/core/lib/mcp to @nextsparkjs/core/lib/mcp in npm mode', () => {
+  const out = generateMcpRegistry([], { ...CONFIG, isNpmMode: true })
+  assert.match(out, /import type \{ McpEntityOverride \} from '@nextsparkjs\/core\/lib\/mcp'/)
+})
+
+test('PascalCases hyphenated/underscored/nested slugs into a valid identifier', () => {
+  const out = generateMcpRegistry(
+    [
+      { slug: 'meal-plans', importPath: '@/contents/themes/default/entities/meal-plans/mcp' },
+      { slug: 'pantry_items', importPath: '@/contents/themes/default/entities/pantry_items/mcp' },
+    ],
+    CONFIG
+  )
+  assert.match(out, /import MealPlansMcpOverride from/)
+  assert.match(out, /import PantryItemsMcpOverride from/)
+  assert.match(out, /'meal-plans': MealPlansMcpOverride,/)
+  assert.match(out, /'pantry_items': PantryItemsMcpOverride,/)
+})
+
+test('handles multiple overrides, one import + entry each, in discovery order', () => {
+  const out = generateMcpRegistry(
+    [
+      { slug: 'customers', importPath: '@/contents/themes/default/entities/customers/mcp' },
+      { slug: 'tasks', importPath: '@/contents/themes/default/entities/tasks/mcp' },
+    ],
+    CONFIG
+  )
+  const importLines = out.match(/^import \w+McpOverride from .+$/gm) ?? []
+  assert.equal(importLines.length, 2)
+  assert.match(out, /'customers': CustomersMcpOverride,[\s\S]*'tasks': TasksMcpOverride,/)
+})

package/scripts/build/registry/__tests__/scope-registry.test.mjs

@@ -0,0 +1,88 @@
+/**
+ * Tests for the scope-registry generator.
+ *
+ * The role→scope computation no longer happens at generation time (see the
+ * rationale comment at the top of `generators/scope-registry.mjs`) — it's
+ * emitted as TypeScript that computes `SCOPE_CONFIG.roles` at IMPORT time,
+ * from the sibling generated `entity-registry.ts`/`permissions-registry.ts`.
+ * So this generator-level test can only assert on the EMITTED source: the
+ * correct static imports, the defensive entity-registry guard, the
+ * role/permission-derived scope logic, and the untouched flag/restriction
+ * literals. The actual `SCOPE_CONFIG.roles` VALUES for a real role are
+ * covered by `packages/core/tests/jest/services/scope.service.test.ts`
+ * (against a realistic mock) and by manual inspection of the real generated
+ * output after `node packages/core/scripts/build/registry.mjs`.
+ *
+ * Run: node --test packages/core/scripts/build/registry/__tests__/scope-registry.test.mjs
+ */
+
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { generateScopeRegistry } from '../generators/scope-registry.mjs'
+
+test('imports ENTITY_REGISTRY and AVAILABLE_ROLES/PERMISSIONS_BY_ROLE from sibling generated registries', () => {
+  const out = generateScopeRegistry([], {})
+  assert.match(out, /import \{ ENTITY_REGISTRY \} from '\.\/entity-registry'/)
+  assert.match(out, /import \{ AVAILABLE_ROLES, PERMISSIONS_BY_ROLE \} from '\.\/permissions-registry'/)
+})
+
+test('does not reintroduce the old generation-time entities/config computation', () => {
+  const out = generateScopeRegistry([{ name: 'ignored', api: { endpoints: { create: true } } }], { some: 'config' })
+  // The old bug read entity.api.endpoints/entity.features/entity.fields directly —
+  // none of those property paths should appear in the emitted output at all,
+  // since the real computation now reads ENTITY_REGISTRY's real EntityConfig.
+  assert.doesNotMatch(out, /entity\.api\.endpoints/)
+  assert.doesNotMatch(out, /entity\.features/)
+})
+
+test('base scopes are empty — nothing granted irrespective of role', () => {
+  const out = generateScopeRegistry([], {})
+  assert.match(out, /base:\s*\[\]/)
+})
+
+test('role scopes are computed from PERMISSIONS_BY_ROLE per AVAILABLE_ROLES, not hardcoded role names', () => {
+  const out = generateScopeRegistry([], {})
+  assert.match(out, /for \(const role of AVAILABLE_ROLES\)/)
+  assert.match(out, /const perms = PERMISSIONS_BY_ROLE\[role\]/)
+  // The old hardcoded roleScopes literal (superadmin/admin/manager/member keys,
+  // referencing a nonexistent "products" entity) must be gone.
+  assert.doesNotMatch(out, /'manager'/)
+  assert.doesNotMatch(out, /products:write/)
+  assert.doesNotMatch(out, /products:delete/)
+})
+
+test('read/write/delete scopes are derived from list|read / create|update / delete permissions', () => {
+  const out = generateScopeRegistry([], {})
+  assert.match(out, /\$\{slug\}\.list.*Permission.*\|\|.*perms\?\.has\(`\$\{slug\}\.read`/)
+  assert.match(out, /\$\{slug\}\.create.*Permission.*\|\|.*perms\?\.has\(`\$\{slug\}\.update`/)
+  assert.match(out, /\$\{slug\}\.delete.*Permission/)
+  assert.match(out, /scopes\.push\(`\$\{slug\}:read`\)/)
+  assert.match(out, /scopes\.push\(`\$\{slug\}:write`\)/)
+  assert.match(out, /scopes\.push\(`\$\{slug\}:delete`\)/)
+})
+
+test('guards against ChildEntityDefinition entries (no access/slug) in ENTITY_REGISTRY', () => {
+  const out = generateScopeRegistry([], {})
+  assert.match(out, /if \(!cfg\?\.access\?\.api \|\| !cfg\.slug\) return null/)
+})
+
+test('flag scopes and restrictions are preserved unchanged', () => {
+  const out = generateScopeRegistry([], {})
+  assert.match(out, /beta_tester/)
+  assert.match(out, /vip:features/)
+  assert.match(out, /"remove": \[\s*"delete",\s*"admin"\s*\]/)
+  assert.match(out, /"allow_only": \[\s*"read",\s*"tasks:write"\s*\]/)
+})
+
+test('superadmin is not hardcoded into SCOPE_CONFIG.roles — handled as a global-role bypass elsewhere', () => {
+  const out = generateScopeRegistry([], {})
+  assert.doesNotMatch(out, /'superadmin':\s*\[/)
+  assert.match(out, /Superadmin is a GLOBAL role/)
+})
+
+test('is a pure function of its output shape — always emits both SCOPE_CONFIG and API_CONFIG exports', () => {
+  const out = generateScopeRegistry([], {})
+  assert.match(out, /export const SCOPE_CONFIG: ScopeConfig = \{/)
+  assert.match(out, /export const API_CONFIG: ApiConfig = \{/)
+})

package/scripts/build/registry/discovery/mcp-overrides.mjs

@@ -0,0 +1,72 @@
+/**
+ * MCP Override Discovery
+ *
+ * Discovers `entities/<slug>/mcp.ts` files for the active theme — the
+ * extension point a theme uses to customize how one entity is exposed by the
+ * MCP engine (@nextsparkjs/core/lib/mcp): exclude it, exclude specific
+ * operations, relax required fields, transform input/output, or add extra
+ * (non-CRUD) tools.
+ *
+ * Mirrors discoverApiPresets's discoverEntityFolders (same
+ * `{theme}/entities/<slug>/` scan, same theme-only scope) with one
+ * difference: `mcp.ts` sits at the entity folder root (a sibling of `api/`,
+ * `migrations/`, `messages/`), not nested under `api/` like `presets.ts`.
+ *
+ * Unlike the presets discovery, this module does NOT parse file contents —
+ * an McpEntityOverride exports real functions (transformInput, extraTools),
+ * which can't be recovered by regex/brace-counting. The generator instead
+ * emits a literal `import` statement per discovered file (same approach as
+ * entity-registry.mjs), and the override object itself is resolved by the
+ * TypeScript compiler/bundler at build time, not by this script.
+ *
+ * @module core/scripts/build/registry/discovery/mcp-overrides
+ */
+
+import { readdir } from 'fs/promises'
+import { join } from 'path'
+import { existsSync } from 'fs'
+
+import { log, verbose } from '../../../utils/index.mjs'
+
+/**
+ * Discover MCP entity overrides for the active theme.
+ * @param {object} config - Configuration object from getConfig()
+ * @returns {Promise<Array<{slug: string, importPath: string, themeName: string}>>}
+ */
+export async function discoverMcpOverrides(config) {
+  const overrides = []
+  const themeName = config.activeTheme
+
+  if (!themeName) {
+    verbose('[mcp-overrides] No active theme configured — skipping MCP override discovery')
+    return overrides
+  }
+
+  const entitiesDir = join(config.themesDir, themeName, 'entities')
+  if (!existsSync(entitiesDir)) {
+    verbose(`[mcp-overrides] No entities directory found for theme "${themeName}"`)
+    return overrides
+  }
+
+  try {
+    const entries = await readdir(entitiesDir, { withFileTypes: true })
+    const entityDirs = entries.filter((entry) => entry.isDirectory())
+
+    for (const dir of entityDirs) {
+      const entityName = dir.name
+      const mcpPath = join(entitiesDir, entityName, 'mcp.ts')
+      if (!existsSync(mcpPath)) continue
+
+      overrides.push({
+        slug: entityName,
+        importPath: `@/contents/themes/${themeName}/entities/${entityName}/mcp`,
+        themeName,
+      })
+      verbose(`[mcp-overrides] MCP override discovered: ${entityName} -> ${mcpPath}`)
+    }
+  } catch (error) {
+    log(`[mcp-overrides] Error discovering MCP overrides: ${error.message}`, 'error')
+  }
+
+  return overrides
+}

package/scripts/build/registry/discovery/mcp-overrides.test.mjs

@@ -0,0 +1,86 @@
+/**
+ * Tests for discoverMcpOverrides.
+ *
+ * Run: node --test packages/core/scripts/build/registry/discovery/mcp-overrides.test.mjs
+ */
+
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { mkdtemp, mkdir, writeFile, rm } from 'fs/promises'
+import { tmpdir } from 'os'
+import { join } from 'path'
+
+import { discoverMcpOverrides } from './mcp-overrides.mjs'
+
+async function makeThemeFixture(entities) {
+  const root = await mkdtemp(join(tmpdir(), 'mcp-overrides-test-'))
+  const themesDir = join(root, 'themes')
+  const themeName = 'testtheme'
+  const entitiesDir = join(themesDir, themeName, 'entities')
+
+  for (const [slug, files] of Object.entries(entities)) {
+    const entityDir = join(entitiesDir, slug)
+    await mkdir(entityDir, { recursive: true })
+    for (const file of files) {
+      await writeFile(join(entityDir, file), '// fixture\n')
+    }
+  }
+
+  return { root, themesDir, themeName }
+}
+
+test('returns an empty array when there is no active theme', async () => {
+  const result = await discoverMcpOverrides({ activeTheme: undefined, themesDir: '/nonexistent' })
+  assert.deepEqual(result, [])
+})
+
+test('returns an empty array when the theme has no entities directory', async () => {
+  const root = await mkdtemp(join(tmpdir(), 'mcp-overrides-test-'))
+  const result = await discoverMcpOverrides({ activeTheme: 'ghost', themesDir: join(root, 'themes') })
+  assert.deepEqual(result, [])
+  await rm(root, { recursive: true, force: true })
+})
+
+test('finds mcp.ts at the entity folder root, not nested under api/', async () => {
+  const { root, themesDir, themeName } = await makeThemeFixture({
+    customers: ['customers.config.ts', 'mcp.ts'],
+  })
+  const result = await discoverMcpOverrides({ activeTheme: themeName, themesDir })
+  assert.equal(result.length, 1)
+  assert.equal(result[0].slug, 'customers')
+  assert.equal(result[0].importPath, `@/contents/themes/${themeName}/entities/customers/mcp`)
+  await rm(root, { recursive: true, force: true })
+})
+
+test('skips entities that have no mcp.ts', async () => {
+  const { root, themesDir, themeName } = await makeThemeFixture({
+    customers: ['customers.config.ts', 'mcp.ts'],
+    tasks: ['tasks.config.ts'],
+  })
+  const result = await discoverMcpOverrides({ activeTheme: themeName, themesDir })
+  assert.deepEqual(result.map((r) => r.slug), ['customers'])
+  await rm(root, { recursive: true, force: true })
+})
+
+test('does NOT match a preset-style entities/<slug>/api/mcp.ts (wrong location)', async () => {
+  const root = await mkdtemp(join(tmpdir(), 'mcp-overrides-test-'))
+  const themesDir = join(root, 'themes')
+  const themeName = 'testtheme'
+  await mkdir(join(themesDir, themeName, 'entities', 'customers', 'api'), { recursive: true })
+  await writeFile(join(themesDir, themeName, 'entities', 'customers', 'api', 'mcp.ts'), '// wrong spot\n')
+
+  const result = await discoverMcpOverrides({ activeTheme: themeName, themesDir })
+  assert.deepEqual(result, [])
+  await rm(root, { recursive: true, force: true })
+})
+
+test('discovers multiple entity overrides in the same theme', async () => {
+  const { root, themesDir, themeName } = await makeThemeFixture({
+    customers: ['mcp.ts'],
+    tasks: ['mcp.ts'],
+    posts: [],
+  })
+  const result = await discoverMcpOverrides({ activeTheme: themeName, themesDir })
+  assert.deepEqual(result.map((r) => r.slug).sort(), ['customers', 'tasks'])
+  await rm(root, { recursive: true, force: true })
+})

package/scripts/build/registry/generators/mcp-registry.mjs

@@ -0,0 +1,61 @@
+/**
+ * MCP Override Registry Generator
+ *
+ * Generates mcp-registry.ts: a literal-import map of discovered
+ * `entities/<slug>/mcp.ts` files (see discovery/mcp-overrides.mjs), consumed
+ * by the default `/api/mcp` route template to build the `overrides` option
+ * passed to `createMcpEngine`. Follows entity-registry.mjs's literal-import
+ * pattern (not the regex-parsing approach used for api-presets.ts) because
+ * an McpEntityOverride exports real functions — transformInput, extraTools —
+ * that can't be recovered from source text.
+ *
+ * @module core/scripts/build/registry/generators/mcp-registry
+ */
+
+import { join } from 'path'
+import { convertCorePath } from '../config.mjs'
+
+/**
+ * Generate the MCP override registry file.
+ * @param {Array<{slug: string, importPath: string, themeName: string}>} mcpOverrides - Discovered overrides
+ * @param {object} config - Configuration object from getConfig()
+ * @returns {string} Generated TypeScript content
+ */
+export function generateMcpRegistry(mcpOverrides, config) {
+  const outputFilePath = join(config.outputDir, 'mcp-registry.ts')
+
+  const importName = (slug) => `${toPascalCase(slug)}McpOverride`
+
+  const imports = mcpOverrides
+    .map((entry) => `import ${importName(entry.slug)} from '${entry.importPath}'`)
+    .join('\n')
+
+  const entries = mcpOverrides
+    .map((entry) => `  '${entry.slug}': ${importName(entry.slug)},`)
+    .join('\n')
+
+  return `/**
+ * Auto-generated MCP Override Registry
+ *
+ * Generated at: ${new Date().toISOString()}
+ * MCP overrides discovered: ${mcpOverrides.length}
+ *
+ * DO NOT EDIT - This file is auto-generated by scripts/build/registry.mjs
+ */
+
+${imports}
+import type { McpEntityOverride } from '${convertCorePath('@/core/lib/mcp', outputFilePath, config)}'
+
+export const MCP_OVERRIDES: Record<string, McpEntityOverride> = {
+${entries}
+}
+`
+}
+
+function toPascalCase(slug) {
+  return slug
+    .split(/[-_/]+/)
+    .filter(Boolean)
+    .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+    .join('')
+}