velocious 1.0.691 → 1.0.693

package/src/background-jobs/store.js

@@ -116,6 +116,17 @@ const SCHEDULE_KEYS_TABLE = "background_job_schedule_keys"
 const SCHEDULE_ORDER_WATERMARKS_TABLE = "background_job_schedule_order_watermarks"
 const SCHEDULE_ORDER_WATERMARK_MIGRATION_VERSION = "20260911120000"
 const SCHEDULE_HISTORY_ORDER_INDEX = "index_background_jobs_schedule_history_order"
+// Composite retention indexes bound the terminal-status discovery scan to the expired
+// (status, terminal_timestamp) range, so retention candidate pages stay cheap on
+// multi-million-row tables. Activation was staged separately from the lock-scope fix
+// because MariaDB online index DDL makes concurrent metadata inspection fail with
+// ER_WARN_I_S_SKIPPED_TABLE; the driver now outlasts that skip with a bounded retry.
+const RETENTION_INDEX_MIGRATION_VERSION = "20261012120000"
+const RETENTION_INDEX_DEFINITIONS = [
+  {columns: ["status", "completed_at_ms", "id"], name: "index_background_jobs_completed_retention"},
+  {columns: ["status", "failed_at_ms", "id"], name: "index_background_jobs_failed_retention"},
+  {columns: ["status", "orphaned_at_ms", "id"], name: "index_background_jobs_orphaned_retention"}
+]
 const CONCURRENCY_TABLE = "background_job_concurrency"
 const COUNTS_REVISION_TABLE = "background_job_count_revisions"
 const COUNTS_REVISION_KEY = "counts"
@@ -2155,6 +2166,7 @@ export default class BackgroundJobsStore extends BackgroundJobsAdapter {
       await this._ensureScheduleKeysTable(db)
       await this._ensureConcurrencyTable(db)
       await this._ensureCountRevisionTable(db)
+      await this._ensureRetentionIndexesOnce(db)
 
       return
     }
