@ultimat3/cli 22.13.0 → 22.14.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/cli",
-  "version": "22.13.0",
+  "version": "22.14.0",
   "description": "The `x` binary: new, dev, build, verify, generate, db, mcp, doctor, deploy",
   "license": "MIT",
   "type": "module",
@@ -38,33 +38,33 @@
   },
   "dependencies": {
     "@babel/core": "^8.0.1",
-    "@ultimat3/action": "22.13.0",
-    "@ultimat3/admin": "22.13.0",
-    "@ultimat3/ai": "22.13.0",
-    "@ultimat3/auth": "22.13.0",
-    "@ultimat3/cache": "22.13.0",
-    "@ultimat3/core": "22.13.0",
-    "@ultimat3/db": "22.13.0",
-    "@ultimat3/entity": "22.13.0",
-    "@ultimat3/flags": "22.13.0",
-    "@ultimat3/http": "22.13.0",
-    "@ultimat3/i18n": "22.13.0",
-    "@ultimat3/jobs": "22.13.0",
-    "@ultimat3/mail": "22.13.0",
-    "@ultimat3/manifest": "22.13.0",
-    "@ultimat3/mcp": "22.13.0",
-    "@ultimat3/money": "22.13.0",
-    "@ultimat3/notify": "22.13.0",
-    "@ultimat3/policy": "22.13.0",
-    "@ultimat3/pwa": "22.13.0",
-    "@ultimat3/query": "22.13.0",
-    "@ultimat3/realtime": "22.13.0",
-    "@ultimat3/render": "22.13.0",
-    "@ultimat3/schema": "22.13.0",
-    "@ultimat3/seo": "22.13.0",
-    "@ultimat3/storage": "22.13.0",
-    "@ultimat3/testing": "22.13.0",
-    "@ultimat3/time": "22.13.0",
+    "@ultimat3/action": "22.14.0",
+    "@ultimat3/admin": "22.14.0",
+    "@ultimat3/ai": "22.14.0",
+    "@ultimat3/auth": "22.14.0",
+    "@ultimat3/cache": "22.14.0",
+    "@ultimat3/core": "22.14.0",
+    "@ultimat3/db": "22.14.0",
+    "@ultimat3/entity": "22.14.0",
+    "@ultimat3/flags": "22.14.0",
+    "@ultimat3/http": "22.14.0",
+    "@ultimat3/i18n": "22.14.0",
+    "@ultimat3/jobs": "22.14.0",
+    "@ultimat3/mail": "22.14.0",
+    "@ultimat3/manifest": "22.14.0",
+    "@ultimat3/mcp": "22.14.0",
+    "@ultimat3/money": "22.14.0",
+    "@ultimat3/notify": "22.14.0",
+    "@ultimat3/policy": "22.14.0",
+    "@ultimat3/pwa": "22.14.0",
+    "@ultimat3/query": "22.14.0",
+    "@ultimat3/realtime": "22.14.0",
+    "@ultimat3/render": "22.14.0",
+    "@ultimat3/schema": "22.14.0",
+    "@ultimat3/seo": "22.14.0",
+    "@ultimat3/storage": "22.14.0",
+    "@ultimat3/testing": "22.14.0",
+    "@ultimat3/time": "22.14.0",
     "babel-preset-solid": "^1.9.15"
   }
 }

package/src/app-mcp.ts

@@ -3,7 +3,9 @@
 // `ai: { mcp: { expose: true, path: '/mcp' } }` by DEFAULT, and nothing between the two served it:
 // neither `x dev` nor `runRole` mounted the route, so `POST /mcp` answered `X_ROUTE_NOT_FOUND` in
 // every app ever scaffolded (measured 2026-09-05). The contract is one file: `apps/<app>/mcp.ts`
-// exports `mcp`, an `AppMcp`; this module finds it, and both boots mount what it carries.
+// exports `mcp` — one `AppMcp`, or an array of them, one per population (customers, staff,
+// affiliates) — this module finds it, and both boots mount what it carries: endpoint #0 at
+// `ai.mcp.path`, every other at its own `defineAppMcp({ path })`.
 
 // why: a directory's existence — `Bun.file().exists()` answers for files, and `apps/` is a directory.
 import { existsSync } from 'node:fs';
@@ -12,23 +14,38 @@ import { join } from 'node:path';
 import { logger } from '@ultimat3/core';
 import type { Route } from '@ultimat3/http';
 import { json, selfOrigin } from '@ultimat3/http';
-import { type AppMcp, McpAppUnmountedError } from '@ultimat3/mcp';
+import {
+  type AppMcp,
+  McpAppUnmountedError,
+  McpPathDuplicateError,
+  PROTECTED_RESOURCE_WELL_KNOWN,
+} from '@ultimat3/mcp';
 import { APP_CONFIG_EXPORT } from './app-auth';
 import { APP_CONFIG_FILE } from './app-root';
 
 /** The one file an app writes, per app directory. */
 export const APP_MCP_GLOB = 'apps/*/mcp.ts';
