velocious 1.0.692 → 1.0.693

package/src/mcp/json-rpc-server.js

@@ -0,0 +1,167 @@
+// @ts-check
+
+/**
+ * @typedef {Record<string, unknown> & {error?: {code: number, message: string}, id?: number | string | null, jsonrpc: string, method?: string, params?: Record<string, unknown>, result?: Record<string, unknown>}} JsonRpcMessage
+ */
+
+import readline from "node:readline"
+import {callMcpTool, listMcpTools} from "./dispatcher.js"
+
+const MCP_PROTOCOL_VERSION = "2025-03-26"
+
+/**
+ * Handles one JSON-RPC message of the MCP protocol (initialize / tools/list /
+ * tools/call / ping) against a Velocious configuration. Returns null for
+ * notifications (no response expected).
+ * @param {object} args - Arguments.
+ * @param {import("../configuration.js").default} args.configuration - Configuration instance.
+ * @param {JsonRpcMessage} args.request - Parsed JSON-RPC request.
+ * @param {Record<string, string | number | boolean> | undefined} [args.requestContext] - Remote request context forwarded to every tool call.
+ * @returns {Promise<JsonRpcMessage | null>} - JSON-RPC response, or null for notifications.
+ */
+export async function handleMcpRequest({configuration, request, requestContext}) {
+  if (!request || typeof request !== "object" || request.jsonrpc !== "2.0" || typeof request.method !== "string") {
+    return jsonRpcError(null, -32600, "Invalid Request")
+  }
+
+  const id = request.id
+
+  if (request.method.startsWith("notifications/")) return null
+
+  if (request.method === "initialize") {
+    return jsonRpcResult(id, {
+      capabilities: {tools: {listChanged: false}},
+      protocolVersion: MCP_PROTOCOL_VERSION,
+      serverInfo: {name: "velocious-mcp", title: "Velocious frontend-model MCP server", version: "1.0.0"}
+    })
+  }
+
+  if (request.method === "ping") return jsonRpcResult(id, {})
+
+  if (request.method === "tools/list") {
+    return jsonRpcResult(id, {tools: await listMcpTools({configuration})})
+  }
+
+  if (request.method === "tools/call") {
+    const params = request.params || {}
+
+    if (typeof params.name !== "string") return jsonRpcError(id, -32602, "Expected tools/call params.name")
+
+    const toolArguments = params.arguments && typeof params.arguments === "object" && !Array.isArray(params.arguments)
+      ? /** @type {Record<string, unknown>} */ (params.arguments)
+      : {}
+
+    return jsonRpcResult(id, await callMcpTool({configuration, requestContext, toolArguments, toolName: params.name}))
+  }
+
+  return jsonRpcError(id, -32601, `Method not found: ${request.method}`)
+}
+
+/**
+ * Starts a line-delimited JSON-RPC MCP server over stdio (the primary MCP
+ * transport for local tool servers). Each input line is one JSON-RPC message;
+ * each response is written as one JSON line.
+ * @param {object} args - Arguments.
+ * @param {import("../configuration.js").default} args.configuration - Configuration instance.
+ * @param {import("node:stream").Readable} [args.input] - Input stream (defaults to stdin).
+ * @param {import("node:stream").Writable} [args.output] - Output stream (defaults to stdout).
+ * @param {Record<string, string | number | boolean> | undefined} [args.requestContext] - Remote request context forwarded to every tool call.
+ * @returns {{close: () => void, done: Promise<void>}} - Server handle; `done` resolves when the input stream closes.
+ */
+export function startMcpStdioServer({configuration, input = process.stdin, output = process.stdout, requestContext}) {
+  let closed = false
+  let doneResolved = false
+  /** @type {((value: void) => void) | undefined} */
+  let resolveDone
+
+  const done = new Promise((resolve) => { resolveDone = resolve })
+
+  /**
+   * Writes one JSON-RPC message as a line.
+   * @param {JsonRpcMessage | null} message - Message to write.
+   * @returns {void} - No return value.
+   */
+  const writeMessage = (message) => {
+    // Responses for in-flight requests are still written after the input
+    // stream closed; only after `done` resolved are writes suppressed.
+    if (message === null || doneResolved) return
+
+    output.write(`${JSON.stringify(message)}\n`)
+  }
+
+  const readlineInterface = readline.createInterface({input})
+
+  let pendingRequests = 0
+
+  const finishIfClosed = () => {
+    if (closed && pendingRequests === 0 && resolveDone && !doneResolved) {
+      doneResolved = true
+      resolveDone(undefined)
+    }
+  }
+
+  readlineInterface.on("line", (/** @type {string} */ line) => {
+    const trimmed = line.trim()
+
+    if (trimmed.length === 0) return
+
+    /** @type {JsonRpcMessage} */
+    let request
+
+    try {
+      request = JSON.parse(trimmed)
+    } catch {
+      writeMessage(jsonRpcError(null, -32700, "Parse error"))
+
+      return
+    }
+
+    pendingRequests++
+
+    handleMcpRequest({configuration, request, requestContext}).then((response) => {
+      writeMessage(response)
+    }).catch((error) => {
+      writeMessage(jsonRpcError(request.id ?? null, -32603, `Internal error: ${error instanceof Error ? error.message : String(error)}`))
+    }).finally(() => {
+      pendingRequests--
+      finishIfClosed()
+    })
+  })
+
+  readlineInterface.on("close", () => {
+    closed = true
+    finishIfClosed()
+  })
+
+  return {
+    close() {
+      if (closed) return
+
+      closed = true
+      readlineInterface.close()
+      finishIfClosed()
+    },
+    done
+  }
+}
+
+/**
+ * Builds a JSON-RPC success response.
+ * @param {number | string | null | undefined} id - Request id.
+ * @param {Record<string, unknown>} result - Result payload.
+ * @returns {JsonRpcMessage} - JSON-RPC response.
+ */
+function jsonRpcResult(id, result) {
+  return {id, jsonrpc: "2.0", result}
+}
+
+/**
+ * Builds a JSON-RPC error response.
+ * @param {number | string | null | undefined} id - Request id.
+ * @param {number} code - JSON-RPC error code.
+ * @param {string} message - Error message.
+ * @returns {JsonRpcMessage} - JSON-RPC response.
+ */
+function jsonRpcError(id, code, message) {
+  return {error: {code, message}, id, jsonrpc: "2.0"}
+}