@@ -2360,6 +2372,7 @@ export default class BackgroundJobsStore extends BackgroundJobsAdapter {
     await this._ensureJobTimeoutColumn(db)
     await this._ensureChildAcceptanceColumns(db)
     await this._ensureJobsTableIndexesOnce(db)
+    await this._ensureRetentionIndexesOnce(db)
   }
 
   /**
@@ -2451,6 +2464,54 @@ export default class BackgroundJobsStore extends BackgroundJobsAdapter {
     }
   }
 
+  /**
+   * Idempotently creates the ordered composite retention indexes. An index
+   * with the expected name but a different column order is a manual-repair
+   * situation and fails readiness loudly instead of being rebuilt or
+   * re-recorded; the migration ledger is written only once every expected
+   * index exists with its exact ordered columns.
+   * @param {import("../database/drivers/base.js").default} db - Database connection.
+   * @returns {Promise<void>} - Resolves when all retention indexes exist.
+   */
+  async _ensureRetentionIndexesOnce(db) {
+    const migrationVersion = RETENTION_INDEX_MIGRATION_VERSION
+    const migrationKey = this._migrationKey(migrationVersion)
+
+    if (await this._hasMigration(db, migrationVersion)) return
+
+    const acquired = await db.acquireAdvisoryLock(migrationKey)
+
+    if (!acquired) throw new Error("Failed to acquire background jobs retention index lock")
+
+    try {
+      if (await this._hasMigration(db, migrationVersion)) return
+
+      db.clearSchemaCache()
+      const table = await db.getTableByNameOrFail(JOBS_TABLE)
+      const existingIndexColumns = new Map(
+        (await table.getIndexes()).map((index) => [index.getName(), index.getColumnNames()])
+      )
+
+      for (const {columns, name} of RETENTION_INDEX_DEFINITIONS) {
+        const existingColumns = existingIndexColumns.get(name)
+
+        if (existingColumns) {
+          if (existingColumns.join(",") === columns.join(",")) continue
+          throw new Error(`Background jobs retention index ${name} exists with unexpected columns: ${existingColumns.join(",")}`)
+        }
+
+        for (const sql of await db.createIndexSQLs({columns, ifNotExists: db.getType() === "sqlite", name, tableName: JOBS_TABLE})) {
+          await db.query(sql)
+        }
+      }
+
+      db.clearSchemaCache()
+      await this._recordMigration(db, migrationVersion)
+    } finally {
+      await db.releaseAdvisoryLock(migrationKey)
+    }
+  }
+
   /**
    * Idempotently adds the per-job wall-clock timeout to existing job tables.
    * @param {import("../database/drivers/base.js").default} db - Database connection.

package/src/cli/commands/mcp.js

@@ -0,0 +1,7 @@
+import BaseCommand from "../base-command.js"
+
+export default class VelociousCliCommandsMcp extends BaseCommand{
+  async execute() {
+    return await this.getConfiguration().getEnvironmentHandler().cliCommandsMcp(this)
+  }
+}

package/src/cli/index.js

@@ -1,6 +1,6 @@
 // @ts-check
 
-const COMMAND_VALUE_OPTIONS = new Set(["--generation", "--initial-generation-state", "--lifecycle-socket", "--phase", "--socket", "--tenant"])
+const COMMAND_VALUE_OPTIONS = new Set(["--generation", "--initial-generation-state", "--lifecycle-socket", "--phase", "--request-context", "--socket", "--tenant"])
 
 export default class VelociousCli {
   /**

package/src/configuration-types.js

@@ -68,6 +68,7 @@
 
 /**
  * @typedef {object} DatabaseConfigurationType
+ * @property {number | null} [advisoryLockAcquireTimeoutMs] - Bound (ms) a blocking advisory-lock acquisition waits for a contended lock before reporting failure. Default: `900000` (15 minutes). `null` opts out and restores the driver's indefinite wait. A per-call `timeoutMs` argument always overrides this.
  * @property {string} [databaseCharset] - Default character set applied by `db:create` via mysql/mariadb `CREATE DATABASE ... CHARACTER SET`. Distinct from `charset`, which is the client connection charset forwarded to the mysql2 driver.
  * @property {string} [databaseCollation] - Default collation applied by `db:create` via mysql/mariadb `CREATE DATABASE ... COLLATE`.
  * @property {string} [database] - Database name for this connection.
@@ -93,6 +94,7 @@
  * @property {boolean} [readOnly] - Whether writes should be blocked for this database.
  * @property {string} [schema] - Default schema for unqualified table lookups (MSSQL).
  * @property {boolean} [schemaCache] - Whether schema metadata should be cached on the driver. Defaults to true.
+ * @property {number} [schemaMetadataRetryDeadlineMs] - Bounded deadline (ms) for outlasting a cached schema-metadata read the server skipped because concurrent online DDL is modifying the table. Defaults to 60000.
  * @property {object} [record] - Record-level configuration.
  * @property {boolean} [record.transactions] - Whether record operations should use transactions.
  * @property {boolean} [reset] - Whether to reset the database on startup.
@@ -221,6 +223,7 @@
  *   Priorities may be any number, including negative to sink a queue below the
  *   default. Jobs within the same priority keep FIFO (`scheduled_at`, then
  *   `created_at`) order. Default: `{}` (no queue caps, all queues priority `0`).
+ * @property {number | null} [scheduledEnqueueTimeoutMs] - Bounds one scheduled enqueue attempt in the main process. A durable enqueue that never settles (wedged DB connection, contended advisory lock) would otherwise keep its schedule key permanently in flight, so every later tick skipped itself and shutdown could never drain. On timeout the attempt is reported as `background-jobs-scheduled-enqueue-stall` and the key clears for the next tick. Default: 20 minutes — deliberately 5 minutes above `advisoryLockAcquireTimeoutMs` so the precise lock error surfaces first. `null` opts out.
  * @property {BackgroundJobsDispatchStrategy} [dispatchStrategy] - How the main process
  *   detects new work. Defaults to `"beacon"` (event-driven). Set to `"polling"`
  *   to restore the legacy fixed-interval poll.

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"
@@ -1707,6 +1708,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 +1747,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"
@@ -183,6 +184,12 @@ const SCHEMA_INVALIDATION_SCAN_LIMIT = 8192
 /** Maximum checkout-name characters inspected by retry diagnostics. */
 const OPERATION_NAME_SCAN_LIMIT = 1024
 const REDACTED_DIAGNOSTIC_LABEL = "[REDACTED]"
