@ultimat3/admin 30.3.0 → 30.4.0

package/README.md

@@ -482,7 +482,13 @@ The admin exposes **its own MCP surface**, derived from the same resources and g
 ```ts
 import { adminMcp, adminMcpTools } from '@ultimat3/admin';
 
-export const mcp = adminMcp({ app: admin, actor: (session) => actorFor(session.token) });
+// apps/admin/mcp.ts — module scope: the mount serves every apps/<app>/mcp.ts, after the scan
+export const mcp = adminMcp({
+  app: admin,
+  path: '/admin/mcp', // beside the web endpoint's /mcp
+  include: 'exposed', // the app's exposed actions (admin:write) and queries (admin:read) too
+  actor: ({ token, facts }) => actorFor(token, facts),
+});
 adminMcpTools(admin, ctx); // admin.post.list · admin.post.read · admin.search · admin.action.post.publish
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/admin",
-  "version": "30.3.0",
+  "version": "30.4.0",
   "description": "Two dashboards: the /_x framework dev panels and the generated, AI-first app admin",
   "keywords": [
     "ultimate",
@@ -45,21 +45,21 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/action": "30.3.0",
-    "@ultimat3/ai": "30.3.0",
-    "@ultimat3/cache": "30.3.0",
-    "@ultimat3/core": "30.3.0",
-    "@ultimat3/db": "30.3.0",
-    "@ultimat3/entity": "30.3.0",
-    "@ultimat3/http": "30.3.0",
-    "@ultimat3/i18n": "30.3.0",
-    "@ultimat3/jobs": "30.3.0",
-    "@ultimat3/mcp": "30.3.0",
-    "@ultimat3/money": "30.3.0",
-    "@ultimat3/policy": "30.3.0",
-    "@ultimat3/query": "30.3.0",
-    "@ultimat3/render": "30.3.0",
-    "@ultimat3/schema": "30.3.0",
-    "@ultimat3/ui": "30.3.0"
+    "@ultimat3/action": "30.4.0",
+    "@ultimat3/ai": "30.4.0",
+    "@ultimat3/cache": "30.4.0",
+    "@ultimat3/core": "30.4.0",
+    "@ultimat3/db": "30.4.0",
+    "@ultimat3/entity": "30.4.0",
+    "@ultimat3/http": "30.4.0",
+    "@ultimat3/i18n": "30.4.0",
+    "@ultimat3/jobs": "30.4.0",
+    "@ultimat3/mcp": "30.4.0",
+    "@ultimat3/money": "30.4.0",
+    "@ultimat3/policy": "30.4.0",
+    "@ultimat3/query": "30.4.0",
+    "@ultimat3/render": "30.4.0",
+    "@ultimat3/schema": "30.4.0",
+    "@ultimat3/ui": "30.4.0"
   }
 }

package/src/mcp-scopes.ts

@@ -2,10 +2,10 @@
 // what a resolved token carries. The gate itself is `@ultimat3/mcp`'s registry — this file only
 // declares the cut (`defineAppMcp({ scopes })`) and the token's half of it.
 
-import type { McpScopes } from '@ultimat3/mcp';
+import type { McpScopes, ProjectablePrimitive } from '@ultimat3/mcp';
 import { expandPermissions } from './authz';
 import type { AdminMcpTool } from './mcp-tools';
-import { ADMIN_DESTROY, ADMIN_PERMISSIONS } from './permissions';
+import { ADMIN_DESTROY, ADMIN_PERMISSIONS, ADMIN_READ, ADMIN_WRITE } from './permissions';
 
 const isAdminPermission = (scope: string): boolean =>
   (ADMIN_PERMISSIONS as readonly string[]).includes(scope);
@@ -34,3 +34,21 @@ export function adminToolScopes(tools: readonly AdminMcpTool[]): McpScopes {
   for (const tool of tools) by.set(tool.scope, [...(by.get(tool.scope) ?? []), tool.name]);
   return Object.fromEntries(by);
 }
+
+/**
+ * The app's exposed primitives an admin endpoint serves (`adminMcp({ include: 'exposed' })`),
+ * each under the admin scope its KIND needs — a query reads, an action writes; the framework
+ * cannot tell an insert from a delete, so never `admin:destroy`. Merged into the admin's own cut,
+ * so the map stays total and a read-only token stays read-only on the app's tools too.
+ */
+export function includedToolScopes(
+  primitives: readonly ProjectablePrimitive[],
+  scopes: McpScopes,
+): McpScopes {
+  const by = new Map(Object.entries(scopes).map(([scope, names]) => [scope, [...names]]));
+  for (const primitive of primitives) {
+    const scope = primitive.mutates === false ? ADMIN_READ : ADMIN_WRITE;
+    by.set(scope, [...(by.get(scope) ?? []), primitive.name]);
+  }
+  return Object.fromEntries(by);
+}

package/src/mcp.ts

@@ -8,9 +8,11 @@ import {
   type AnyMcpTool,
   type AppMcp,
   defineAppMcp,
+  exposedPrimitives,
   type JsonSchema,
   jsonResult,
   type McpCaller,
+  type McpRequestFacts,
   type McpToolResult,
   type ResolvedToken,
   type ToolArgs,
@@ -33,7 +35,7 @@ import {
 import { AdminFilterInvalidError } from './errors';
 import type { AdminFieldType } from './fields';
 import { type AskedFilter, checkedFilter } from './list-filters';
-import { adminTokenScopes, adminToolScopes } from './mcp-scopes';
+import { adminTokenScopes, adminToolScopes, includedToolScopes } from './mcp-scopes';
 import { type AdminMcpTool, adminMcpTools, adminToolCatalog } from './mcp-tools';
 import type { AdminAction, AdminRow } from './registry';
 import { adminSearch } from './search';
@@ -250,9 +252,23 @@ export interface AdminMcpActor extends AdminActor {
 
 export interface AdminMcpOptions {
   readonly app: AdminApp;
-  /** Resolve the MCP session's actor. The same hook the HTTP surface uses, never a bypass. */
-  actor(session: { readonly token?: string }): Promise<AdminMcpActor | null> | AdminMcpActor | null;
+  /**
+   * Resolve the MCP session's actor. The same hook the HTTP surface uses, never a bypass. `facts`:
+   * how the request arrived (address, `Origin`) — what a development token is decided on.
+   */
+  actor(session: {
+    readonly token?: string;
+    readonly facts?: McpRequestFacts;
+  }): Promise<AdminMcpActor | null> | AdminMcpActor | null;
   readonly requestId?: () => string;
+  /** Mount path, `defineAppMcp`'s own. Default `/mcp`; an admin surface beside the app's says `/admin/mcp`. */
+  readonly path?: string;
+  /**
+   * `'exposed'`: the app's own MCP tools here too, projected by `defineAppMcp` as on `/mcp`, each
+   * under its kind's admin scope (`includedToolScopes`). Call `adminMcp` at module scope in
+   * `apps/<app>/mcp.ts`: the mount refuses a catalog built before the scan ended (`X_MCP_INCLUDE_EARLY`).
+   */
+  readonly include?: 'exposed';
 }
 
 /** A field type an agent can actually send. Anything richer is a JSON object on the wire. */
@@ -436,15 +452,20 @@ export function adminMcp(opts: AdminMcpOptions): AppMcp {
   const requestId = opts.requestId ?? ((): string => crypto.randomUUID());
   const catalog = adminToolCatalog(opts.app);
 
+  const own = adminToolScopes(catalog);
+
   return defineAppMcp({
     name: 'admin',
     tools: catalog.map((tool) => toMcpTool(opts, requestId, tool)),
+    ...(opts.path === undefined ? {} : { path: opts.path }),
+    // The app's tools are `defineAppMcp`'s projection, never a copy; the scopes read the same registry.
+    ...(opts.include === undefined ? {} : { include: opts.include }),
     // The connection gate: each tool needs its admin-level permission as a token scope, checked
     // by the registry BEFORE the actor's policy. A stdio host builds its caller's scopes with
     // `adminTokenScopes`, as `resolveToken` does below.
-    scopes: adminToolScopes(catalog),
-    async resolveToken(token: string): Promise<ResolvedToken | null> {
-      const actor = await opts.actor({ token });
+    scopes: opts.include === 'exposed' ? includedToolScopes(exposedPrimitives(), own) : own,
+    async resolveToken(token: string, facts: McpRequestFacts): Promise<ResolvedToken | null> {
+      const actor = await opts.actor({ token, facts });
       // `kind: 'agent'` — the same actor shape an agent gets everywhere else, so a policy
       // that distinguishes agents from people keeps working on this surface.
       //