@ultimat3/mcp 1.0.0

package/src/from-action.ts

@@ -0,0 +1,123 @@
+// The free-tool projection: an `action` (or `query`) with `mcp.expose` becomes an MCP tool
+// at zero authorization cost.
+//
+// The whole claim rests on one line in `handle` below: the tool calls `action.run(...)` —
+// the SAME entry point the HTTP route calls. Policy evaluation lives inside `run`, so
+// there is nothing here to keep in sync and no second authz system to drift. This
+// projection therefore INVENTS no `scope`: a scope is a capability of the connection's
+// token, which a projection cannot know anything about. An app that wants one names the
+// tool in `defineAppMcp`'s `scopes:` map (see `scopes.ts`) — declared once, next to the
+// other tools that same token capability covers, never guessed from the action.
+//
+// `toMcpTool` in @ultimat3/action owns the schema half of the projection (input schema →
+// JSON Schema); this file owns the execution half.
+
+import type { Actor } from '@ultimat3/core';
+import { McpToolUndeclaredError } from './errors';
+import type { AnyMcpTool, McpCaller, McpRole, McpToolResult, ToolArgs } from './registry';
+import { jsonResult } from './registry';
+import type { JsonSchema } from './wire';
+import { NO_ARGS } from './wire';
+
+/**
+ * MCP exposure as declared on an action/query (`mcp: { expose: true, description }`).
+ * `visibleTo` restricts which roles may enumerate the tool; it is a catalog concern, not
+ * an authz one — the policy still decides.
+ */
+export interface McpExposure {
+  readonly expose?: boolean;
+  /**
+   * Contract text, not UI text: the same string is the OpenAPI operation `summary`, and
+   * `buildOpenApi`'s bytes are what `x verify` diffs. Routing it through the ambient,
+   * request-scoped `t()` would make that artifact locale-dependent — see
+   * `ActionMcp.description` in @ultimat3/action.
+   */
+  readonly description?: string;
+  readonly visibleTo?: readonly McpRole[];
+  /** Override the projected tool name. Defaults to the primitive's own name. */
+  readonly name?: string;
+}
+
+/**
+ * The surface this projection needs from a primitive. Structurally satisfied by `Action`
+ * and by `query`'s runnable handle from @ultimat3/action / @ultimat3/query — restated here
+ * (rather than imported as a generic) so the projection is testable with a fake and does
+ * not bind to either package's type parameters.
+ */
+export interface ProjectablePrimitive {
+  readonly name: string;
+  readonly description?: string;
+  readonly mcp?: McpExposure;
+  /** JSON Schema of the input, as produced by `toMcpTool`. */
+  readonly inputJsonSchema?: JsonSchema;
+  /** True for a mutation. Drives the rate-limit bucket; queries set it false. */
+  readonly mutates?: boolean;
+  /** The one server-authoritative entry point. Runs policy, then the handler. */
+  run(args: { input: unknown; actor: Actor }): Promise<unknown>;
+}
+
+/** True when the primitive opted into MCP. Opt-in, never opt-out: silence exposes nothing. */
+export function isExposed(primitive: ProjectablePrimitive): boolean {
+  return primitive.mcp?.expose === true;
+}
+
+/**
+ * Project one primitive. Throws nothing, and does not re-check exposure: the two list
+ * projections below decide what an un-exposed primitive means — skip it, or refuse it.
+ */
+export function toolFromAction(primitive: ProjectablePrimitive): AnyMcpTool {
+  const name = primitive.mcp?.name ?? primitive.name;
+  const description =
+    primitive.mcp?.description ?? primitive.description ?? `Run the "${primitive.name}" action.`;
+  const mutates = primitive.mutates ?? true;
+  const visibleTo = primitive.mcp?.visibleTo;
+
+  return {
+    name,
+    description,
+    inputSchema: primitive.inputJsonSchema ?? NO_ARGS,
+    destructive: mutates,
+    ...(visibleTo !== undefined ? { visibleTo } : {}),
+    // No `scope` from here: see the header. `defineAppMcp`'s `scopes:` map may add one.
+    async handle(args: ToolArgs, caller: McpCaller): Promise<McpToolResult> {
+      // ONE authz system, TWO surfaces. HTTP does exactly this call with an actor of
+      // kind 'user'; MCP does it with kind 'agent'. Same policy, same decision.
+      const output = await primitive.run({ input: args, actor: caller.actor });
+      return jsonResult(output);
+    },
+  };
+}
+
+/** Alias that reads correctly at a query call site — same projection, same guarantees. */
+export const toolFromQuery = toolFromAction;
+
+/**
+ * Project every exposed primitive, SKIPPING the rest. Stable name order.
+ *
+ * For a swept list — every primitive the registries hold — where the un-exposed ones are the
+ * normal case and dropping them is the whole job. A list the author wrote out by hand goes
+ * through `toolsListed`, which refuses instead.
+ */
+export function toolsFrom(primitives: readonly ProjectablePrimitive[]): readonly AnyMcpTool[] {
+  return primitives
+    .filter(isExposed)
+    .map(toolFromAction)
+    .sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+}
+
+/**
+ * Project a list the AUTHOR wrote out, REFUSING any primitive that never opted in.
+ *
+ * Naming a primitive in `defineAppMcp` is the request to expose it, so silence there is a
+ * contradiction rather than an opt-out — and a silently dropped entry ships a server whose
+ * catalog is missing a tool its author believes is in it. Every offender is collected before
+ * throwing so one edit closes all of them.
+ */
+export function toolsListed(primitives: readonly ProjectablePrimitive[]): readonly AnyMcpTool[] {
+  const undeclared = primitives.filter((primitive) => !isExposed(primitive));
+  if (undeclared.length > 0) {
+    // The primitive's own name, not `mcp.name`: it is what the author greps for.
+    throw new McpToolUndeclaredError({ names: undeclared.map((primitive) => primitive.name) });
+  }
+  return toolsFrom(primitives);
+}

