@ultimat3/mcp 1.0.0

package/src/dev-host.ts

@@ -0,0 +1,59 @@
+// Wires the framework's own description functions into a `DevHost` and assembles the dev
+// MCP server. Split from `dev-server.ts` so the tool definitions stay dependency-free and
+// unit-testable against a fake host — this file is the only place that reaches into the
+// primitive registries.
+
+import { describeActions } from '@ultimat3/action';
+import { FRAMEWORK_VERSION } from '@ultimat3/core';
+import { describeEntities } from '@ultimat3/entity';
+import { describeJobs, inspectJob, jobDriver } from '@ultimat3/jobs';
+import { describeQueries } from '@ultimat3/query';
+import type { DevCapabilities, DevHost, DevIntrospection } from './dev-server';
+import { devTools } from './dev-server';
+import type { FrameworkResourceProviders } from './resources';
+import { frameworkResources } from './resources';
+import { createMcpServer, type McpServer } from './server';
+
+/**
+ * The description half of a real app's `DevHost`. `routes` and `policies` are supplied by
+ * the caller: the route table lives in `@ultimat3/render` and the policy catalog is
+ * assembled per app, both outside what this tier may import.
+ */
+export function frameworkIntrospection(
+  extra: Pick<DevIntrospection, 'routes' | 'policies'>,
+): DevIntrospection {
+  return {
+    routes: extra.routes,
+    policies: extra.policies,
+    entities: () => describeEntities(),
+    actions: () => describeActions(),
+    queries: () => describeQueries(),
+    jobs: () => describeJobs(),
+    // inspectJob needs a driver; the ambient one is set at boot by the app's job config.
+    // Reported as a tool error rather than thrown, so `x mcp` stays usable without a queue.
+    jobInspect: (name: string) => {
+      const driver = jobDriver();
+      if (driver === undefined) return { error: 'no job driver configured' };
+      return inspectJob(driver, name);
+    },
+  };
+}
+
+export interface CreateDevServerInput {
+  readonly host: DevHost;
+  readonly resources?: FrameworkResourceProviders;
+}
+
+/** `x mcp serve` and `POST /mcp` in dev both build the server through this. */
+export function createDevServer(input: CreateDevServerInput): McpServer {
+  return createMcpServer({
+    tools: devTools(input.host),
+    resources: frameworkResources(input.resources ?? {}),
+    serverInfo: { name: 'ultimate-dev', version: FRAMEWORK_VERSION },
+  });
+}
+
+/** Compose the two halves without spelling out the intersection at every call site. */
+export function devHost(introspection: DevIntrospection, capabilities: DevCapabilities): DevHost {
+  return { ...introspection, ...capabilities };
+}

package/src/dev-server.ts