+/** First backoff between retries of a schema-metadata read blocked by concurrent online DDL. */
+const SCHEMA_METADATA_RETRY_INITIAL_DELAY_MS = 250
+/** Largest backoff between retries of a schema-metadata read blocked by concurrent online DDL. */
+const SCHEMA_METADATA_RETRY_MAX_DELAY_MS = 2000
+/** Default bounded deadline for outlasting a concurrent online-DDL metadata skip. */
+const SCHEMA_METADATA_RETRY_DEADLINE_MS = 60000
 
 /**
  * Builds a non-reversible, stable SQL fingerprint without retaining SQL text. Literal spelling is
@@ -777,6 +784,52 @@ export default class VelociousDatabaseDriversBase {
     return this.getArgs().schemaCache !== false
   }
 
+  /**
+   * Runs schema metadata retry deadline ms.
+   * @returns {number} - Bounded deadline for outlasting transient schema-metadata contention.
+   */
+  _schemaMetadataRetryDeadlineMs() {
+    const configured = this.getArgs().schemaMetadataRetryDeadlineMs
+
+    return typeof configured === "number" ? configured : SCHEMA_METADATA_RETRY_DEADLINE_MS
+  }
+
+  /**
+   * Whether an error raised by a schema-metadata read is transient contention that a bounded
+   * retry can outlast. Drivers override this for their own contention signatures; the default
+   * treats every failure as final so only drivers that prove the transient shape retry it.
+   * @param {unknown} _error - Error raised by a schema-metadata read.
+   * @returns {boolean} - Whether the read may be retried.
+   */
+  _isTransientSchemaMetadataError(_error) {
+    return false
+  }
+
+  /**
+   * Runs a schema-metadata read, retrying transient concurrent-DDL contention until the bounded
+   * deadline. Non-transient failures and exhausted deadlines propagate the original error.
+   * @template T
+   * @param {() => Promise<T>} callback - Cache-miss schema read.
+   * @returns {Promise<T>} - Resolves with the read result.
+   */
+  async _withSchemaMetadataDdlRetry(callback) {
+    const deadlineMs = this._schemaMetadataRetryDeadlineMs()
+    const startedAt = Date.now()
+    let delayMs = SCHEMA_METADATA_RETRY_INITIAL_DELAY_MS
+
+    for (;;) {
+      try {
+        return await callback()
+      } catch (error) {
+        if (!this._isTransientSchemaMetadataError(error)) throw error
+        if (Date.now() - startedAt + delayMs > deadlineMs) throw error
+
+        await wait(delayMs)
+        delayMs = Math.min(delayMs * 2, SCHEMA_METADATA_RETRY_MAX_DELAY_MS)
+      }
+    }
+  }
+
   /**
    * Runs cached schema metadata.
    * @template T
@@ -785,7 +838,7 @@ export default class VelociousDatabaseDriversBase {
    * @returns {Promise<T>} - Resolves with the cached metadata.
    */
   async _cachedSchemaMetadata(cacheKey, callback) {
-    if (!this._schemaCacheEnabled()) return await callback()
+    if (!this._schemaCacheEnabled()) return await this._withSchemaMetadataDdlRetry(callback)
 
     const existingPromise = this._schemaCache.get(cacheKey)
 
@@ -793,7 +846,7 @@ export default class VelociousDatabaseDriversBase {
       return /** @type {T} */ (this._schemaCacheReturnValue(await existingPromise))
     }
 
-    const promise = (async () => await callback())()
+    const promise = (async () => await this._withSchemaMetadataDdlRetry(callback))()
 
     this._schemaCache.set(cacheKey, promise)
 
@@ -2876,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/mysql/index.js

@@ -723,6 +723,29 @@ export default class VelociousDatabaseDriversMysql extends Base{
     return insert.toSql()
   }
 
+  /**
+   * MariaDB skips information-schema/SHOW reads for a table whose definition is being modified
+   * by concurrent online DDL (ER_WARN_I_S_SKIPPED_TABLE). The build completes in seconds, so the
+   * skip is transient contention that the bounded schema-metadata retry can outlast. Query
+   * helpers wrap the driver error, so the code is searched through the cause chain.
+   * @param {unknown} error - Error raised by a schema-metadata read.
+   * @returns {boolean} - Whether the read hit concurrent-DDL metadata contention.
+   */
+  _isTransientSchemaMetadataError(error) {
+    let currentError = /** @type {{code?: string, cause?: unknown} | undefined} */ (
+      /** @type {unknown} */ (error)
+    )
+
+    for (let depth = 0; depth < 5 && currentError; depth++) {
+      if (currentError.code === "ER_WARN_I_S_SKIPPED_TABLE") return true
+      currentError = /** @type {{code?: string, cause?: unknown} | undefined} */ (
+        /** @type {unknown} */ (currentError.cause)
+      )
+    }
+
+    return false
+  }
+
   /**
    * Runs get tables.
    * @returns {Promise<Array<import("../base-table.js").default>>} - Resolves with the tables.

package/src/database/drivers/mysql/query.js

@@ -171,7 +171,7 @@ export default async function query(pool, sql, {signal} = {}) {
           connection.release()
         }
 
-        reject(new Error(`Query failed because of ${error}: ${sql}`))
+        reject(new Error(`Query failed because of ${error}: ${sql}`, {cause: error}))
 
         return
       }

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.