package/src/index.ts

@@ -0,0 +1,133 @@
+// Public API of @ultimat3/mcp. Explicit — nothing is re-exported by wildcard, so the
+// surface an app or an agent can reach is exactly this list.
+
+/** Re-exported so a `defineAppMcp` file needs one import, not two. Same object as schema's. */
+export type { Infer } from '@ultimat3/schema';
+export { formatIssues, t } from '@ultimat3/schema';
+export type {
+  AnyAppToolDefinition,
+  AppToolArgs,
+  AppToolDefinition,
+  AppTools,
+} from './app-tool';
+export { appToolPrimitive, appToolPrimitives } from './app-tool';
+export type { AppMcp, AppToolSchemas, DefineAppMcpInput } from './app-tools';
+export { defineAppMcp } from './app-tools';
+export type { McpAuditEntry, McpOutcome } from './audit';
+export { auditToolCall, outcomeForCode } from './audit';
+export type { CreateDevServerInput } from './dev-host';
+export { createDevServer, devHost, frameworkIntrospection } from './dev-host';
+export type {
+  DevCapabilities,
+  DevHost,
+  DevIntrospection,
+  ErrorExplanation,
+  MigrateResult,
+  QueueDepth,
+  TestRun,
+  VerifyResult,
+  VerifyStep,
+} from './dev-server';
+export { DEV_SCOPES, devTools } from './dev-server';
+export type { McpErrorCode } from './errors';
+export {
+  MCP_ERROR_CODES,
+  MCP_ERROR_TITLES,
+  McpArgsInvalidError,
+  McpNotBranchDbError,
+  McpProtocolError,
+  McpQueryRejectedError,
+  McpScopeConflictError,
+  McpScopeDeniedError,
+  McpScopeUnknownError,
+  McpToolDuplicateError,
+  McpToolUndeclaredError,
+  McpToolUnknownError,
+  McpToolUnsafeError,
+} from './errors';
+export { exposedPrimitives } from './exposed';
+export type { McpExposure, ProjectablePrimitive } from './from-action';
+export {
+  isExposed,
+  toolFromAction,
+  toolFromQuery,
+  toolsFrom,
+  toolsListed,
+} from './from-action';
+export { toWireSchema } from './input-schema';
+export type { ListedPrimitive } from './projectable';
+export { asProjectable } from './projectable';
+export type { QueryLimits, QueryResult, QueryRows } from './query-limits';
+export {
+  capQueryRows,
+  DEFAULT_QUERY_ROWS,
+  QUERY_LIMITS,
+  resolveQueryLimits,
+} from './query-limits';
+export type { DatabaseTarget } from './readonly-sql';
+export { assertBranchDatabase, assertReadOnlyQuery, PARSE_GUARD } from './readonly-sql';
+export type {
+  AnyMcpTool,
+  ContentBlock,
+  McpCaller,
+  McpRole,
+  McpTool,
+  McpToolResult,
+  McpVerbClass,
+  McpVisibility,
+  ToolArgs,
+  ToolListEntry,
+  ToolResolution,
+} from './registry';
+export { jsonResult, ToolRegistry, textResult, visibleToCaller } from './registry';
+export type {
+  FrameworkResourceProviders,
+  McpPrompt,
+  McpPromptArgument,
+  McpResource,
+  ResourceContents,
+  ResourceListEntry,
+} from './resources';
+export {
+  frameworkResources,
+  promptFromPath,
+  RESOURCE_URIS,
+  ResourceRegistry,
+  toPrompts,
+  URI_ARG_SCHEMA,
+} from './resources';
+export type { McpScopes } from './scopes';
+export { withScopes } from './scopes';
+export type { CreateMcpServerInput } from './server';
+export { createMcpServer, McpServer } from './server';
+export type {
+  McpHttpTransportInput,
+  McpRouteDescriptor,
+  ResolvedToken,
+} from './transport-http';
+export { bearerToken, isAgentActor, MCP_RATE_LIMITS, mcpHttpRoute } from './transport-http';
+export type { StdioTransportInput } from './transport-stdio';
+export { serveStdio } from './transport-stdio';
+export type { ArgIssue, ArgValidation } from './validate-args';
+export { validateArgs } from './validate-args';
+export type {
+  JsonRpcError,
+  JsonRpcId,
+  JsonRpcRequest,
+  JsonRpcResponse,
+  JsonSchema,
+  ServerInfo,
+} from './wire';
+export {
+  DEFAULT_SERVER_INFO,
+  errorResponse,
+  INTERNAL_ERROR,
+  INVALID_PARAMS,
+  INVALID_REQUEST,
+  isJsonRpcRequest,
+  MCP_PROTOCOL_VERSION,
+  METHOD_NOT_FOUND,
+  NO_ARGS,
+  PARSE_ERROR,
+  resultResponse,
+} from './wire';

