velocious 1.0.692 → 1.0.694

package/src/configuration.js

@@ -26,6 +26,7 @@ import UUID from "pure-uuid"
 import translate from "gettext-universal/build/src/translate.js"
 import Ability from "./authorization/ability.js"
 import BackgroundJobsAdapter from "./background-jobs/adapter.js"
+import {DEFAULT_SCHEDULED_ENQUEUE_TIMEOUT_MS} from "./background-jobs/scheduled-enqueue-bound.js"
 import DatabaseOperation from "./database/operation.js"
 import { initializeAuditedModelRelationships } from "./database/record/auditing.js"
 import EventEmitter from "./utils/event-emitter.js"
@@ -259,7 +260,7 @@ export default class VelociousConfiguration {
    * Runs constructor.
    * @param {import("./configuration-types.js").ConfigurationArgsType} args - Configuration arguments.
    */
-  constructor({abilityResolver, abilityResources, attachments, autoload = true, backgroundJobs, backendProjects, beacon, cookieSecret, cors, database, debug = false, debugEndpoint = false, apiManifest = false, directory, enforceTenantDatabaseScopes = true, environment, environmentHandler, exposeInternalErrorsToClients, frontendTenantSqlite, httpServer, initializeModels, initializers, locale, localeFallbacks, locales, logging, mailerBackend, packages, requestTimeoutMs, routeResolverHooks, scheduledBackgroundJobs, secureFrontendModelErrors, structureSql, sync, tenantDatabaseProviders, tenantDatabaseResolver, tenantResolver, testing, timeZone, timezoneOffsetMinutes, trustedProxies, websocketChannelResolver, websocketMessageHandlerResolver, ...restArgs}) {
+  constructor({abilityResolver, abilityResources, attachments, autoload = true, backgroundJobs, backendProjects, beacon, cookieSecret, cors, database, debug = false, debugEndpoint = false, apiManifest = false, directory, enforceTenantDatabaseScopes = true, environment, environmentHandler, exposeInternalErrorsToClients, frontendTenantSqlite, httpServer, initializeModels, initializers, locale, localeFallbacks, locales, logging, mailerBackend, mcp = false, packages, requestTimeoutMs, routeResolverHooks, scheduledBackgroundJobs, secureFrontendModelErrors, structureSql, sync, tenantDatabaseProviders, tenantDatabaseResolver, tenantResolver, testing, timeZone, timezoneOffsetMinutes, trustedProxies, websocketChannelResolver, websocketMessageHandlerResolver, ...restArgs}) {
     restArgsError(restArgs)
 
     this._abilityResolver = abilityResolver
@@ -303,6 +304,7 @@ export default class VelociousConfiguration {
     this.debug = debug
     this._debugEndpoint = this._normalizeDebugEndpoint(debugEndpoint)
     this._apiManifest = this._normalizeApiManifest(apiManifest)
+    this._mcp = this._normalizeMcp(mcp)
     this._environment = environment || globalThis.process?.env.VELOCIOUS_ENV || globalThis.process?.env.NODE_ENV || "development"
     this._environmentHandler = environmentHandler
     this._enforceTenantDatabaseScopes = enforceTenantDatabaseScopes
@@ -485,6 +487,7 @@ export default class VelociousConfiguration {
     this._routeResolverHooks = [...(routeResolverHooks || [])]
     this._addDebugEndpointRouteHook()
     this._addApiManifestRouteHook()
+    this._addMcpRouteHook()
 
     /**
      * Stores the applied route mounts value.
@@ -624,6 +627,63 @@ export default class VelociousConfiguration {
     })
   }
 
+  /**
+   * Runs normalize mcp.
+   * @param {boolean | {path?: string, token?: string}} value - MCP endpoint configuration.
+   * @returns {{enabled: boolean, path: string, token: string | null}} - Normalized MCP endpoint configuration.
+   */
+  _normalizeMcp(value) {
+    if (value === false || value === undefined) return {enabled: false, path: "/mcp", token: null}
+    if (value === true) return {enabled: true, path: "/mcp", token: null}
+
+    if (typeof value !== "object" || value === null) {
+      throw new Error(`Expected mcp to be a boolean or object, got: ${String(value)}`)
+    }
+
+    const path = value.path || "/mcp"
+
+    if (typeof path !== "string" || !path.startsWith("/")) {
+      throw new Error(`Expected mcp.path to be a string starting with '/', got: ${String(path)}`)
+    }
+
+    const token = value.token === undefined || value.token === null ? null : value.token
+
+    if (token !== null && (typeof token !== "string" || !token.trim())) {
+      throw new Error(`Expected mcp.token to be a non-empty string, got: ${String(token)}`)
+    }
+
+    return {enabled: true, path, token: token === null ? null : token.trim()}
+  }
+
+  /**
+   * Runs add mcp route hook.
+   * @returns {void} - No return value.
+   */
+  _addMcpRouteHook() {
+    if (!this._mcp.enabled) return
+
+    this.addRouteResolverHook(({currentPath, request}) => {
+      if (request.httpMethod() !== "POST") return null
+      if (currentPath !== this._mcp.path) return null
+
+      // When a token is configured, an unauthenticated request gets no route at
+      // all (404) rather than a 401, so the endpoint's existence stays hidden.
+      if (this._mcp.token && !this.debugEndpointRequestAuthorized(request, this._mcp.token)) return null
+
+      return {
+        action: "handle",
+        controller: "velociousMcp",
+        controllerPath: "./built-in/mcp/controller.js",
+        // Tenant and ability resolution belong to the frontend-model dispatcher
+        // per command (withFrontendModelRequestContext), exactly like the regular
+        // /frontend-models route — the MCP transport never bypasses them.
+        skipAbilityResolution: true,
+        skipTenantResolution: true,
+        viewPath: "./built-in/mcp"
+      }
+    })
+  }
+
   /**
    * Runs add debug endpoint route hook.
    * @returns {void} - No return value.
@@ -1041,6 +1101,7 @@ export default class VelociousConfiguration {
       enforceTenantDatabaseScopes: this.getEnforceTenantDatabaseScopes(),
       exposeInternalErrorsToClients: this.getExposeInternalErrorsToClients(),
       initialized: this._isInitialized,
+      mcp: this._mcp.enabled ? {enabled: true, path: this._mcp.path, tokenConfigured: Boolean(this._mcp.token)} : {enabled: false},
       logging: {
         debugLowLevel: this._logging?.debugLowLevel === true,
         outputs: this._logging ? Object.keys(this._logging) : []
@@ -1707,6 +1768,20 @@ export default class VelociousConfiguration {
     const drainStoreOperationTimeoutMs = typeof configured.drainStoreOperationTimeoutMs === "number" && configured.drainStoreOperationTimeoutMs >= 1
       ? configured.drainStoreOperationTimeoutMs
       : 60_000
+    // `null` is an explicit opt-out of the scheduled-enqueue bound. A present
+    // but non-positive number is a mistake, not an opt-out, so it falls back to
+    // the framework default rather than silently disabling the watchdog.
+    const scheduledEnqueueTimeoutMs = "scheduledEnqueueTimeoutMs" in configured
+      ? (
+        configured.scheduledEnqueueTimeoutMs === null ?
+          null
+        : (
+          typeof configured.scheduledEnqueueTimeoutMs === "number" && configured.scheduledEnqueueTimeoutMs > 0 ?
+            configured.scheduledEnqueueTimeoutMs
+          : DEFAULT_SCHEDULED_ENQUEUE_TIMEOUT_MS
+        )
+      )
+      : DEFAULT_SCHEDULED_ENQUEUE_TIMEOUT_MS
     const queues = configured.queues && typeof configured.queues === "object" ? configured.queues : {}
     // An explicit config value wins over the env var — including `null`/`0`,
     // which disable the backstop even when the environment sets a default.
@@ -1732,7 +1807,7 @@ export default class VelociousConfiguration {
 
     const jobClasses = this.getBackgroundJobClasses()
 
-    return {host, port, databaseIdentifier, maxConcurrentForkedJobs, maxConcurrentInlineJobs, mode, pooledRunnerCount, pooledRunnerConcurrency, pooledRunnerMaxJobs, pooledRunnerMaxRssBytes, pooledRunnerMaxLifetimeMs, runnerMaxOldSpaceSizeMb, runnerMallocArenaMax, dispatchStrategy, pollIntervalMs, drainStoreOperationTimeoutMs, queues, jobClasses, jobTimeoutMs, retention, generationId, initialGenerationState, lifecycleSocketPath}
+    return {host, port, databaseIdentifier, maxConcurrentForkedJobs, maxConcurrentInlineJobs, mode, pooledRunnerCount, pooledRunnerConcurrency, pooledRunnerMaxJobs, pooledRunnerMaxRssBytes, pooledRunnerMaxLifetimeMs, runnerMaxOldSpaceSizeMb, runnerMallocArenaMax, dispatchStrategy, pollIntervalMs, drainStoreOperationTimeoutMs, scheduledEnqueueTimeoutMs, queues, jobClasses, jobTimeoutMs, retention, generationId, initialGenerationState, lifecycleSocketPath}
   }
 
   /**

package/src/database/advisory-lock-bound.js

@@ -0,0 +1,16 @@
+// @ts-check
+
+/**
+ * Default bound for one blocking advisory-lock acquisition.
+ *
+ * A blocking `acquireAdvisoryLock(name)` call with no explicit timeout used to park a pooled
+ * connection for the driver's indefinite wait (MySQL/MariaDB: one year). One wedged holder — a
+ * killed process, a runner that died while holding the lock, a connection that never returned —
+ * then convoyed every later caller on the same lock name: the queue kept growing while every pool
+ * connection sat in MariaDB's `User lock` state and no dispatch happened anywhere.
+ *
+ * The default is deliberately far above any contention observed in healthy production operation, so
+ * a legitimate lock handover is never cut off, while a wedged holder stops stealing pool capacity
+ * forever. Pass `null` explicitly to opt back in to the indefinite wait.
+ * @type {number} */
+export const DEFAULT_ADVISORY_LOCK_ACQUIRE_TIMEOUT_MS = 15 * 60 * 1000

package/src/database/drivers/base.js

@@ -160,6 +160,7 @@ import BacktraceCleaner from "../../utils/backtrace-cleaner.js"
 import { getDatabaseAnnotations } from "../annotations.js"
 import { formatDateForDatabase } from "../datetime-storage.js"
 import isDate from "../../utils/is-date.js"
+import {DEFAULT_ADVISORY_LOCK_ACQUIRE_TIMEOUT_MS} from "../advisory-lock-bound.js"
 import Logger from "../../logger.js"
 import Query from "../query/index.js"
 import QueryAbortedError from "../query-aborted-error.js"
@@ -2928,17 +2929,37 @@ export default class VelociousDatabaseDriversBase {
    * same name and let you serialize functionality without blocking readers
    * or writers that do not participate in the same lock.
    * @param {string} name - Lock name.
-   * @param {{timeoutMs?: number | null}} [args] - Optional timeout in milliseconds; `null` or undefined blocks forever.
+   * @param {{timeoutMs?: number | null}} [args] - Optional timeout in milliseconds; `null` blocks forever, and an omitted value uses the database's `advisoryLockAcquireTimeoutMs` or the framework default.
    * @returns {Promise<boolean>} - Resolves to true when the lock has been acquired, false if the timeout elapsed.
    */
   async acquireAdvisoryLock(name, args = {}) {
-    const acquired = await this._acquireAdvisoryLock(name, args)
+    const acquired = await this._acquireAdvisoryLock(name, {timeoutMs: this.advisoryLockAcquireTimeoutMs(args)})
 
     if (acquired) this._trackAdvisoryLock(name)
 
     return acquired
   }
 
+  /**
+   * Resolves the wait bound for one advisory-lock acquisition.
+   * An explicit `timeoutMs` — including an explicit `null` opt-out — always
+   * wins. Otherwise the database configuration's `advisoryLockAcquireTimeoutMs`
+   * applies, and a null there opts out too. Only when neither is configured does
+   * the framework default bound the wait.
+   * @param {{timeoutMs?: number | null}} [args] - Acquisition options from the caller.
+   * @returns {number | null} - Wait bound in milliseconds, or `null` for an indefinite wait.
+   */
+  advisoryLockAcquireTimeoutMs(args = {}) {
+    if (args.timeoutMs !== undefined) return args.timeoutMs
+
+    const configured = this.getArgs()?.advisoryLockAcquireTimeoutMs
+
+    if (configured === null) return null
+    if (typeof configured === "number" && configured >= 0) return configured
+
+    return DEFAULT_ADVISORY_LOCK_ACQUIRE_TIMEOUT_MS
+  }
+
   /**
    * Driver-specific blocking advisory-lock acquisition hook.
    * @abstract

package/src/database/drivers/pgsql/index.js

@@ -22,6 +22,11 @@ import Update from "./sql/update.js"
 
 const PG_TIMESTAMP_WITHOUT_TIMEZONE_OID = 1114
 
+/** Smallest wait between `pg_try_advisory_lock` probes; preserves the historical 50ms cadence for short bounds. */
+const PGSQL_ADVISORY_LOCK_POLL_MIN_INTERVAL_MS = 50
+/** Largest wait between `pg_try_advisory_lock` probes; keeps a long bounded wait from probing tens of thousands of times. */
+const PGSQL_ADVISORY_LOCK_POLL_MAX_INTERVAL_MS = 2000
+
 pgTypes.setTypeParser(PG_TIMESTAMP_WITHOUT_TIMEZONE_OID, (value) => new Date(`${value.replace(" ", "T")}Z`))
 
 export default class VelociousDatabaseDriversPgsql extends Base{
@@ -425,14 +430,32 @@ export default class VelociousDatabaseDriversPgsql extends Base{
     return signed.toString()
   }
 
+  /**
+   * Resolves the `pg_try_advisory_lock` probe cadence for one bounded wait.
+   *
+   * `pg_advisory_lock` has no native timeout, so a bounded acquisition polls. Scaling the interval
+   * with the bound keeps the historical 50ms cadence — and its fast acquisition — for the short
+   * explicit `timeoutMs` values callers already pass, while a long framework default stays
+   * responsive without turning one contended lock into tens of thousands of probe queries.
+   * @param {number} timeoutMs - Bounded wait in milliseconds.
+   * @returns {number} - Probe interval in milliseconds.
+   */
+  static advisoryLockPollIntervalMs(timeoutMs) {
+    return Math.min(
+      Math.max(Math.floor(timeoutMs / 100), PGSQL_ADVISORY_LOCK_POLL_MIN_INTERVAL_MS),
+      PGSQL_ADVISORY_LOCK_POLL_MAX_INTERVAL_MS
+    )
+  }
+
   /**
    * Blocks until a PostgreSQL session-level advisory lock is acquired on
    * this connection. Implemented via `pg_advisory_lock(bigint)`, which has
    * no native timeout — the `timeoutMs` argument is emulated by racing a
-   * `pg_try_advisory_lock` poll loop so callers on MySQL and Postgres see
-   * the same contract.
+   * `pg_try_advisory_lock` poll loop so callers on MySQL and Postgres see the
+   * same contract. The poll interval backs off to a cap so a long bounded wait
+   * does not turn one contended lock into thousands of probe queries.
    * @param {string} name - Lock name.
-   * @param {{timeoutMs?: number | null}} [args] - Optional timeout in milliseconds; `null`, `undefined`, or negative blocks forever.
+   * @param {{timeoutMs?: number | null}} [args] - Optional timeout in milliseconds; `null` or negative blocks forever, and an omitted value uses the database's `advisoryLockAcquireTimeoutMs` or the framework default.
    * @returns {Promise<boolean>} - True if the lock was acquired, false if the timeout elapsed.
    */
   async _acquireAdvisoryLock(name, {timeoutMs} = {}) {
@@ -444,7 +467,7 @@ export default class VelociousDatabaseDriversPgsql extends Base{
     }
 
     const deadline = Date.now() + timeoutMs
-    const pollIntervalMs = 50
+    const pollIntervalMs = VelociousDatabaseDriversPgsql.advisoryLockPollIntervalMs(timeoutMs)
 
     while (true) {
       if (await this._tryAcquireAdvisoryLock(name)) return true

package/src/environment-handlers/base.js

@@ -518,6 +518,15 @@ export default class VelociousEnvironmentHandlerBase {
     throw new Error("cliCommandsConsole not implemented")
   }
 
+  /**
+   * Runs cli commands mcp.
+   * @param {import("../cli/base-command.js").default} _command - Command.
+   * @returns {Promise<void>} - Resolves when the command completes.
+   */
+  async cliCommandsMcp(_command) {
+    throw new Error("cliCommandsMcp not implemented")
+  }
+
   /**
    * Runs cli commands server.
    * @param {import("../cli/base-command.js").default} _command - Command.

package/src/environment-handlers/node/cli/commands/mcp.js

@@ -0,0 +1,87 @@
+// @ts-check
+
+import Application from "../../../../application.js"
+import BaseCommand from "../../../../cli/base-command.js"
+import {startMcpStdioServer} from "../../../../mcp/json-rpc-server.js"
+
+/**
+ * Parses `--request-context key=value` occurrences from raw process args and the
+ * `MCP_REQUEST_CONTEXT` environment variable (JSON object) into one context hash.
+ * @param {object} args - Arguments.
+ * @param {string[]} [args.processArgs] - Raw CLI process args.
+ * @returns {Record<string, string | number | boolean> | undefined} - Parsed request context, or undefined when none configured.
+ */
+export function parseMcpRequestContext({processArgs = []}) {
+  /** @type {Record<string, string | number | boolean>} */
+  const context = {}
+
+  const envValue = process.env.MCP_REQUEST_CONTEXT
+
+  if (envValue) {
+    const parsedEnv = /** @type {Record<string, unknown>} */ (JSON.parse(envValue))
+
+    for (const [key, value] of Object.entries(parsedEnv)) {
+      assignContextValue(context, key, value)
+    }
+  }
+
+  for (let i = 0; i < processArgs.length; i++) {
+    if (processArgs[i] !== "--request-context") continue
+
+    const pair = processArgs[i + 1]
+
+    if (typeof pair !== "string") throw new Error("--request-context requires a key=value pair")
+
+    const separatorIndex = pair.indexOf("=")
+
+    if (separatorIndex < 1) throw new Error(`--request-context pair '${pair}' must be key=value`)
+
+    assignContextValue(context, pair.slice(0, separatorIndex), pair.slice(separatorIndex + 1))
+    i++
+  }
+
+  return Object.keys(context).length > 0 ? context : undefined
+}
+
+/**
+ * Assigns one scalar context value, converting numeric strings to numbers.
+ * @param {Record<string, string | number | boolean>} context - Target context hash.
+ * @param {string} key - Context key.
+ * @param {unknown} value - Raw value.
+ * @returns {void} - No return value.
+ */
+function assignContextValue(context, key, value) {
+  if (typeof value === "number" || typeof value === "boolean") {
+    context[key] = value
+
+    return
+  }
+
+  if (typeof value !== "string") throw new Error(`Request context value for '${key}' must be a scalar`)
+
+  const asNumber = Number(value)
+
+  context[key] = value.length > 0 && Number.isFinite(asNumber) ? asNumber : value
+}
+
+export default class VelociousCliCommandsMcp extends BaseCommand{
+  /**
+   * Runs execute.
+   * @returns {Promise<void>} - Starts the MCP stdio server and waits until stdin closes.
+   */
+  async execute() {
+    // Identify this process in `ps`/`top` instead of a generic "node" entry.
+    process.title = "velocious mcp"
+
+    const configuration = this.getConfiguration()
+    const requestContext = parseMcpRequestContext({processArgs: this.processArgs})
+    const application = new Application({configuration, type: "mcp"})
+
+    await application.initialize()
+
+    const server = startMcpStdioServer({configuration, requestContext})
+
+    await server.done
+    await application.stop()
+  }
+}

package/src/environment-handlers/node.js

@@ -11,6 +11,7 @@ import CliCommandsGenerateFrontendModels from "./node/cli/commands/generate/fron
 import CliCommandsGenerateMigration from "./node/cli/commands/generate/migration.js"
 import CliCommandsGenerateModel from "./node/cli/commands/generate/model.js"
 import CliCommandsLintRelationships from "./node/cli/commands/lint/relationships.js"
+import CliCommandsMcp from "./node/cli/commands/mcp.js"
 import CliCommandsRoutes from "./node/cli/commands/routes.js"
 import CliCommandsServer from "./node/cli/commands/server.js"
 import CliCommandsTest from "./node/cli/commands/test.js"
@@ -859,6 +860,15 @@ export default class VelociousEnvironmentHandlerNode extends Base{
     return await this.forwardCommand(command, CliCommandsServer)
   }
 
+  /**
+   * Runs cli commands mcp.
+   * @param {import("../cli/base-command.js").default} command - Command.
+   * @returns {Promise<void>} - Resolves when the command completes.
+   */
+  async cliCommandsMcp(command) {
+    return await this.forwardCommand(command, CliCommandsMcp)
+  }
+
   /**
    * Runs cli commands test.
    * @param {import("../cli/base-command.js").default} command - Command.

package/src/mcp/dispatcher.js

@@ -0,0 +1,271 @@
+// @ts-check
+
+/**
+ * @typedef {object} McpToolResult
+ * @property {Array<{text: string, type: "text"}>} content - Tool result content blocks.
+ * @property {boolean} isError - Whether the tool call failed.
+ */
+
+/**
+ * @typedef {object} FrontendModelRequestEntry
+ * @property {string} [commandType] - Built-in command type.
+ * @property {string} [customPath] - Custom command path.
+ * @property {string} model - Backend model name.
+ * @property {Record<string, unknown>} payload - Command payload.
+ * @property {Record<string, string | number | boolean> | undefined} [requestContext] - Remote request context.
+ * @property {string} requestId - Request correlation id.
+ */
+
+/**
+ * @typedef {Record<string, unknown> & {formatVersion?: number, resources?: Record<string, unknown>}} ApiManifest
+ */
+
+/**
+ * @typedef {object} ManifestCommandEntry
+ * @property {Array<{name: string, type: string}>} [args] - Declared typed command arguments.
+ * @property {boolean} [isBuiltIn] - Whether the entry is a synthesized built-in command.
+ * @property {string} methodName - Command method name.
+ * @property {string} [path] - Manifest command path (member paths carry `<id>`).
+ * @property {string | null} [returnType] - Declared JSDoc return type.
+ * @property {"collection" | "member"} scope - Command scope.
+ */
+
+/**
+ * @typedef {object} ManifestResourceEntry
+ * @property {Record<string, ManifestCommandEntry[]>} [commands] - Scope-keyed custom command entries.
+ * @property {Record<string, Record<string, string>>} [builtInCommands] - Scope-keyed built-in command maps.
+ * @property {string} modelName - Backend model name.
+ * @property {string | string[]} [primaryKey] - Primary key attribute name(s).
+ */
+
+import FrontendModelController from "../frontend-model-controller.js"
+import Request from "../http-server/client/request.js"
+import Response from "../http-server/client/response.js"
+import {deserializeFrontendModelTransportValue, serializeFrontendModelTransportValue} from "../frontend-models/transport-serialization.js"
+import {generateMcpTools, metaToolName, parseMcpToolName} from "./manifest-tools.js"
+
+const MCP_REQUEST_PATH = "/frontend-models"
+
+/**
+ * Lists the MCP tools exposed by a configuration's frontend-model API manifest.
+ * @param {object} args - Arguments.
+ * @param {import("../configuration.js").default} args.configuration - Configuration instance.
+ * @returns {Promise<Record<string, unknown>[]>} - MCP `tools/list` tool definitions.
+ */
+export async function listMcpTools({configuration}) {
+  const manifest = /** @type {ApiManifest} */ (await configuration.getApiManifest())
+
+  return generateMcpTools(manifest)
+}
+
+/**
+ * Executes one MCP `tools/call` against the frontend-model dispatcher.
+ * The tool call is translated into the exact shared frontend-model request entry
+ * (`commandType`/`customPath`, `model`, `payload`, `requestContext`) and runs
+ * through `FrontendModelController.frontendApi()` in-process, so tenant and
+ * ability resolution stay inside the owning dispatcher — MCP never bypasses them.
+ * @param {object} args - Arguments.
+ * @param {import("../configuration.js").default} args.configuration - Configuration instance.
+ * @param {Record<string, string | number | boolean> | undefined} [args.requestContext] - Remote request context forwarded to the app's ability/tenant resolvers.
+ * @param {Record<string, unknown>} args.toolArguments - Tool arguments from the MCP client.
+ * @param {string} args.toolName - MCP tool name.
+ * @returns {Promise<McpToolResult>} - MCP tool call result.
+ */
+export async function callMcpTool({configuration, requestContext, toolArguments, toolName}) {
+  const manifest = /** @type {ApiManifest} */ (await configuration.getApiManifest())
+
+  if (toolName === metaToolName()) {
+    return textResult({value: manifest})
+  }
+
+  const identity = parseMcpToolName({manifest, toolName})
+
+  if (!identity) return errorResult(`Unknown MCP tool '${toolName}'.`)
+
+  const manifestResources = /** @type {Record<string, unknown>} */ (manifest.resources || {})
+  const resource = /** @type {ManifestResourceEntry} */ (manifestResources[identity.modelKey])
+  const commandEntry = findManifestCommandEntry({commandName: identity.commandName, resource, scope: identity.scope})
+
+  if (!commandEntry) return errorResult(`Manifest command entry missing for tool '${toolName}'.`)
+
+  const requestEntry = buildFrontendModelRequestEntry({commandEntry, model: String(resource.modelName), requestContext, toolArguments})
+  const responsePayload = await runFrontendApiRequest({configuration, requestEntry})
+  const responseEntry = Array.isArray(responsePayload?.responses) ? responsePayload.responses[0] : undefined
+  const commandResponse = responseEntry?.response
+
+  if (!commandResponse) return errorResult("Frontend-model dispatcher returned no response.")
+
+  if (commandResponse.status === "error") {
+    return errorResult(commandResponse.errorMessage || "Frontend-model command failed.", commandResponse)
+  }
+
+  return textResult({value: commandResponse})
+}
+
+/**
+ * Finds the manifest command entry matching a parsed tool identity.
+ * @param {object} args - Arguments.
+ * @param {string} args.commandName - Command method name.
+ * @param {ManifestResourceEntry} args.resource - Manifest resource entry.
+ * @param {"collection" | "member"} args.scope - Command scope.
+ * @returns {ManifestCommandEntry | undefined} - Manifest command entry.
+ */
+function findManifestCommandEntry({commandName, resource, scope}) {
+  if (resource.builtInCommands?.[scope]?.[commandName]) {
+    return {isBuiltIn: true, methodName: commandName, scope}
+  }
+
+  const scopeCommands = resource.commands?.[scope]
+
+  if (!Array.isArray(scopeCommands)) return undefined
+
+  return scopeCommands.find((entry) => entry.methodName === commandName)
+}
+
+/**
+ * Builds the shared frontend-model request entry for one tool call.
+ * @param {object} args - Arguments.
+ * @param {ManifestCommandEntry} args.commandEntry - Manifest command entry.
+ * @param {string} args.model - Backend model name.
+ * @param {Record<string, string | number | boolean> | undefined} args.requestContext - Remote request context.
+ * @param {Record<string, unknown>} args.toolArguments - Tool arguments.
+ * @returns {FrontendModelRequestEntry} - frontendApi request entry.
+ */
+function buildFrontendModelRequestEntry({commandEntry, model, requestContext, toolArguments}) {
+  const isBuiltInCommand = ["attach", "attachmentList", "create", "destroy", "download", "find", "index", "update", "url"].includes(commandEntry.methodName)
+
+  if (isBuiltInCommand) {
+    return {
+      commandType: commandEntry.methodName,
+      model,
+      payload: toolArguments,
+      requestId: "mcp-1",
+      requestContext
+    }
+  }
+
+  return {
+    customPath: resolveCustomCommandPath({commandEntry, toolArguments}),
+    model,
+    payload: toolArguments,
+    requestId: "mcp-1",
+    requestContext
+  }
+}
+
+/**
+ * Substitutes the `<id>` placeholder of a manifest command path with the tool's
+ * primary key argument, matching the member route the dispatcher resolves.
+ * @param {object} args - Arguments.
+ * @param {ManifestCommandEntry} args.commandEntry - Manifest command entry (carries `path` and `scope`).
+ * @param {Record<string, unknown>} args.toolArguments - Tool arguments.
+ * @returns {string} - Custom command path.
+ */
+function resolveCustomCommandPath({commandEntry, toolArguments}) {
+  const path = String(commandEntry.path || "")
+
+  if (!path.includes("<id>")) return path
+
+  const idValue = toolArguments.id ?? toolArguments.recordId
+
+  return path.replace("<id>", encodeURIComponent(String(idValue ?? "")))
+}
+
+/**
+ * Builds the synthetic HTTP request lines for one MCP dispatch. The request-context
+ * `authorization` key is forwarded as the request's `Authorization` header so apps
+ * whose ability resolver authenticates from headers (Bearer service tokens or
+ * personal access tokens) authenticate MCP tool calls exactly like HTTP calls.
+ * Carriage returns and line feeds are stripped so a context value can never inject
+ * extra request lines.
+ * @param {object} args - Arguments.
+ * @param {Record<string, string | number | boolean> | undefined} args.requestContext - Remote request context.
+ * @returns {string} - Raw HTTP request head.
+ */
+export function buildSyntheticRequestLines({requestContext}) {
+  const lines = [
+    `POST ${MCP_REQUEST_PATH} HTTP/1.1`,
+    "Host: velocious-mcp",
+    "Content-Length: 0",
+  ]
+
+  if (requestContext && typeof requestContext.authorization === "string") {
+    const authorization = requestContext.authorization.replace(/[\r\n]/g, "").trim()
+
+    if (authorization.length > 0) lines.push(`Authorization: ${authorization}`)
+  }
+
+  lines.push("", "")
+
+  return lines.join("\r\n")
+}
+
+/**
+ * Runs one frontend-model request entry through the controller in-process,
+ * mirroring the synthetic-request pattern used by the controller specs.
+ * @param {object} args - Arguments.
+ * @param {import("../configuration.js").default} args.configuration - Configuration instance.
+ * @param {FrontendModelRequestEntry} args.requestEntry - frontendApi request entry.
+ * @returns {Promise<Record<string, ReturnType<typeof JSON.parse>>>} - Parsed frontendApi response payload.
+ */
+async function runFrontendApiRequest({configuration, requestEntry}) {
+  const client = /** @type {import("../http-server/client/index.js").default} */ ({remoteAddress: "127.0.0.1"})
+  const request = new Request({client, configuration})
+  const donePromise = new Promise((resolve) => request.requestParser.events.on("done", resolve))
+
+  request.feed(Buffer.from(buildSyntheticRequestLines({requestContext: requestEntry.requestContext}), "utf8"))
+
+  await donePromise
+
+  const response = new Response({configuration})
+  const controller = new FrontendModelController({
+    action: "frontendApi",
+    configuration,
+    controller: "frontend-models",
+    params: {requests: [requestEntry]},
+    request,
+    response,
+    viewPath: `${configuration.getDirectory()}/src/routes/frontend-models`
+  })
+
+  await controller.frontendApi()
+
+  const body = response.getBody()
+  const responseText = body === null || body === undefined
+    ? ""
+    : (typeof body === "string" ? body : Buffer.from(body).toString("utf8"))
+  const responseJson = responseText.length > 0 ? JSON.parse(responseText) : {}
+
+  return /** @type {Record<string, ReturnType<typeof JSON.parse>>} */ (deserializeFrontendModelTransportValue(responseJson))
+}
+
+/**
+ * Wraps a value as an MCP text content result.
+ * @param {object} args - Arguments.
+ * @param {unknown} args.value - Value to serialize as JSON text.
+ * @returns {McpToolResult} - MCP tool result.
+ */
+function textResult({value}) {
+  const serialized = serializeFrontendModelTransportValue(value)
+
+  return {
+    content: [{text: JSON.stringify(serialized, null, 2), type: "text"}],
+    isError: false
+  }
+}
+
+/**
+ * Builds an MCP error result, optionally including the dispatcher's error
+ * payload (validation summaries stay faithful — nothing is swallowed).
+ * @param {string} message - Error message.
+ * @param {Record<string, unknown>} [payload] - Full dispatcher error payload.
+ * @returns {McpToolResult} - MCP tool result.
+ */
+function errorResult(message, payload) {
+  const detail = payload ? `\n${JSON.stringify(payload, null, 2)}` : ""
+
+  return {
+    content: [{text: `${message}${detail}`, type: "text"}],
+    isError: true
+  }
+}