-/** The export that file makes — an `AppMcp`, the value `defineAppMcp` returns. */
+/**
+ * The export that file makes — an `AppMcp`, the value `defineAppMcp` returns, or a non-empty array
+ * of them. ONE export name either way: a second named export per endpoint would be a second way
+ * to say the same thing, and the array's order is the one fact the mount needs (#0 is the default).
+ */
 export const APP_MCP_EXPORT = 'mcp';
-/** What the boot line and `/_x` call the route. */
+/** What the boot line and `/_x` call endpoint #0's route; endpoint #n is `mcp:<its path>`. */
 export const APP_MCP_ROUTE_NAME = 'mcp';
 
 export interface AppMcpMount {
-  /** `[]` when `expose` is false, when nothing exports `mcp`, or when the export has no route. */
+  /** `[]` when `expose` is false, when nothing exports `mcp`, or when no endpoint has a route. */
   readonly routes: readonly Route[];
-  /** `POST <path>` when mounted, else `null` — the boot line prints it. */
+  /** Endpoint #0's `POST <path>` when mounted, else `null` — the default, at `ai.mcp.path`. */
   readonly path: string | null;
-  /** Set exactly when `expose` is true and `routes` is empty: the reason, as an instruction. */
+  /** Every mounted endpoint's `POST <path>`, in export order — the boot line prints one each. */
+  readonly paths: readonly string[];
+  /**
+   * Set when `expose` is true and an endpoint could not be mounted — nothing exports `mcp`, or the
+   * first endpoint built without `resolveToken`: the reason, as an instruction. The endpoints that
+   * could be mounted still are.
+   */
   readonly warning: McpAppUnmountedError | undefined;
 }
 
@@ -65,6 +82,13 @@ async function exposeDeclaration(root: string): Promise<ExposeDeclaration | unde
 const isAppMcp = (value: unknown): value is AppMcp =>
   isRecord(value) && 'server' in value && 'tools' in value && 'route' in value;
 