package/src/input-schema.ts

@@ -0,0 +1,59 @@
+// A Standard Schema (`t.object({...})`, Zod, Valibot) -> the JSON Schema subset the wire speaks.
+//
+// Two `JsonSchema` types exist on purpose. `@ultimat3/schema` emits the full draft-07 vocabulary;
+// `wire.ts` declares the narrow subset `validate-args.ts` can actually ENFORCE. Handing an agent a
+// keyword the server ignores is worse than omitting it — the agent obeys a rule nothing checks and
+// gets a silent pass. So this is a real projection, not a cast: a keyword outside the subset is
+// dropped here, and `tools/list` publishes only what the resolver will hold a call to.
+
+import type { JsonSchema as RichJsonSchema } from '@ultimat3/schema';
+import { toMcpInputSchema } from '@ultimat3/schema';
+import type { JsonSchema } from './wire';
+
+/** Introspect any Standard Schema and narrow the result to the wire subset. */
+export function toWireSchema(schema: unknown): JsonSchema {
+  return narrow(toMcpInputSchema(schema));
+}
+
+function narrow(source: RichJsonSchema): JsonSchema {
+  // exactOptionalPropertyTypes: every field is attached only when it is present, never as
+  // an explicit `undefined` — `tools/list` serialises this object verbatim.
+  return {
+    ...(source.type === undefined ? {} : { type: source.type }),
+    ...(source.title === undefined ? {} : { title: source.title }),
+    ...(source.description === undefined ? {} : { description: source.description }),
+    ...(source.properties === undefined ? {} : { properties: narrowProperties(source.properties) }),
+    ...(source.required === undefined ? {} : { required: source.required }),
+    ...narrowAdditional(source.additionalProperties),
+    ...(source.items === undefined ? {} : { items: narrow(source.items) }),
+    ...(source.enum === undefined ? {} : { enum: source.enum }),
+    ...(source.const === undefined ? {} : { const: source.const }),
+    ...(source.default === undefined ? {} : { default: source.default }),
+    ...(source.format === undefined ? {} : { format: source.format }),
+    ...(source.minimum === undefined ? {} : { minimum: source.minimum }),
+    ...(source.maximum === undefined ? {} : { maximum: source.maximum }),
+    ...(source.minLength === undefined ? {} : { minLength: source.minLength }),
+    ...(source.maxLength === undefined ? {} : { maxLength: source.maxLength }),
+    ...(source.anyOf === undefined ? {} : { anyOf: source.anyOf.map(narrow) }),
+  };
+}
+
+function narrowProperties(
+  properties: Readonly<Record<string, RichJsonSchema>>,
+): Readonly<Record<string, JsonSchema>> {
+  const out: Record<string, JsonSchema> = {};
+  for (const [key, child] of Object.entries(properties)) out[key] = narrow(child);
+  return out;
+}
+
+/**
+ * A record schema says "extra keys, shaped like this". The wire subset can only say yes or no,
+ * and `validate-args.ts` reads `false` as "reject unknown keys" — so an unrepresentable value
+ * schema becomes `true` (permit) rather than a rejection the agent was never warned about.
+ */
+function narrowAdditional(value: boolean | RichJsonSchema | undefined): {
+  readonly additionalProperties?: boolean;
+} {
+  if (value === undefined) return {};
+  return { additionalProperties: typeof value === 'boolean' ? value : true };
+}