@@ -0,0 +1,303 @@
+// The built-in MCP dev server — the reason an agent needs no framework documentation.
+//
+// Documentation describes; these tools answer. An agent asks `routes.list` instead of
+// reading a routing guide, `errors.explain` instead of searching a code, `verify.run`
+// instead of guessing whether it is done. Every tool declares a scope, and the two that can
+// change something (`db.migrate`, `tests.run`) say so in their own description so a model
+// reading only the catalog still knows what it is holding.
+//
+// Data sources are a single injected `DevHost`. Route and policy description live in
+// packages of this same tier, and the shell-side capabilities (db, tests, logs) belong to
+// the CLI, so this file defines the interface and the CLI satisfies it.
+
+import type { QueryLimits, QueryRows } from './query-limits';
+import { capQueryRows, DEFAULT_QUERY_ROWS, QUERY_LIMITS, resolveQueryLimits } from './query-limits';
+import type { DatabaseTarget } from './readonly-sql';
+import { assertBranchDatabase, assertReadOnlyQuery, PARSE_GUARD } from './readonly-sql';
+import type { AnyMcpTool, McpToolResult, ToolArgs } from './registry';
+import { jsonResult, textResult } from './registry';
+import type { JsonSchema } from './wire';
+import { NO_ARGS } from './wire';
+
+/** Scopes the dev server gates on. A token carries a subset; the rest is invisible. */
+export const DEV_SCOPES = {
+  read: 'dev:read',
+  test: 'dev:test',
+  logs: 'dev:logs',
+  dbRead: 'db:read',
+  dbMigrate: 'db:migrate',
+} as const;
+
+export interface TestRun {
+  readonly passed: number;
+  readonly failed: number;
+  readonly skipped: number;
+  readonly durationMs: number;
+  readonly failures: readonly { readonly test: string; readonly message: string }[];
+}
+
+export interface MigrateResult {
+  readonly branch: string;
+  readonly applied: readonly string[];
+  readonly pending: readonly string[];
+}
+
+export interface QueueDepth {
+  readonly queue: string;
+  readonly pending: number;
+  readonly running: number;
+  readonly failed: number;
+}
+
+export interface ErrorExplanation {
+  readonly code: string;
+  readonly cause: string;
+  readonly fix: string;
+  readonly docs: string;
+}
+
+export interface VerifyStep {
+  readonly name: string;
+  readonly ok: boolean;
+  readonly detail?: string;
+}
+
+export interface VerifyResult {
+  readonly ok: boolean;
+  readonly steps: readonly VerifyStep[];
+}
+
+/** Description sources. Satisfied by `frameworkIntrospection` in a real app. */
+export interface DevIntrospection {
+  routes(): unknown;
+  entities(): unknown;
+  actions(): unknown;
+  queries(): unknown;
+  policies(): unknown;
+  jobs(): unknown;
+  jobInspect(name: string): unknown;
+}
+
+/** Shell-side capabilities. Satisfied by the CLI, which owns the process and the DB. */
+export interface DevCapabilities {
+  readonly database: DatabaseTarget;
+  /**
+   * Run one already-parsed read-only statement under layers 1–2 (a SELECT-only role, a
+   * `BEGIN READ ONLY` transaction, `limits.timeoutMs`) and return at most `limits.maxRows + 1`
+   * rows — the extra row is how the tool tells `truncated` without a second count query.
+   */
+  runQuery(sql: string, limits: QueryLimits): Promise<QueryRows>;
+  runMigrations(branch: string, dryRun: boolean): Promise<MigrateResult>;
+  queueDepth(): Promise<readonly QueueDepth[]>;
+  runTests(filter: string | undefined): Promise<TestRun>;
+  tailLogs(lines: number, role: string | undefined): Promise<readonly string[]>;
+  readManifest(): Promise<string>;
+  explainError(code: string): ErrorExplanation | undefined;
+  verify(fix: boolean): Promise<VerifyResult>;
+}
+
+export type DevHost = DevIntrospection & DevCapabilities;
+
+const NAME_ARG: JsonSchema = {
+  type: 'object',
+  properties: { name: { type: 'string', description: 'Job name from jobs.inspect with no name.' } },
+  additionalProperties: false,
+};
+
+/** Every dev tool, in one array so `x mcp serve` and the HTTP transport share the catalog. */
+export function devTools(host: DevHost): readonly AnyMcpTool[] {
+  return [
+    read(
+      'routes.list',
+      'Route table: url, render mode, offline strategy, hydrate, budget.',
+      NO_ARGS,
+      () => jsonResult(host.routes()),
+    ),
+
+    read('schema.describe', 'Entities with columns, types and invariants.', NO_ARGS, () =>
+      jsonResult(host.entities()),
+    ),
+
+    read(
+      'policies.list',
+      'Every policy: permission, subject, and where it is enforced.',
+      NO_ARGS,
+      () => jsonResult(host.policies()),
+    ),
+
+    read(
+      'actions.describe',
+      'Every action and query: input/output schema, policy, cache tags, MCP exposure.',
+      NO_ARGS,
+      () => jsonResult({ actions: host.actions(), queries: host.queries() }),
+    ),
+
+    read(
+      'jobs.inspect',
+      'Job definitions, retry policy and steps. Omit name for all jobs.',
+      NAME_ARG,
+      (args) => {
+        const name = args['name'];
+        return jsonResult(typeof name === 'string' ? host.jobInspect(name) : host.jobs());
+      },
+    ),
+
+    read('queue.depth', 'Pending, running and failed counts per queue.', NO_ARGS, async () =>
+      jsonResult(await host.queueDepth()),
+    ),
+
+    read('manifest.read', 'The generated x.manifest.json as text.', NO_ARGS, async () =>
+      textResult(await host.readManifest()),
+    ),
+
+    read(
+      'errors.explain',
+      'Explain a stable X_* error code: cause, exact fix command, docs link.',
+      {
+        type: 'object',
+        properties: { code: { type: 'string', description: 'e.g. X_DB_DRIFT' } },
+        required: ['code'],
+        additionalProperties: false,
+      },
+      (args) => {
+        const code = String(args['code']);
+        const explanation = host.explainError(code);
+        return explanation === undefined
+          ? textResult(`unknown error code: ${code}`, true)
+          : jsonResult(explanation);
+      },
+    ),
+
+    // ── gated: reads real data ────────────────────────────────────────────────
+    {
+      name: 'db.query',
+      description:
+        'Run ONE read-only SQL statement. Writes, multiple statements, locking clauses ' +
+        'and data-modifying CTEs are refused (X_MCP_QUERY_REJECTED), not merely discouraged. ' +
+        `Runs as a SELECT-only role in a READ ONLY transaction, capped at ${QUERY_LIMITS.maxRows} ` +
+        `rows, ${QUERY_LIMITS.maxBytes} bytes and ${QUERY_LIMITS.timeoutMs}ms; the answer's ` +
+        '`guards` names the defences that engaged and `truncatedBy` names any cap that bit.',
+      scope: DEV_SCOPES.dbRead,
+      destructive: false,
+      inputSchema: {
+        type: 'object',
+        properties: {
+          sql: { type: 'string', description: 'One SELECT/WITH/EXPLAIN/SHOW statement.' },
+          limit: {
+            type: 'integer',
+            minimum: 1,
+            maximum: QUERY_LIMITS.maxRows,
+            default: DEFAULT_QUERY_ROWS,
+          },
+        },
+        required: ['sql'],
+        additionalProperties: false,
+      },
+      async handle(args: ToolArgs) {
+        // Layer 3, here, before the host ever sees the string; layers 1–2 in the host; layer 4
+        // on the way out. The caps run in this handler rather than in the host because a host
+        // that forgets them is a host that answers a million rows into a model's context.
+        const statement = assertReadOnlyQuery(String(args['sql']));
+        const limits = resolveQueryLimits(args['limit']);
+        const rows = await host.runQuery(statement, limits);
+        return jsonResult(capQueryRows({ ...rows, guards: [PARSE_GUARD, ...rows.guards] }, limits));
+      },
+    },
+
+    // ── gated: changes state ──────────────────────────────────────────────────
+    {
+      name: 'db.migrate',
+      description:
+        'Apply pending migrations to the current BRANCH database. Refuses a production or ' +
+        'non-branch target (X_MCP_NOT_BRANCH_DB). Use ROLE=migrate to deploy.',
+      scope: DEV_SCOPES.dbMigrate,
+      destructive: true,
+      inputSchema: {
+        type: 'object',
+        properties: {
+          dryRun: { type: 'boolean', default: false, description: 'Plan only, apply nothing.' },
+        },
+        additionalProperties: false,
+      },
+      async handle(args: ToolArgs) {
+        const branch = assertBranchDatabase(host.database);
+        const dryRun = args['dryRun'] === true;
+        return jsonResult(await host.runMigrations(branch, dryRun));
+      },
+    },
+    {
+      name: 'tests.run',
+      description: 'Run the test suite (executes project code). Optional substring filter.',
+      scope: DEV_SCOPES.test,
+      destructive: true,
+      inputSchema: {
+        type: 'object',
+        properties: { filter: { type: 'string', description: 'Substring match on test path.' } },
+        additionalProperties: false,
+      },
+      async handle(args: ToolArgs) {
+        const filter = typeof args['filter'] === 'string' ? args['filter'] : undefined;
+        const run = await host.runTests(filter);
+        return { ...jsonResult(run), ...(run.failed > 0 ? { isError: true } : {}) };
+      },
+    },
+    {
+      name: 'verify.run',
+      description:
+        'Run x verify: types, lint, boundaries, migrations, manifest drift, tests, budgets. ' +
+        'This is the shippable contract. `fix: true` applies safe autofixes.',
+      scope: DEV_SCOPES.test,
+      destructive: true,
+      inputSchema: {
+        type: 'object',
+        properties: { fix: { type: 'boolean', default: false } },
+        additionalProperties: false,
+      },
+      async handle(args: ToolArgs) {
+        const result = await host.verify(args['fix'] === true);
+        return { ...jsonResult(result), ...(result.ok ? {} : { isError: true }) };
+      },
+    },
+    {
+      name: 'logs.tail',
+      description: 'Last N log lines, optionally for one runtime role (web/sync/worker/...).',
+      scope: DEV_SCOPES.logs,
+      destructive: false,
+      inputSchema: {
+        type: 'object',
+        properties: {
+          lines: { type: 'integer', minimum: 1, maximum: 2000, default: 100 },
+          role: {
+            type: 'string',
+            enum: ['web', 'sync', 'worker', 'scheduler', 'migrate', 'replicator'],
+          },
+        },
+        additionalProperties: false,
+      },
+      async handle(args: ToolArgs) {
+        const lines = typeof args['lines'] === 'number' ? args['lines'] : 100;
+        const role = typeof args['role'] === 'string' ? args['role'] : undefined;
+        return textResult((await host.tailLogs(lines, role)).join('\n'));
+      },
+    },
+  ];
+}
+
+/** Shorthand for the introspection tools: `dev:read`, non-destructive, no role filter. */
+function read(
+  name: string,
+  description: string,
+  inputSchema: JsonSchema,
+  handle: (args: ToolArgs) => Promise<McpToolResult> | McpToolResult,
+): AnyMcpTool {
+  return {
+    name,
+    description,
+    inputSchema,
+    scope: DEV_SCOPES.read,
+    destructive: false,
+    async handle(args: ToolArgs) {
+      return await handle(args);
+    },
+  };
+}

