@ultimat3/mcp 18.0.0 → 19.1.0

package/README.md

@@ -114,10 +114,21 @@ export const mcp = defineAppMcp({
   resolveToken: (token) => sessions.resolveAgentToken(token),
 });
 
-// app.config.ts
-routes: [mcp.route]                      // POST /mcp, rate-limited per method class
 ```
 
+**The web role mounts it, `As of 2026-09-05` — the contract is the file's location.** `app.config.ts`
+has no `routes:` key and never had one; this page said `routes: [mcp.route]` while nothing read it,
+and `POST /mcp` answered `X_ROUTE_NOT_FOUND` in every app ever scaffolded. Now: `apps/<app>/mcp.ts`
+exports `mcp` (the value `defineAppMcp` returns), and both boots — `x dev` and `runRole` — mount
+`POST config.ai.mcp.path` → `mcp.route.handle(request)` when `config.ai.mcp.expose` is `true`,
+which is the **default**, and say `app mcp mounted` in the boot log (`x dev` prints `mcp POST /mcp`
+in its summary). The http pipeline does not pre-judge the route (`auth: 'public'`,
+`enforcedBy: 'handler'`): `mcp.route.handle` reads `Authorization: Bearer` through `resolveToken`
+and decides per tool through the policy every other surface evaluates. `expose: true` with nothing
+to mount — no file exports `mcp`, or the export was built without `resolveToken` and so carries no
+`route` — logs `X_MCP_APP_UNMOUNTED` once, with the file to write; `expose: false` mounts nothing
+and says nothing.
+
 `include: 'exposed'` reads the action and query registries instead of asking for
 `actions: [...]` / `queries: [...]` — the registries already know who opted in, and a
 second hand-maintained list is a thing that goes stale silently. The explicit arrays still

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/mcp",
-  "version": "18.0.0",
+  "version": "19.1.0",
   "description": "MCP server, dev tools, and the action-to-tool projection \u2014 one authz system, two surfaces",
   "license": "MIT",
   "type": "module",
@@ -31,13 +31,13 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/action": "18.0.0",
-    "@ultimat3/core": "18.0.0",
-    "@ultimat3/entity": "18.0.0",
-    "@ultimat3/http": "18.0.0",
-    "@ultimat3/jobs": "18.0.0",
-    "@ultimat3/policy": "18.0.0",
-    "@ultimat3/query": "18.0.0",
-    "@ultimat3/schema": "18.0.0"
+    "@ultimat3/action": "19.1.0",
+    "@ultimat3/core": "19.1.0",
+    "@ultimat3/entity": "19.1.0",
+    "@ultimat3/http": "19.1.0",
+    "@ultimat3/jobs": "19.1.0",
+    "@ultimat3/policy": "19.1.0",
+    "@ultimat3/query": "19.1.0",
+    "@ultimat3/schema": "19.1.0"
   }
 }

package/src/errors.ts

@@ -17,6 +17,7 @@ export const MCP_ERROR_CODES = [
   'X_MCP_SCOPE_UNKNOWN',
   'X_MCP_SCOPE_CONFLICT',
   'X_MCP_RATE_LIMITED',
+  'X_MCP_APP_UNMOUNTED',
 ] as const;
 
 export type McpErrorCode = (typeof MCP_ERROR_CODES)[number];
@@ -35,6 +36,7 @@ export const MCP_ERROR_TITLES: Readonly<Record<McpErrorCode, string>> = {
   X_MCP_SCOPE_UNKNOWN: 'defineAppMcp scopes a tool this server does not project',
   X_MCP_SCOPE_CONFLICT: 'two scopes claim one MCP tool',
   X_MCP_RATE_LIMITED: "the caller has spent its allowance for this request's class",
+  X_MCP_APP_UNMOUNTED: "the app's MCP endpoint is exposed in config and nothing can be mounted",
 };
 
 // Titles must be registered for `format()` to render the contract's first line. Every code above is
@@ -156,6 +158,33 @@ export class McpToolUndeclaredError extends UltimateError {
  * asking for the name reaches whichever copy won, which is the worst failure mode available —
  * a call that succeeds against the wrong handler and reports nothing.
  */
+/**
+ * `config.ai.mcp.expose` is `true` — the DEFAULT — and the web role found nothing to mount at
+ * `config.ai.mcp.path`. Two causes, one code: no `apps/<app>/mcp.ts` exports an `mcp`, or the one
+ * that does was built without `resolveToken`, so `defineAppMcp` built no `route` (a token resolver
+ * is what turns a bearer header into an actor, and an endpoint with no way to name its caller is
+ * not one the framework will serve). Logged once per boot by the web role, never thrown: an app
+ * with no agent surface yet is a working app, and this line is the instruction for the day it
+ * wants one.
+ */
+export class McpAppUnmountedError extends UltimateError {
+  readonly reason: 'missing' | 'no-route';
+  constructor(input: { reason: 'missing' | 'no-route'; path: string; file: string }) {
+    super({
+      code: 'X_MCP_APP_UNMOUNTED',
+      cause:
+        input.reason === 'missing'
+          ? `ai.mcp.expose is true and no ${input.file} exports mcp, so POST ${input.path} answers 404`
+          : `${input.file} exports mcp with no route — defineAppMcp was given no resolveToken — so POST ${input.path} answers 404`,
+      fix:
+        input.reason === 'missing'
+          ? `write ${input.file}: export const mcp = defineAppMcp({ include: 'exposed', resolveToken: (token) => resolveAgentToken(token) }) — or set ai: { mcp: { expose: false } } in app.config.ts`
+          : `add resolveToken: (token) => resolveAgentToken(token) to defineAppMcp({ ... }) in ${input.file} — the route is only built with one`,
+    });
+    this.reason = input.reason;
+  }
+}
+
 export class McpToolDuplicateError extends UltimateError {
   /**
    * Which declaration each copy came from, when the projector knows — carried the way

package/src/index.ts

@@ -33,6 +33,7 @@ export type { McpErrorCode } from './errors';
 export {
   MCP_ERROR_CODES,
   MCP_ERROR_TITLES,
+  McpAppUnmountedError,
   McpArgsInvalidError,
   McpNotBranchDbError,
   McpProtocolError,