package/src/projectable.ts

@@ -0,0 +1,99 @@
+// A real `action` or `query` → the `ProjectablePrimitive` this package projects.
+//
+// ONE adapter, two callers — the registry sweep and the written-out list — so writing a
+// primitive out is a different way to NAME a tool, never a second way to run one.
+
+import type { AnyAction } from '@ultimat3/action';
+import { actionName, invoke, isAction } from '@ultimat3/action';
+import { withChildContext } from '@ultimat3/core';
+import type { AnyQuery } from '@ultimat3/query';
+import { isQuery, queryName, sourceFor } from '@ultimat3/query';
+import type { McpExposure, ProjectablePrimitive } from './from-action';
+import { toWireSchema } from './input-schema';
+
+/**
+ * What `defineAppMcp`'s `actions:`/`queries:` accept.
+ *
+ * The real primitives come first because they are what an app writes: `actions: [publishPost]`.
+ * Until 2026-08 this list took `ProjectablePrimitive` alone, which no `action()` or `query()`
+ * structurally satisfies — they carry `as`/`tool`, never `run` — so the only value that could
+ * reach `X_MCP_TOOL_UNDECLARED` was a hand-built fake, and the gate refused nothing an app could
+ * actually declare. `ProjectablePrimitive` stays in the union for surfaces that build their
+ * catalog programmatically (`@ultimat3/admin`) and for tests that project a stand-in.
+ */
+export type ListedPrimitive = AnyAction | AnyQuery | ProjectablePrimitive;
+
+/**
+ * Adapt whatever the author listed.
+ *
+ * `isAction`/`isQuery` are structural against each package's PRIVATE declaration store, so a
+ * look-alike carrying `kind: 'action'` cannot take either branch — it falls through as the
+ * already-projectable object it claims to be, and is projected verbatim.
+ */
+export function asProjectable(listed: ListedPrimitive): ProjectablePrimitive {
+  if (isAction(listed)) return primitiveFromAction(listed);
+  if (isQuery(listed)) return primitiveFromQuery(listed);
+  return listed;
+}
+
+export function primitiveFromAction(target: AnyAction): ProjectablePrimitive {
+  const exposure = exposureOf(target.mcp);
+  return {
+    // Throws `X_ACTION_UNREGISTERED` on an unnamed action rather than projecting a tool called
+    // `''`: a nameless tool is unaddressable by the scope map, by `tools/call`, and by the author.
+    name: actionName(target),
+    ...(exposure === undefined ? {} : { mcp: exposure }),
+    ...(exposure?.description === undefined ? {} : { description: exposure.description }),
+    inputJsonSchema: toWireSchema(target.input),
+    mutates: true,
+    // The actor rides in on the options: `invoke` swaps it inside the one execution path.
+    run: ({ input, actor }) => invoke(target, input, { surface: 'mcp', actor }),
+  };
+}
+
+export function primitiveFromQuery(target: AnyQuery): ProjectablePrimitive {
+  const exposure = exposureOf(target.mcp);
+  return {
+    name: queryName(target),
+    ...(exposure === undefined ? {} : { mcp: exposure }),
+    ...(exposure?.description === undefined ? {} : { description: exposure.description }),
+    inputJsonSchema: toWireSchema(target.input),
+    mutates: false,
+    run: ({ input, actor }) =>
+      withChildContext({ actor }, async () => {
+        // `sourceFor` is the authorized front half of `runQuery` — validate, guard, build —
+        // and is what `live`, `paginate` and `explain` build on too. Executed without the
+        // cache tiers on purpose: an agent diffing two tool calls must be reading the rows,
+        // not a TTL.
+        const source = await sourceFor(target, input);
+        return source.execute();
+      }),
+  };
+}
+
+/**
+ * An action and a query declare MCP exposure with the same fields, so one typed path reads
+ * both. Narrow on purpose: only a literal `expose: true` counts, so nothing is exposed by
+ * accident — an undeclared `mcp` block yields no exposure at all.
+ *
+ * `visibleTo` travels with it, and must: it is OUTCOME 1's only declaration surface for a
+ * projected primitive. Dropping it here — which this function did until 2026-08 — left
+ * `ToolRegistry`'s role gate enforcing a field no action or query could ever set, so every
+ * projected tool was visible to every caller and the first outcome existed only for the
+ * hand-written tools that build their own `McpTool`.
+ */
+function exposureOf(declared: DeclaredMcp | undefined): McpExposure | undefined {
+  if (declared === undefined) return undefined;
+  return {
+    expose: declared.expose === true,
+    ...(declared.description === undefined ? {} : { description: declared.description }),
+    ...(declared.visibleTo === undefined ? {} : { visibleTo: declared.visibleTo }),
+  };
+}
+
+/** `ActionMcp` and `QueryMcp` are the same shape; restating it binds to neither. */
+interface DeclaredMcp {
+  readonly expose: boolean;
+  readonly description?: string;
+  readonly visibleTo?: readonly string[];
+}