package/src/errors.ts

@@ -0,0 +1,245 @@
+// The X_* codes owned by @ultimat3/mcp. Each carries the exact next command, because the
+// caller reading it is usually an agent with no human to ask.
+
+import { registerErrorCodes, UltimateError } from '@ultimat3/core';
+
+export const MCP_ERROR_CODES = [
+  'X_MCP_TOOL_UNKNOWN',
+  'X_MCP_SCOPE_DENIED',
+  'X_MCP_ARGS_INVALID',
+  'X_MCP_PROTOCOL',
+  'X_MCP_QUERY_REJECTED',
+  'X_MCP_NOT_BRANCH_DB',
+  'X_MCP_TOOL_UNSAFE',
+  'X_MCP_TOOL_UNDECLARED',
+  'X_MCP_TOOL_DUPLICATE',
+  'X_MCP_SCOPE_UNKNOWN',
+  'X_MCP_SCOPE_CONFLICT',
+] as const;
+
+export type McpErrorCode = (typeof MCP_ERROR_CODES)[number];
+
+export const MCP_ERROR_TITLES: Readonly<Record<McpErrorCode, string>> = {
+  X_MCP_TOOL_UNKNOWN: 'no such tool for this caller',
+  X_MCP_SCOPE_DENIED: "the connection's token does not carry the tool's scope",
+  X_MCP_ARGS_INVALID: 'tool arguments failed the input schema',
+  X_MCP_PROTOCOL: 'the MCP handshake or auth is wrong',
+  X_MCP_QUERY_REJECTED: 'db.query was not given one read-only statement',
+  X_MCP_NOT_BRANCH_DB: 'db.migrate was aimed at a database that is not a branch',
+  X_MCP_TOOL_UNSAFE: 'an MCP tool declares no policy',
+  X_MCP_TOOL_UNDECLARED: 'defineAppMcp lists a primitive that declares no MCP exposure',
+  X_MCP_TOOL_DUPLICATE: 'two primitives project to one MCP tool name',
+  X_MCP_SCOPE_UNKNOWN: 'defineAppMcp scopes a tool this server does not project',
+  X_MCP_SCOPE_CONFLICT: 'two scopes claim one MCP tool',
+};
+
+// Titles must be registered for `format()` to render the contract's first line. Every code above is
+// owned here and none is borrowed, so the call is unconditional: a second package claiming one has
+// to fail as X_ERROR_CODE_DUPLICATE, not quietly keep whichever title was registered first.
+registerErrorCodes(
+  Object.fromEntries(Object.entries(MCP_ERROR_TITLES).map(([code, title]) => [code, { title }])),
+);
+
+const docsFor = (code: McpErrorCode): string => `https://ultimate.dev/errors/${code}`;
+
+/**
+ * OUTCOME 1 of three: a tool name reached the dispatcher that no VISIBLE tool answers to —
+ * the tool is absent, or it exists and this caller's role may never invoke it. One error for
+ * both, on purpose. Thrown by in-process callers; over the wire the same condition is
+ * `-32601` with the same message, so a role-hidden tool is indistinguishable from an absent
+ * one even for a caller holding every scope in the system.
+ */
+export class McpToolUnknownError extends UltimateError {
+  constructor(input: { name: string; visible: readonly string[] }) {
+    super({
+      code: 'X_MCP_TOOL_UNKNOWN',
+      cause: `no MCP tool named "${input.name}" is visible to this caller (visible: ${
+        input.visible.length > 0 ? input.visible.join(', ') : 'none'
+      })`,
+      fix: 'call tools/list to read the catalog this caller may use',
+      docs: docsFor('X_MCP_TOOL_UNKNOWN'),
+    });
+  }
+}
+
+/**
+ * OUTCOME 2 of three: the caller may SEE the tool, but the connection's token does not carry
+ * its scope. Named out loud rather than hidden — the caller can legitimately fix this, and
+ * hiding it would strand a well-behaved client. Scope belongs to the token, not to the
+ * actor's permissions: granting it takes effect on the next connection, not this one.
+ */
+export class McpScopeDeniedError extends UltimateError {
+  readonly scope: string;
+
+  constructor(input: { name: string; scope: string }) {
+    super({
+      code: 'X_MCP_SCOPE_DENIED',
+      cause: `tool "${input.name}" requires scope "${input.scope}", which this connection's token does not carry`,
+      fix: `x token grant ${input.scope}   # then reconnect: scopes are fixed for the life of a connection`,
+      docs: docsFor('X_MCP_SCOPE_DENIED'),
+    });
+    this.scope = input.scope;
+  }
+}
+
+/** Arguments failed the tool's declared JSON Schema — the schema the agent was handed. */
+export class McpArgsInvalidError extends UltimateError {
+  constructor(input: { name: string; issues: readonly string[] }) {
+    super({
+      code: 'X_MCP_ARGS_INVALID',
+      cause: `arguments for "${input.name}" are invalid: ${input.issues.join('; ')}`,
+      fix: `re-read the tool's inputSchema from tools/list and resend`,
+      docs: docsFor('X_MCP_ARGS_INVALID'),
+    });
+  }
+}
+
+/**
+ * A hand-written tool reached `defineAppMcp` with no policy. Boot-time, because a server that
+ * starts and then refuses every call is indistinguishable from one that is merely broken —
+ * and a tool that starts and then allows every call is a second door into the data.
+ */
+export class McpToolUnsafeError extends UltimateError {
+  constructor(input: { name: string }) {
+    super({
+      code: 'X_MCP_TOOL_UNSAFE',
+      cause: `tool "${input.name}" declares no policy; an unguarded tool is a second door into the data`,
+      fix: `add policy: '<resource>:<verb>' to the tool, reusing the permission its action uses`,
+      docs: docsFor('X_MCP_TOOL_UNSAFE'),
+    });
+  }
+}
+
+/**
+ * A primitive was NAMED in `defineAppMcp`'s `actions`/`queries` but never declared
+ * `mcp: { expose: true }`. Naming it there is the request to expose it, so the only two honest
+ * answers are "project it" and "refuse": filtering it out silently ships a catalog missing a tool
+ * its author believes is in it, and nothing fails until an agent asks for a tool that is not
+ * there. Boot-time, with every offender named at once so one edit closes all of them.
+ *
+ * `include: 'exposed'` sweeps the registries and therefore DOES filter — that list is every
+ * primitive the app registered, not a list anyone wrote out.
+ */
+export class McpToolUndeclaredError extends UltimateError {
+  /** The offending primitive names, so a caller can report them without re-parsing `cause`. */
+  readonly names: readonly string[];
+
+  constructor(input: { names: readonly string[] }) {
+    const names = input.names.join(', ');
+    super({
+      code: 'X_MCP_TOOL_UNDECLARED',
+      cause: `listed in defineAppMcp but never declared mcp.expose: ${names}`,
+      fix:
+        "add mcp: { expose: true, description: '<what it does>' } beside the policy on each — " +
+        "or drop it from the list and let include: 'exposed' project what opted in",
+      docs: docsFor('X_MCP_TOOL_UNDECLARED'),
+    });
+    this.names = input.names;
+  }
+}
+
+/**
+ * Two primitives project to one tool name. Caught at boot rather than at first call: an agent
+ * 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.
+ */
+export class McpToolDuplicateError extends UltimateError {
+  constructor(input: { name: string }) {
+    super({
+      code: 'X_MCP_TOOL_DUPLICATE',
+      cause: `two primitives project to the MCP tool "${input.name}"`,
+      fix: "rename one: the tool name is the primitive's export name, or the `tools` record key",
+      docs: docsFor('X_MCP_TOOL_DUPLICATE'),
+    });
+  }
+}
+
+/**
+ * `defineAppMcp`'s `scopes:` names a tool the server does not project. Boot-time and loud:
+ * the alternative is a scope entry that quietly covers nothing, leaving the tool the author
+ * meant to gate reachable by every connection — a gate that reads as declared and never runs.
+ * The projected names travel with it, because the usual cause is a rename or a typo.
+ */
+export class McpScopeUnknownError extends UltimateError {
+  /** The catalog as projected, so a caller can show it without re-parsing `cause`. */
+  readonly projected: readonly string[];
+
+  constructor(input: { scope: string; name: string; projected: readonly string[] }) {
+    const projected = input.projected.length > 0 ? input.projected.join(', ') : 'nothing';
+    super({
+      code: 'X_MCP_SCOPE_UNKNOWN',
+      cause: `scopes["${input.scope}"] names "${input.name}", which this server does not project (projected: ${projected})`,
+      fix: `in defineAppMcp, spell it as one of the projected names above — or drop "${input.name}" from scopes["${input.scope}"]`,
+      docs: docsFor('X_MCP_SCOPE_UNKNOWN'),
+    });
+    this.projected = input.projected;
+  }
+}
+
+/**
+ * Two scopes claim one tool. A tool carries ONE scope, so the second claim would either
+ * overwrite the first or be dropped — decided by object key order, which is not a security
+ * model. Refused at boot rather than resolved, because either resolution is a guess about
+ * which capability the author meant a token to need.
+ *
+ * The two claimants travel with it, as `McpScopeUnknownError` carries the projected catalog: the
+ * reader is usually an agent holding `--json`, and a sentence is not a field.
+ */
+export class McpScopeConflictError extends UltimateError {
+  /** The two scopes that claimed the tool, in the order the map declared them. */
+  readonly scopes: readonly [string, string];
+
+  constructor(input: { name: string; scopes: readonly [string, string] }) {
+    super({
+      code: 'X_MCP_SCOPE_CONFLICT',
+      cause: `tool "${input.name}" is claimed by two scopes ("${input.scopes[0]}" and "${input.scopes[1]}"); a tool carries one`,
+      fix: `in defineAppMcp, keep "${input.name}" under the single scope a token must hold for it, and remove the other entry`,
+      docs: docsFor('X_MCP_SCOPE_CONFLICT'),
+    });
+    this.scopes = input.scopes;
+  }
+}
+
+/** A malformed envelope or an unsupported method — a client bug, not an authz outcome. */
+export class McpProtocolError extends UltimateError {
+  constructor(input: { cause: string; fix?: string }) {
+    super({
+      code: 'X_MCP_PROTOCOL',
+      cause: input.cause,
+      fix: input.fix ?? `send a JSON-RPC 2.0 body: { jsonrpc: '2.0', id, method, params }`,
+      docs: docsFor('X_MCP_PROTOCOL'),
+    });
+  }
+}
+
+/**
+ * LAYER 3 of `db.query`'s four defences: the statement is not one read-only statement, so it
+ * never reaches the server. Separate from the migration refusal below because the two want
+ * different next commands, and a code that covers both tells the agent neither.
+ */
+export class McpQueryRejectedError extends UltimateError {
+  constructor(input: { cause: string; fix: string }) {
+    super({
+      code: 'X_MCP_QUERY_REJECTED',
+      cause: `db.query refused: ${input.cause}`,
+      fix: input.fix,
+      docs: docsFor('X_MCP_QUERY_REJECTED'),
+    });
+  }
+}
+
+/**
+ * `db.migrate` was pointed at a database that is not a branch. Enforced, not documented — the
+ * dev server holds real credentials, and a migration is the one dev tool that cannot be undone
+ * by reading the error afterwards.
+ */
+export class McpNotBranchDbError extends UltimateError {
+  constructor(input: { cause: string; fix: string }) {
+    super({
+      code: 'X_MCP_NOT_BRANCH_DB',
+      cause: `db.migrate refused: ${input.cause}`,
+      fix: input.fix,
+      docs: docsFor('X_MCP_NOT_BRANCH_DB'),
+    });
+  }
+}