package/src/mcp/manifest-tools.js

@@ -0,0 +1,310 @@
+// @ts-check
+
+/**
+ * @typedef {object} ManifestCommandEntry
+ * @property {Array<{name: string, type: string}>} [args] - Declared typed command arguments.
+ * @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 (methodName → slug).
+ * @property {string} modelName - Backend model name.
+ * @property {string | string[]} [primaryKey] - Primary key attribute name(s).
+ */
+
+/**
+ * @typedef {Record<string, unknown> & {formatVersion?: number, resources?: Record<string, unknown>}} ApiManifest
+ */
+
+import inflection from "inflection"
+
+const MCP_TOOL_NAME_PATTERN = /^[a-z0-9_]+$/
+
+/** @type {Record<string, string>} */
+const BUILT_IN_COMMAND_DESCRIPTIONS = {
+  attach: "Attach a file attachment to one record.",
+  attachmentList: "List the attachments of one record.",
+  create: "Create one record with `attributes` (and optional `nestedAttributes`).",
+  destroy: "Destroy one record by primary key `id`.",
+  download: "Download one attachment of one record.",
+  find: "Find one record by primary key `id`.",
+  index: "List records with optional `where`, `searches`, `sort`, `limit`, `offset`, `page`, `perPage`, `preload`, `select`, `count`, `pluck`, `distinct`, `group`, `joins`, and `queryData`.",
+  update: "Update one record by primary key `id` with `attributes` (and optional `nestedAttributes`).",
+  url: "Resolve the download URL of one attachment of one record."
+}
+
+const META_TOOL_NAME = "frontend_model_api_manifest"
+const META_TOOL_DESCRIPTION = "Return the full frontend-model API manifest (all resources, attributes, abilities, and commands) so callers can discover the available model commands."
+
+/**
+ * Maps one JSDoc type string from command metadata to a JSON Schema fragment.
+ * @param {string} type - JSDoc type string (for example `string`, `number`, `{id: number}`).
+ * @returns {{items?: {type: string}, type: string}} - JSON Schema type fragment.
+ */
+function jsonSchemaTypeForJSDocType(type) {
+  const normalizedType = type.trim()
+
+  if (normalizedType === "number" || normalizedType === "integer") return {type: "number"}
+  if (normalizedType === "boolean") return {type: "boolean"}
+  if (normalizedType.startsWith("Array<") || normalizedType.endsWith("[]")) return {items: {type: "string"}, type: "array"}
+
+  return {type: "string"}
+}
+
+/**
+ * Builds the MCP tool name for one model command.
+ * @param {object} args - Arguments.
+ * @param {string} args.modelKey - Manifest resource key (configured model name).
+ * @param {string} args.commandName - Command method name.
+ * @param {"collection" | "member"} args.scope - Command scope.
+ * @returns {string} - MCP tool name.
+ */
+function mcpToolName({commandName, modelKey, scope}) {
+  const modelPart = inflection.underscore(modelKey).toLowerCase()
+  const commandPart = inflection.underscore(commandName).toLowerCase()
+  const scopePart = scope === "member" ? "_by_id" : ""
+
+  return `${modelPart}_${commandPart}${scopePart}`
+}
+
+/**
+ * Builds the primary key input properties for one manifest resource.
+ * @param {string | string[] | undefined} primaryKey - Resource primary key attribute name(s).
+ * @returns {Record<string, {description: string, type: string}>} - Primary key JSON Schema properties.
+ */
+function primaryKeyProperties(primaryKey) {
+  const keyAttributes = Array.isArray(primaryKey) ? primaryKey : [primaryKey || "id"]
+  /** @type {Record<string, {description: string, type: string}>} */
+  const properties = {}
+
+  for (const keyAttribute of keyAttributes) {
+    properties[keyAttribute] = {description: `Primary key attribute \`${keyAttribute}\` of the record.`, type: "string"}
+  }
+
+  return properties
+}
+
+/**
+ * Builds the fixed input schema for one built-in command.
+ * @param {object} args - Arguments.
+ * @param {string} args.commandName - Built-in command name.
+ * @param {string | string[] | undefined} args.primaryKey - Resource primary key attribute name(s).
+ * @returns {Record<string, unknown>} - JSON Schema object for the tool input.
+ */
+function builtInCommandInputSchema({commandName, primaryKey}) {
+  if (commandName === "index") {
+    return {
+      additionalProperties: false,
+      properties: {
+        count: {description: "Return only the count of matching records.", type: "boolean"},
+        distinct: {description: "Apply DISTINCT to the index query.", type: "boolean"},
+        group: {description: "Group the index query by attribute names or relationship-path descriptors.", type: "object"},
+        joins: {description: "Relationship-path join descriptors.", type: "object"},
+        limit: {description: "Maximum number of records to return.", type: "number"},
+        offset: {description: "Number of records to skip.", type: "number"},
+        page: {description: "1-based page number (combine with `perPage`).", type: "number"},
+        perPage: {description: "Records per page.", type: "number"},
+        pluck: {description: "Attribute names or relationship-path descriptors to pluck instead of full records.", type: "array"},
+        preload: {description: "Relationship preload descriptors.", type: "object"},
+        queryData: {description: "Structured query-data descriptor.", type: "object"},
+        searches: {description: "Search descriptors (path/column/operator/value).", type: "array"},
+        select: {description: "Selected attribute names per model.", type: "object"},
+        selectsExtra: {description: "Extra selected attributes.", type: "object"},
+        sort: {description: "Sort definitions (column or relationship-path descriptors).", type: "array"},
+        where: {description: "Attribute filter hash.", type: "object"},
+        withCount: {description: "Include the total count alongside records.", type: "boolean"}
+      },
+      type: "object"
+    }
+  }
+
+  if (commandName === "create") {
+    return {
+      additionalProperties: false,
+      properties: {
+        attributes: {description: "Writable attribute values for the new record.", type: "object"},
+        nestedAttributes: {description: "Nested relationship attribute payloads.", type: "object"}
+      },
+      required: ["attributes"],
+      type: "object"
+    }
+  }
+
+  if (commandName === "update") {
+    const idProperties = primaryKeyProperties(primaryKey)
+
+    return {
+      additionalProperties: false,
+      properties: {
+        attributes: {description: "Writable attribute values to apply.", type: "object"},
+        ...idProperties,
+        nestedAttributes: {description: "Nested relationship attribute payloads.", type: "object"}
+      },
+      required: [...Object.keys(idProperties), "attributes"],
+      type: "object"
+    }
+  }
+
+  // find / destroy / attach / download / url / attachmentList are id-addressed
+  const idProperties = primaryKeyProperties(primaryKey)
+
+  return {
+    additionalProperties: false,
+    properties: {...idProperties},
+    required: [...Object.keys(idProperties)],
+    type: "object"
+  }
+}
+
+/**
+ * Builds the input schema for one custom command from its manifest argument metadata.
+ * @param {object} args - Arguments.
+ * @param {ManifestCommandEntry} args.entry - Manifest command entry.
+ * @param {string | string[] | undefined} args.primaryKey - Resource primary key attribute name(s).
+ * @returns {Record<string, unknown>} - JSON Schema object for the tool input.
+ */
+function customCommandInputSchema({entry, primaryKey}) {
+  const commandArgs = entry.args || []
+  /** @type {Record<string, {description?: string, items?: {items?: {type: string}, type: string}, type: string}>} */
+  const properties = {}
+
+  for (const commandArg of commandArgs) {
+    properties[commandArg.name] = jsonSchemaTypeForJSDocType(commandArg.type)
+  }
+
+  if (entry.scope === "member") {
+    for (const [keyAttribute, keySchema] of Object.entries(primaryKeyProperties(primaryKey))) {
+      if (!properties[keyAttribute]) properties[keyAttribute] = keySchema
+    }
+  }
+
+  return {
+    additionalProperties: true,
+    properties,
+    type: "object"
+  }
+}
+
+/**
+ * Generates MCP tool definitions from a frontend-model API manifest.
+ * Every built-in and custom command of every manifest resource becomes one tool;
+ * one meta tool exposes the raw manifest for discovery.
+ * @param {ApiManifest} manifest - Manifest from `configuration.getApiManifest()`.
+ * @returns {Record<string, unknown>[]} - MCP `tools/list` tool definitions.
+ */
+export function generateMcpTools(manifest) {
+  const resources = manifest.resources
+  const tools = []
+
+  if (!resources) return [buildMetaTool()]
+
+  for (const modelKey of Object.keys(resources).sort()) {
+    const resource = /** @type {ManifestResourceEntry} */ (resources[modelKey])
+    const commands = resource.commands || {}
+    const builtInCommands = resource.builtInCommands || {}
+
+    for (const scope of /** @type {Array<"collection" | "member">} */ (["collection", "member"])) {
+      for (const entry of scopeCommandEntries({builtInCommands, commands, scope})) {
+        const commandName = entry.methodName
+        const isBuiltIn = entry.isBuiltIn
+        const name = mcpToolName({commandName, modelKey, scope})
+
+        if (!MCP_TOOL_NAME_PATTERN.test(name)) continue
+
+        tools.push({
+          description: isBuiltIn
+            ? `${BUILT_IN_COMMAND_DESCRIPTIONS[commandName] || `Run the built-in \`${commandName}\` command on \`${resource.modelName}\`.`} Model: \`${resource.modelName}\`.`
+            : `Custom command \`${commandName}\` on model \`${resource.modelName}\`${entry.returnType ? ` (returns ${entry.returnType})` : ""}.`,
+          inputSchema: isBuiltIn
+            ? builtInCommandInputSchema({commandName, primaryKey: resource.primaryKey})
+            : customCommandInputSchema({entry, primaryKey: resource.primaryKey}),
+          name
+        })
+      }
+    }
+  }
+
+  tools.push(buildMetaTool())
+
+  return tools
+}
+
+/**
+ * Merges the manifest's built-in command names and custom command entries for
+ * one scope into a single deterministic command-entry list.
+ * @param {object} args - Arguments.
+ * @param {Record<string, Record<string, string>>} args.builtInCommands - Scope-keyed built-in command maps.
+ * @param {Record<string, ManifestCommandEntry[]>} args.commands - Scope-keyed custom command entries.
+ * @param {"collection" | "member"} args.scope - Command scope.
+ * @returns {Array<ManifestCommandEntry & {isBuiltIn: boolean}>} - Combined command entries.
+ */
+function scopeCommandEntries({builtInCommands, commands, scope}) {
+  /** @type {Array<ManifestCommandEntry & {isBuiltIn: boolean}>} */
+  const entries = []
+
+  for (const commandName of Object.keys(builtInCommands[scope] || {})) {
+    entries.push({isBuiltIn: true, methodName: commandName, scope})
+  }
+
+  for (const entry of commands[scope] || []) {
+    entries.push({...entry, isBuiltIn: false})
+  }
+
+  return entries.sort((a, b) => a.methodName.localeCompare(b.methodName))
+}
+
+/**
+ * Builds the manifest discovery meta tool.
+ * @returns {Record<string, unknown>} - MCP tool definition.
+ */
+function buildMetaTool() {
+  return {
+    description: META_TOOL_DESCRIPTION,
+    inputSchema: {additionalProperties: false, properties: {}, type: "object"},
+    name: META_TOOL_NAME
+  }
+}
+
+/**
+ * Parses one MCP tool name back into its manifest model key and command method name.
+ * @param {object} args - Arguments.
+ * @param {string} args.toolName - MCP tool name.
+ * @param {ApiManifest} args.manifest - Manifest from `configuration.getApiManifest()`.
+ * @returns {{commandName: string, modelKey: string, scope: "collection" | "member"} | null} - Command identity, or null when unknown.
+ */
+export function parseMcpToolName({manifest, toolName}) {
+  if (toolName === META_TOOL_NAME) return null
+
+  const resources = manifest.resources
+
+  if (!resources) return null
+
+  for (const modelKey of Object.keys(resources)) {
+    const resource = /** @type {ManifestResourceEntry} */ (resources[modelKey])
+    const commands = resource.commands || {}
+    const builtInCommands = resource.builtInCommands || {}
+
+    for (const scope of /** @type {Array<"collection" | "member">} */ (["collection", "member"])) {
+      const commandNames = [...Object.keys(builtInCommands[scope] || {}), ...(commands[scope] || []).map((entry) => entry.methodName)]
+
+      for (const commandName of commandNames) {
+        if (mcpToolName({commandName, modelKey, scope}) === toolName) {
+          return {commandName, modelKey, scope}
+        }
+      }
+    }
+  }
+
+  return null
+}
+
+/**
+ * Runs the metaToolName helper.
+ * @returns {string} - The meta tool name.
+ */
+export function metaToolName() { return META_TOOL_NAME }