package/src/query-limits.ts

@@ -0,0 +1,101 @@
+// LAYER 4 of `db.query`'s four defences: what one agent-authored read may cost, and how much of
+// it may come back. A cap the caller cannot raise, applied where the tool cannot forget it —
+// `limit` is an argument, and an argument is a request, never a permission.
+
+/** The ceilings. Frozen because a cap a caller can widen is a default, not a cap. */
+export interface QueryLimits {
+  /** Hard row ceiling. A larger `limit` argument is clamped, not honoured. */
+  readonly maxRows: number;
+  /** Ceiling on the serialised rows. Rows are cheap; a row of 2 MB of JSONB is not. */
+  readonly maxBytes: number;
+  /** `statement_timeout` for the read. 0 disables. */
+  readonly timeoutMs: number;
+}
+
+export const QUERY_LIMITS: QueryLimits = Object.freeze({
+  maxRows: 1000,
+  // 256 KiB: the result lands in a model's context, and a tool that can fill it has denied the
+  // agent the rest of its turn as surely as any error would.
+  maxBytes: 256 * 1024,
+  timeoutMs: 5_000,
+});
+
+/** What `limit` means when the caller does not send one. Well under the hard ceiling. */
+export const DEFAULT_QUERY_ROWS = 100;
+
+/** What the host hands back: rows plus the database-side defences that engaged. */
+export interface QueryRows {
+  readonly columns: readonly string[];
+  /** One array per row, in `columns` order. Fetch `maxRows + 1` — see `capQueryRows`. */
+  readonly rows: readonly (readonly unknown[])[];
+  /** Guards from layers 1–2. The tool appends its own; nothing is inferred. */
+  readonly guards: readonly string[];
+}
+
+/** What `db.query` answers. Every cap that bit says so; none of them is silent. */
+export interface QueryResult extends QueryRows {
+  readonly rowCount: number;
+  readonly truncated: boolean;
+  /** Which ceiling cut the result short, or `null` when nothing did. */
+  readonly truncatedBy: 'rows' | 'bytes' | null;
+  /** Bytes of JSON actually returned, so the next `limit` can be chosen rather than guessed. */
+  readonly bytes: number;
+}
+
+/**
+ * The ceilings for one call. A `limit` argument may only ever narrow them: below 1 is a typo,
+ * above `maxRows` is a caller who read the schema's `maximum` as a suggestion.
+ */
+export function resolveQueryLimits(requested: unknown): QueryLimits {
+  const asked =
+    typeof requested === 'number' && Number.isFinite(requested)
+      ? Math.trunc(requested)
+      : DEFAULT_QUERY_ROWS;
+  return { ...QUERY_LIMITS, maxRows: Math.max(1, Math.min(QUERY_LIMITS.maxRows, asked)) };
+}
+
+const encoder = new TextEncoder();
+
+/** Serialised size of one row, plus the separator it costs inside the JSON array. */
+function rowBytes(row: readonly unknown[]): number {
+  return encoder.encode(JSON.stringify(row)).length + 1;
+}
+
+/**
+ * Apply the row and byte ceilings and say which one bit.
+ *
+ * The host fetches `maxRows + 1` rows: one row past the ceiling is how `truncated` is known
+ * without a second count query, and it is dropped here.
+ *
+ * A single row larger than `maxBytes` yields zero rows and `truncatedBy: 'bytes'`. Returning it
+ * anyway would make the byte cap a suggestion, and the honest answer tells the agent exactly
+ * what to do next: select fewer columns.
+ */
+export function capQueryRows(source: QueryRows, limits: QueryLimits): QueryResult {
+  const overRows = source.rows.length > limits.maxRows;
+  const kept: (readonly unknown[])[] = [];
+  let bytes = 2; // the enclosing `[]`
+  let overBytes = false;
+
+  for (const row of source.rows.slice(0, limits.maxRows)) {
+    const size = rowBytes(row);
+    if (bytes + size > limits.maxBytes) {
+      overBytes = true;
+      break;
+    }
+    kept.push(row);
+    bytes += size;
+  }
+
+  return {
+    columns: source.columns,
+    rows: kept,
+    rowCount: kept.length,
+    truncated: overRows || overBytes,
+    // Bytes first: it is the ceiling that cut this particular answer short, even when the row
+    // ceiling would also have applied further down.
+    truncatedBy: overBytes ? 'bytes' : overRows ? 'rows' : null,
+    bytes,
+    guards: [...source.guards, `cap:${limits.maxRows} rows`, `cap:${limits.maxBytes} bytes`],
+  };
+}