@ultimat3/mcp 22.13.0 → 22.14.0

package/README.md

@@ -130,6 +130,13 @@ to mount — no file exports `mcp`, or the export was built without `resolveToke
 `route` — logs `X_MCP_APP_UNMOUNTED` once, with the file to write; `expose: false` mounts nothing
 and says nothing.
 
+**Several endpoints, one per population (Unreleased).** `mcp` may be a non-empty array of
+`defineAppMcp` values: endpoint #0 mounts at `config.ai.mcp.path` and owns the root well-known
+document; every other mounts at its own `defineAppMcp({ path })` and serves only its path-inserted
+metadata document. Each is its own server — catalog, instructions, groups, scopes, prompts. Two on
+one route throws `X_MCP_PATH_DUPLICATE` at boot. `McpPrompt.visibleTo` hides a prompt from
+`prompts/list` and `prompts/get` with the tool/resource `McpVisibility` semantics.
+
 `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": "22.13.0",
+  "version": "22.14.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": "22.13.0",
-    "@ultimat3/core": "22.13.0",
-    "@ultimat3/entity": "22.13.0",
-    "@ultimat3/http": "22.13.0",
-    "@ultimat3/jobs": "22.13.0",
-    "@ultimat3/policy": "22.13.0",
-    "@ultimat3/query": "22.13.0",
-    "@ultimat3/schema": "22.13.0"
+    "@ultimat3/action": "22.14.0",
+    "@ultimat3/core": "22.14.0",
+    "@ultimat3/entity": "22.14.0",
+    "@ultimat3/http": "22.14.0",
+    "@ultimat3/jobs": "22.14.0",
+    "@ultimat3/policy": "22.14.0",
+    "@ultimat3/query": "22.14.0",
+    "@ultimat3/schema": "22.14.0"
   }
 }

package/src/errors.ts

@@ -26,6 +26,7 @@ export const MCP_ERROR_CODES = [
   'X_MCP_OAUTH_INVALID',
   'X_MCP_IDEMPOTENCY_KEY_SHADOWED',
   'X_MCP_SURFACE_OVER_BUDGET',
+  'X_MCP_PATH_DUPLICATE',
 ] as const;
 
 export type McpErrorCode = (typeof MCP_ERROR_CODES)[number];
@@ -54,6 +55,7 @@ export const MCP_ERROR_TITLES: Readonly<Record<McpErrorCode, string>> = {
   X_MCP_IDEMPOTENCY_KEY_SHADOWED:
     "an idempotent action's input declares idempotencyKey, the MCP argument reserved for the idempotency key",
   X_MCP_SURFACE_OVER_BUDGET: "an MCP surface an agent reads is larger than the app's budget for it",
+  X_MCP_PATH_DUPLICATE: 'two MCP endpoints claim one path',
 };
 
 // Titles must be registered for `format()` to render the contract's first line. Every code above is
@@ -197,17 +199,26 @@ export class McpToolUndeclaredError extends UltimateError {
  */
 export class McpAppUnmountedError extends UltimateError {
   readonly reason: 'missing' | 'no-route';
-  constructor(input: { reason: 'missing' | 'no-route'; path: string; file: string }) {
+  constructor(input: {
+    reason: 'missing' | 'no-route';
+    path: string;
+    file: string;
+    /** Index in an `mcp` array export; absent for a single export or the first endpoint. */
+    endpoint?: number;
+  }) {
+    const where =
+      input.endpoint === undefined ? input.file : `${input.file} (mcp[${input.endpoint}])`;
+    const route = input.endpoint === undefined ? `POST ${input.path}` : 'its endpoint';
     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`,
+          : `${where} exports mcp with no route — defineAppMcp was given no resolveToken — so ${route} 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`,
+          : `add resolveToken: (token) => resolveAgentToken(token) to the defineAppMcp({ ... }) at ${where} — the route is only built with one`,
     });
     this.reason = input.reason;
   }

package/src/index.ts

@@ -117,6 +117,7 @@ export {
   oneLineParams,
   renderCatalog,
 } from './meta-surface';
+export { McpPathDuplicateError } from './mount-errors';
 export type { McpOAuth } from './oauth-metadata';
 export {
   metadataPaths,

package/src/mount-errors.ts

@@ -0,0 +1,31 @@
+// The boot-time refusal of an app's MCP MOUNT: several `defineAppMcp` endpoints, one path each.
+// The code and title are registered in `errors.ts` with the rest of the package's; the class sits
+// apart only so that file stays under the size ceiling (the `meta-errors.ts` precedent).
+
+import { UltimateError } from '@ultimat3/core';
+
+/**
+ * Two endpoints resolved to one route. Thrown, never warned: the route table would keep whichever
+ * came first, and the population behind the second would be answered with the first's catalog,
+ * instructions and scopes — silently, and only for the URL both claimed.
+ */
+export class McpPathDuplicateError extends UltimateError {
+  readonly path: string;
+  readonly endpoints: readonly [number, number];
+
+  constructor(input: {
+    method: string;
+    path: string;
+    endpoints: readonly [number, number];
+    file: string;
+  }) {
+    const [first, second] = input.endpoints;
+    super({
+      code: 'X_MCP_PATH_DUPLICATE',
+      cause: `${input.file} exports mcp endpoints #${first} and #${second}, and both claim ${input.method} ${input.path}`,
+      fix: `give endpoint #${second} in ${input.file} its own path — defineAppMcp({ path: '/mcp/<population>', ... }); endpoint #0 mounts at ai.mcp.path and every other at its own defineAppMcp path`,
+    });
+    this.path = input.path;
+    this.endpoints = input.endpoints;
+  }
+}