package/src/routes/catch-all-route.js

@@ -0,0 +1,58 @@
+// @ts-check
+
+import restArgsError from "../utils/rest-args-error.js"
+
+/**
+ * Catch-all route options.
+ * @typedef {object} CatchAllRouteOptions
+ * @property {string} [controller] - Controller name unmatched requests resolve to.
+ * @property {string} [action] - Action name unmatched requests resolve to.
+ */
+
+/**
+ * Application-declared catch-all route created with `route.catchAll(...)` in
+ * the routes file. It is not a path matcher: the resolver applies it only
+ * when no other route in the tree matched, replacing the built-in errors
+ * not-found response with the application's own controller/action (for
+ * example a JSON error envelope) without hand-wiring a route resolver hook.
+ */
+export default class VelociousRouteCatchAllRoute {
+  /**
+   * Controller name unmatched requests resolve to.
+   * @type {string} */
+  controller
+
+  /**
+   * Action name unmatched requests resolve to.
+   * @type {string} */
+  action
+
+  /**
+   * Runs constructor.
+   * @param {CatchAllRouteOptions} [options] - Catch-all options.
+   */
+  constructor({controller = "_root", action = "notFound", ...restArgs} = {}) {
+    restArgsError(restArgs)
+
+    if (typeof controller !== "string" || controller.length < 1) {
+      throw new Error(`Expected catch-all 'controller' to be a non-empty string, got: ${String(controller)}`)
+    }
+
+    if (typeof action !== "string" || action.length < 1) {
+      throw new Error(`Expected catch-all 'action' to be a non-empty string, got: ${String(action)}`)
+    }
+
+    this.controller = controller
+    this.action = action
+  }
+
+  /**
+   * Runs get human paths.
+   * @returns {Array<{action: string | null, method: string, path: string}>} - Route definitions for this route.
+   */
+  getHumanPaths() {
+    return [
+      {method: "ANY", action: this.action, path: "*"}
+    ]
+  }
+}