package/src/exposed.ts

@@ -0,0 +1,25 @@
+// `include: 'exposed'` — project straight from the primitive registries.
+//
+// "Define once, project everywhere". The action and query registries already know which
+// primitives declared `mcp: { expose: true }`; re-listing them in `defineAppMcp` copies that
+// knowledge into a second place, and a copy is a thing that goes stale silently — an action
+// gains `expose`, its tool never appears, and nothing fails.
+//
+// The adaptation itself lives in `projectable.ts`, shared verbatim with the written-out
+// `actions:`/`queries:` list, so both routes run through `invoke` / `sourceFor` and the registry
+// shortcut buys convenience while changing no execution path.
+
+import { listActions } from '@ultimat3/action';
+import { listQueries } from '@ultimat3/query';
+import type { ProjectablePrimitive } from './from-action';
+import { primitiveFromAction, primitiveFromQuery } from './projectable';
+
+/**
+ * Every registered action and query, as projectable primitives. `toolsFrom` applies the opt-in
+ * filter, so this deliberately does NOT filter: one place decides what "exposed" means.
+ *
+ * Read eagerly, at the moment `defineAppMcp` runs — register the app's primitives first.
+ */
+export function exposedPrimitives(): readonly ProjectablePrimitive[] {
+  return [...listActions().map(primitiveFromAction), ...listQueries().map(primitiveFromQuery)];
+}