package/src/prompts-get.ts

@@ -2,6 +2,8 @@
 // advertises the `prompts` capability, so a listed prompt that `prompts/get` cannot resolve is a
 // capability the server claims and does not have.
 
+import type { McpCaller } from './registry';
+import { visibleToCaller } from './registry';
 import type { McpPrompt } from './resources';
 import type { JsonRpcId, JsonRpcResponse } from './wire';
 import { errorResponse, INTERNAL_ERROR, INVALID_PARAMS, resultResponse } from './wire';
@@ -13,6 +15,15 @@ export const promptListEntry = (prompt: McpPrompt) => ({
   ...(prompt.arguments === undefined ? {} : { arguments: prompt.arguments }),
 });
 
+/**
+ * The prompts THIS caller may see — the one filter both methods read, so `prompts/list` and
+ * `prompts/get` cannot disagree about a prompt's existence.
+ */
+export const visiblePrompts = (
+  prompts: readonly McpPrompt[],
+  caller: McpCaller,
+): readonly McpPrompt[] => prompts.filter((prompt) => visibleToCaller(prompt, caller));
+
 /** Only string arguments: MCP types every prompt argument as a string. */
 const stringArguments = (raw: unknown): Readonly<Record<string, string>> => {
   if (typeof raw !== 'object' || raw === null) return {};
@@ -25,12 +36,15 @@ export async function promptsGet(
   prompts: readonly McpPrompt[],
   id: JsonRpcId,
   params: Readonly<Record<string, unknown>> | null,
+  caller: McpCaller,
 ): Promise<JsonRpcResponse> {
   const name = params?.['name'];
   if (typeof name !== 'string') {
     return errorResponse(id, INVALID_PARAMS, 'prompts/get params.name must be a string');
   }
-  const prompt = prompts.find((declared) => declared.name === name);
+  // An invisible prompt answers exactly as a missing one: a distinct refusal would tell a customer
+  // the staff prompt exists, which is the one fact `visibleTo` withholds.
+  const prompt = visiblePrompts(prompts, caller).find((declared) => declared.name === name);
   if (prompt === undefined) {
     return errorResponse(id, INVALID_PARAMS, `prompt not found: ${name} — read prompts/list`);
   }

package/src/resources.ts

@@ -61,6 +61,12 @@ export interface McpPrompt {
   readonly name: string;
   readonly description: string;
   readonly arguments?: readonly McpPromptArgument[];
+  /**
+   * Who may see and get it — OUTCOME 1. Absent = everyone. Same `McpVisibility` as a tool's and a
+   * resource's, evaluated by the same fail-closed `visibleToCaller`: a prompt that names a staff
+   * workflow is part of the staff surface, and listing it to a customer leaks the workflow.
+   */
+  readonly visibleTo?: McpVisibility;
   /**
    * The prompt's TEXT, for `prompts/get`, given the arguments the client passed. An injected thunk
    * — the `frameworkResources` pattern — so the server never learns where a prompt lives.

package/src/server.ts

@@ -12,7 +12,7 @@ import { metaCall } from './meta-call';
 import { META_UNKNOWN_FIX } from './meta-errors';
 import type { McpResourceGroups, McpSurfaceOption, MetaResource } from './meta-surface';
 import { MANAGE_RESOURCE, META_TOOL_ENTRIES, META_TOOL_NAMES, MetaSurface } from './meta-surface';
-import { promptListEntry, promptsGet } from './prompts-get';
+import { promptListEntry, promptsGet, visiblePrompts } from './prompts-get';
 import type {
   AnyMcpTool,
   McpCaller,
@@ -198,9 +198,11 @@ export class McpServer {
       case 'ping':
         return resultResponse(id, {});
       case 'prompts/list':
-        return resultResponse(id, { prompts: this.prompts.map(promptListEntry) });
+        return resultResponse(id, {
+          prompts: visiblePrompts(this.prompts, caller).map(promptListEntry),
+        });
       case 'prompts/get':
-        return promptsGet(this.prompts, id, paramsOf(body));
+        return promptsGet(this.prompts, id, paramsOf(body), caller);
       default:
         return errorResponse(id, METHOD_NOT_FOUND, `method not found: ${body.method}`, {
           supported: METHODS,