package/src/routes/resolver.js

@@ -126,7 +126,10 @@ export default class VelociousRoutesResolver {
       const __filename = fileURLToPath(import.meta.url)
       const __dirname = dirname(__filename)
       const requestedPath = currentPath.replace(/^\//, "") || "_root"
-      const attemptedControllerPath = `${this.configuration.getDirectory()}/src/routes/${requestedPath}/controller.js`
+      const catchAllRoute = currentRoute?.catchAllRoute
+      const attemptedControllerPath = catchAllRoute
+        ? `${this.configuration.getDirectory()}/src/routes/${catchAllRoute.controller}/controller.js`
+        : `${this.configuration.getDirectory()}/src/routes/${requestedPath}/controller.js`
 
       const logger = this.logger
 
@@ -136,13 +139,23 @@ export default class VelociousRoutesResolver {
 
       await logger.warn(`No route matched for ${loggedPath}. Tried controller at ${attemptedControllerPath}`)
 
-      controller = "errors"
-      controllerPath = "./built-in/errors/controller.js"
-      action = "notFound"
-      skipAbilityResolution = true
-      skipControllerConnections = true
-      skipTenantResolution = true
-      viewPath = await fs.realpath(`${__dirname}/built-in/errors`)
+      if (catchAllRoute) {
+        controller = catchAllRoute.controller
+        action = normalizeActionName(catchAllRoute.action)
+        controllerPath = `${this.configuration.getDirectory()}/src/routes/${controller}/controller.js`
+        viewPath = `${this.configuration.getDirectory()}/src/routes/${controller}`
+        skipAbilityResolution = true
+        skipControllerConnections = true
+        skipTenantResolution = true
+      } else {
+        controller = "errors"
+        controllerPath = "./built-in/errors/controller.js"
+        action = "notFound"
+        skipAbilityResolution = true
+        skipControllerConnections = true
+        skipTenantResolution = true
+        viewPath = await fs.realpath(`${__dirname}/built-in/errors`)
+      }
     } else if (action) {
       if (!controller) controller = "_root"
 

package/src/routes/root-route.js

@@ -1,11 +1,36 @@
 // @ts-check
 
 import BasicRoute from "./basic-route.js"
+import CatchAllRoute from "./catch-all-route.js"
 
 export default class VelociousRootRoute extends BasicRoute {
+  /**
+   * Application catch-all route declared with `route.catchAll(...)`, or null
+   * when the application did not declare one.
+   * @type {CatchAllRoute | null} */
+  catchAllRoute = null
+
+  /**
+   * Runs catch all. Declares the application's catch-all route: unmatched
+   * requests resolve to the given controller/action instead of the built-in
+   * errors not-found response.
+   * @param {import("./catch-all-route.js").CatchAllRouteOptions} [options] - Catch-all options.
+   * @returns {void} - No return value.
+   */
+  catchAll(options = {}) {
+    if (this.catchAllRoute) throw new Error("Only one catchAll route can be declared")
+
+    this.catchAllRoute = new CatchAllRoute(options)
+  }
+
   getHumanPaths() {
-    return [
+    /** @type {Array<{action: string | null, method: string, path: string}>} */
+    const humanPaths = [
       {method: "GET", action: "index", path: "/"}
     ]
+
+    if (this.catchAllRoute) humanPaths.push(...this.catchAllRoute.getHumanPaths())
+
+    return humanPaths
   }
 }