+/** The export as a list of endpoints, or `undefined` when it is not one (the "missing" case). */
+function endpointsOf(exported: unknown): readonly AppMcp[] | undefined {
+  if (isAppMcp(exported)) return [exported];
+  if (!Array.isArray(exported) || exported.length === 0) return undefined;
+  return exported.every(isAppMcp) ? (exported as readonly AppMcp[]) : undefined;
+}
+
 /** Every `apps/<app>/mcp.ts`, app-root-relative and sorted, so two apps answer in one order. */
 async function candidates(root: string): Promise<readonly string[]> {
   // A root with no `apps/` is an app with no MCP file, never a boot failure — the scan's ENOENT
@@ -75,8 +99,10 @@ async function candidates(root: string): Promise<readonly string[]> {
   return files.sort();
 }
 
+const NOTHING: AppMcpMount = { routes: [], path: null, paths: [], warning: undefined };
+
 /**
- * The route to mount, or the reason there is none. Pure over the filesystem it is pointed at;
+ * The routes to mount, or the reason there are none. Pure over the filesystem it is pointed at;
  * `mountAppMcp` below is the one place the warning becomes a log line.
  *
  * `meta.auth: 'public'` and `enforcedBy: 'handler'` — the http pipeline must not pre-judge:
@@ -87,72 +113,17 @@ async function candidates(root: string): Promise<readonly string[]> {
  */
 export async function appMcpMount(root: string): Promise<AppMcpMount> {
   const declared = await exposeDeclaration(root);
-  if (declared === undefined || !declared.expose)
-    return { routes: [], path: null, warning: undefined };
+  if (declared === undefined || !declared.expose) return NOTHING;
   const files = await candidates(root);
   const fallbackFile = 'apps/web/mcp.ts';
-  if (files.length === 0) {
-    return {
-      routes: [],
-      path: null,
-      warning: new McpAppUnmountedError({
-        reason: 'missing',
-        path: declared.path,
-        file: fallbackFile,
-      }),
-    };
-  }
   for (const file of files) {
     const module = (await import(join(root, file))) as Record<string, unknown>;
-    const exported = module[APP_MCP_EXPORT];
-    if (!isAppMcp(exported)) continue;
-    const route = exported.route;
-    if (route === undefined) {
-      return {
-        routes: [],
-        path: null,
-        warning: new McpAppUnmountedError({ reason: 'no-route', path: declared.path, file }),
-      };
-    }
-    // The PUBLIC origin, as the pipeline resolved it (`ctx.https` honours a trusted proxy's
-    // `x-forwarded-proto`): behind a TLS-terminating ingress the raw request URL is `http://` on
-    // an internal host, and a `resource_metadata` naming that is a URL no client can reach.
-    const resource = route.protectedResource;
-    return {
-      routes: [
-        {
-          method: 'POST',
-          path: declared.path,
-          handler: (request, ctx) =>
-            route.handle(request.raw, { origin: selfOrigin(ctx.url, ctx.https) }),
-          meta: { name: APP_MCP_ROUTE_NAME, auth: 'public', enforcedBy: 'handler' },
-        },
-        // RFC 9728 protected-resource metadata, when the app declared `oauth`: path-inserted and
-        // at the root, so a client probing either finds the authorization server.
-        ...(resource === undefined
-          ? []
-          : resource.paths.map(
-              (path): Route => ({
-                method: 'GET',
-                path,
-                handler: (_request, ctx) => {
-                  const response = json(resource.document(selfOrigin(ctx.url, ctx.https)));
-                  // A browser-hosted MCP client reads this cross-origin; it holds nothing secret.
-                  response.headers.set('access-control-allow-origin', '*');
-                  response.headers.set('cache-control', 'public, max-age=3600');
-                  return response;
-                },
-                meta: { name: `${APP_MCP_ROUTE_NAME}.oauth-protected-resource`, auth: 'public' },
-              }),
-            )),
-      ],
-      path: declared.path,
-      warning: undefined,
-    };
+    const endpoints = endpointsOf(module[APP_MCP_EXPORT]);
+    if (endpoints === undefined) continue;
+    return mountEndpoints(endpoints, declared.path, file);
   }
   return {
-    routes: [],
-    path: null,
+    ...NOTHING,
     warning: new McpAppUnmountedError({
       reason: 'missing',
       path: declared.path,
@@ -161,6 +132,95 @@ export async function appMcpMount(root: string): Promise<AppMcpMount> {
   };
 }
 
+/**
+ * One file's endpoints onto one route table. An endpoint built without `resolveToken` has no
+ * route: it is skipped and the FIRST such is the warning, so one unfinished population never takes
+ * the others down with it. Two endpoints on one route is thrown — see `McpPathDuplicateError`.
+ */
+function mountEndpoints(
+  endpoints: readonly AppMcp[],
+  defaultPath: string,
+  file: string,
+): AppMcpMount {
+  const routes: Route[] = [];
+  const paths: string[] = [];
+  const claimed = new Map<string, number>();
+  let warning: McpAppUnmountedError | undefined;
+  endpoints.forEach((endpoint, index) => {
+    const route = endpoint.route;
+    if (route === undefined) {
+      warning ??= new McpAppUnmountedError({
+        reason: 'no-route',
+        path: defaultPath,
+        file,
+        ...(index === 0 ? {} : { endpoint: index }),
+      });
+      return;
+    }
+    const path = index === 0 ? defaultPath : route.path;
+    for (const mounted of endpointRoutes(route, path, index)) {
+      const key = `${mounted.method} ${mounted.path}`;
+      const first = claimed.get(key);
+      if (first !== undefined) {
+        throw new McpPathDuplicateError({
+          method: mounted.method,
+          path: mounted.path,
+          endpoints: [first, index],
+          file,
+        });
+      }
+      claimed.set(key, index);
+      routes.push(mounted);
+    }
+    paths.push(path);
+  });
+  const path = endpoints[0]?.route === undefined ? null : defaultPath;
+  return { routes, path, paths, warning };
+}
+
+type Descriptor = NonNullable<AppMcp['route']>;
+
+/** One endpoint's `POST` and, when it declared `oauth`, its RFC 9728 metadata `GET`s. */
+function endpointRoutes(route: Descriptor, path: string, index: number): readonly Route[] {
+  const name = index === 0 ? APP_MCP_ROUTE_NAME : `${APP_MCP_ROUTE_NAME}:${path}`;
+  const resource = route.protectedResource;
+  // The ROOT document belongs to endpoint #0 alone: a client that probes the bare well-known URL
+  // is asking about the default resource, and a second endpoint answering there would collide.
+  // Every endpoint keeps its path-inserted document (RFC 9728 §3.1), which its own 401 names.
+  const metadata: readonly Route[] =
+    resource === undefined
+      ? []
+      : resource.paths
+          .filter((metadataPath) => index === 0 || metadataPath !== PROTECTED_RESOURCE_WELL_KNOWN)
+          .map(
+            (metadataPath): Route => ({
+              method: 'GET',
+              path: metadataPath,
+              handler: (_request, ctx) => {
+                const response = json(resource.document(selfOrigin(ctx.url, ctx.https)));
+                // A browser-hosted MCP client reads this cross-origin; it holds nothing secret.
+                response.headers.set('access-control-allow-origin', '*');
+                response.headers.set('cache-control', 'public, max-age=3600');
+                return response;
+              },
+              meta: { name: `${name}.oauth-protected-resource`, auth: 'public' },
+            }),
+          );
+  return [
+    {
+      method: 'POST',
+      path,
+      // The PUBLIC origin, as the pipeline resolved it (`ctx.https` honours a trusted proxy's
+      // `x-forwarded-proto`): behind a TLS-terminating ingress the raw request URL is `http://`
+      // on an internal host, and a `resource_metadata` naming that is a URL no client can reach.
+      handler: (request, ctx) =>
+        route.handle(request.raw, { origin: selfOrigin(ctx.url, ctx.https) }),
+      meta: { name, auth: 'public', enforcedBy: 'handler' },
+    },
+    ...metadata,
+  ];
+}
+
 /**
  * The boot's call: the routes to spread into the table, with the warning already logged ONCE and
  * the mount announced. Both `x dev` and `runRole` go through here, so a developer's terminal and a
@@ -171,6 +231,6 @@ export async function mountAppMcp(root: string): Promise<AppMcpMount> {
   if (mount.warning !== undefined) {
     logger.warn(`${mount.warning.code}: ${mount.warning.cause} — fix: ${mount.warning.fix}`);
   }
-  if (mount.path !== null) logger.info('app mcp mounted', { method: 'POST', path: mount.path });
+  for (const path of mount.paths) logger.info('app mcp mounted', { method: 'POST', path });
   return mount;
 }

package/src/cmd-dev.ts

@@ -79,8 +79,10 @@ export interface DevServer {
   readonly runtime: RunningServices;
   /** Panel keys `/_x` mounted, in tab order. Reported so `--json` names what is reachable. */
   readonly panels: readonly string[];
-  /** `POST <path>` of the app's own MCP endpoint, or `null` when nothing was mounted. */
+  /** `POST <path>` of the app's default MCP endpoint, or `null` when nothing was mounted. */
   readonly mcp: string | null;
+  /** `POST <path>` of every mounted MCP endpoint, default first — `[]` when none was. */
+  readonly mcpPaths: readonly string[];
   stop(): Promise<void>;
 }
 
@@ -240,7 +242,7 @@ async function bootDev(
   // `x dev`'s own, so a reload can empty it: an `isr` page's first render was otherwise served for
   // its whole ttl after every save, whatever the modules behind it now said.
   const isr = createIsrController({ buildId });
-  const { routes, theme, errorStyles, mcpPath } = await devRouteTable({
+  const { routes, theme, errorStyles, mcpPath, mcpPaths } = await devRouteTable({
     isr,
     root: options.root,
     env: options.env,
@@ -328,6 +330,7 @@ async function bootDev(
     services,
     roles: running.roles,
     mcp: mcpPath,
+    mcpPaths,
     get buildId(): string {
       return stamped ?? state.manifest.buildId;
     },
@@ -447,6 +450,7 @@ export const devCommand: CliCommand = {
         introspect: `${server.url}/_x`,
         panels: [...server.panels],
         mcp: server.mcp,
+        mcpPaths: [...server.mcpPaths],
       },
       lines: [
         // A hard kill leaves the lock behind; clearing it is normal and worth one line, never a
@@ -458,7 +462,8 @@ export const devCommand: CliCommand = {
         msg('cli.dev.introspect', { url: `${server.url}/_x` }),
         // Only when something was mounted: the unmounted case has already said why, once, as a
         // warning with a fix, and a summary line reading `mcp none` would be a second copy of it.
-        ...(server.mcp === null ? [] : [msg('cli.dev.mcp', { path: server.mcp })]),
+        // One line per endpoint, so an app serving customers, staff and affiliates sees all three.
+        ...server.mcpPaths.map((path) => msg('cli.dev.mcp', { path })),
       ],
     };
     await writeLock(services.stateDir, {

package/src/dev-route-table.ts

@@ -58,8 +58,10 @@ export interface DevRouteTable {
   readonly theme: ThemeBoot;
   /** The app's own error pages' inline styles, admitted the same way. */
   readonly errorStyles: readonly string[];
-  /** Where the app's MCP endpoint was mounted, or `undefined`. */
+  /** Where the app's default MCP endpoint was mounted, or `null`. */
   readonly mcpPath: string | null;
+  /** Every mounted MCP endpoint's path, default first — one per population the app serves. */
+  readonly mcpPaths: readonly string[];
 }
 
 export async function devRouteTable(input: DevRouteTableInput): Promise<DevRouteTable> {
@@ -156,5 +158,5 @@ export async function devRouteTable(input: DevRouteTableInput): Promise<DevRoute
     }),
   ];
 
-  return { routes, theme, errorStyles, mcpPath: mcpMount.path };
+  return { routes, theme, errorStyles, mcpPath: mcpMount.path, mcpPaths: mcpMount.paths };
 }