@antasphere/chassis-server 1.0.0

package/src/jobs/timers.ts

@@ -0,0 +1,287 @@
+import type PgBoss from 'pg-boss';
+import type pg from 'pg';
+import type { Logger } from '../logger.js';
+
+/**
+ * One-off timers (PRDCT-3254): a tool runs a function ONCE at an instant or
+ * after a delay, with a JSON payload, on a queue its `jobs` slot declared.
+ * The runtime is pg-boss, the same durable queue the crons ride: a timer is a
+ * job row with `start_after` in the future, so it lives in the tool's own
+ * Postgres, survives a restart and a redeploy, and is taken by exactly one
+ * worker replica (pg-boss fetches with SKIP LOCKED). Edition-neutral, and an
+ * api-role replica schedules and cancels like any other: neither needs DDL.
+ *
+ * A KEY makes a timer replaceable: at most one PENDING timer per (queue, key).
+ * `schedule` with a key withdraws the pending timer of that key and inserts
+ * the new one in ONE transaction under a per-key advisory lock, so two
+ * replicas re-arming the same thing at once never leave two timers, and
+ * `cancel({ key })` withdraws whatever is pending under it. A timer that is
+ * already RUNNING is neither replaced nor cancelled (its handler is on it;
+ * the handler's own claim decides what it does), so a consumer keeps its
+ * at-most-once guard in the data it writes (meet's claim-before-send stamps),
+ * never in the timer alone. What a replace or a cancel DOES do to a running
+ * timer is take its retries away (`retry_limit = retry_count`): pg-boss's
+ * fail path re-inserts a failed run as a pending `retry` row with the same
+ * key, which would put the withdrawn payload back beside the new one
+ * (verifier round 1, F1). A withdrawn run that throws therefore ends
+ * `failed`, and "one pending per key" holds across the run's failure too.
+ * `cancel` itself runs without the per-key lock: a cancel concurrent with a
+ * replace may answer 0 and leave the replace's fresh timer pending (it ran
+ * first); a consumer that wants "nothing pending" cancels after its last
+ * schedule, as every path does.
+ *
+ * The payload is a plain JSON object (not an array, not a Date, nothing a
+ * `JSON.stringify` refuses): node-postgres serialises anything else into a
+ * value the `jsonb` column refuses with a raw database error, so the check is
+ * made here and answers `invalid_argument` before any statement runs.
+ *
+ * What a timer costs in pg-boss's terms: `keep_until` is `start_after` plus
+ * the queue's retention (fourteen days by default), so a timer months ahead is
+ * not archived before its time; the handler's run is bounded by the queue's
+ * `expireIn` (fifteen minutes by default); a handler that throws fails the
+ * job, retried per `retry` or the queue's own settings (pg-boss's queue
+ * default is two retries with no delay, so a handler that always throws runs
+ * three times back to back), then left `failed`.
+ *
+ * The pending-state SQL reads pg-boss's own `job` table (its schema is
+ * `PGBOSS_SCHEMA`, the column names pg-boss 10's), because pg-boss exposes no
+ * lookup by key; `timers.test.ts` pins the statements against the installed
+ * version. A pg-boss bump re-verifies them.
+ */
+
+/** The pg-boss schema the chassis installs (`createJobs`). */
+export const PGBOSS_SCHEMA = 'pgboss';
+
+/**
+ * Advisory-lock class serializing the replace of a keyed timer, beside the
+ * migration lock (7432001), the last-owner locks (7432002 xact / 7432003
+ * session) and the pg-boss install lock (7432004). Transaction-scoped, two-int
+ * form: the class and `hashtext(queue + US + key)`.
+ */
+export const TIMER_KEY_LOCK_CLASS = 7_432_005;
+
+/** What a handler learns about the run beside its payload. */
+export interface TimerJob {
+  /** pg-boss's job id, the one `schedule` answered. */
+  id: string;
+  queue: string;
+  /** The dedupe key the timer was scheduled with; null without one, and on a cron's run. */
+  key: string | null;
+}
+
+/** When the timer fires: an instant, or a delay from now in seconds. Exactly one. */
+export type TimerWhen = { at: Date; inSeconds?: never } | { inSeconds: number; at?: never };
+
+/** How a failing handler is retried: `limit` more attempts, `delaySeconds` apart (doubled each time with `backoff`). */
+export interface TimerRetry {
+  limit: number;
+  delaySeconds?: number;
+  backoff?: boolean;
+}
+
+export type TimerOptions = TimerWhen & {
+  /** The dedupe key: at most one pending timer per (queue, key); a new schedule under it replaces the pending one. */
+  key?: string;
+  /** Absent: the queue's own retry settings. */
+  retry?: TimerRetry;
+};
+
+export type TimerRef = { id: string; key?: never } | { key: string; id?: never };
+
+export interface Timers {
+  /**
+   * Run the queue's handler once with `data`, at `at` or `inSeconds` from
+   * now. Answers the job id. Throws `TimerError` (`unknown_queue`) when the
+   * queue is not one the tool's `jobs` slot declared, `invalid_argument` on a
+   * malformed call.
+   */
+  schedule<TData extends object>(queue: string, data: TData, options: TimerOptions): Promise<string>;
+  /**
+   * Withdraw a timer that has not run yet, by its id or by its key. Answers
+   * how many pending timers were withdrawn (0 when none was pending: already
+   * run, already withdrawn, running right now, or never scheduled).
+   */
+  cancel(queue: string, ref: TimerRef): Promise<number>;
+}
+
+export class TimerError extends Error {
+  constructor(
+    readonly code: 'unknown_queue' | 'invalid_argument',
+    message: string
+  ) {
+    super(message);
+    this.name = 'TimerError';
+  }
+}
+
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/** pg-boss's own rule for a queue name (`Attorney.assertQueueName`), applied before any statement runs. */
+const QUEUE_NAME = /^[\w-]+$/;
+/** Unit separator: joins the queue and the key under one lock hash, and can appear in neither. */
+const US = '\u001f';
+
+const invalid = (message: string) => new TimerError('invalid_argument', `timers: ${message}`);
+/** The longest delay a timer takes, in seconds: a hundred years. Postgres refuses an interval written in exponent form. */
+export const MAX_IN_SECONDS = 100 * 365.25 * 24 * 3600;
+
+function assertQueue(queue: unknown): asserts queue is string {
+  if (typeof queue !== 'string' || !QUEUE_NAME.test(queue)) {
+    throw invalid('the queue must be a name of letters, digits, underscores and hyphens');
+  }
+}
+
+/** The pg-boss `startAfter` for `options`: the Date of `at`, or the delay in seconds. */
+export function startAfterOf(options: TimerWhen): Date | number {
+  const hasAt = options.at !== undefined;
+  const hasIn = options.inSeconds !== undefined;
+  if (hasAt === hasIn) throw invalid('exactly one of `at` and `inSeconds` is required');
+  if (hasAt) {
+    const at = options.at as Date;
+    if (!(at instanceof Date) || !Number.isFinite(at.getTime())) throw invalid('`at` must be a valid Date');
+    return at;
+  }
+  const seconds = options.inSeconds as number;
+  if (!Number.isFinite(seconds) || seconds < 0 || seconds > MAX_IN_SECONDS)
+    throw invalid('`inSeconds` must be a finite number, between 0 and a hundred years');
+  return seconds;
+}
+
+function retryOptionsOf(retry: TimerRetry | undefined): PgBoss.RetryOptions {
+  if (retry === undefined) return {};
+  if (!Number.isInteger(retry.limit) || retry.limit < 0)
+    throw invalid('`retry.limit` must be an integer, 0 or more');
+  const delay = retry.delaySeconds ?? 0;
+  if (!Number.isInteger(delay) || delay < 0)
+    throw invalid('`retry.delaySeconds` must be an integer, 0 or more');
+  return { retryLimit: retry.limit, retryDelay: delay, retryBackoff: retry.backoff ?? false };
+}
+
+function assertData(data: unknown): void {
+  const proto = typeof data === 'object' && data !== null ? Object.getPrototypeOf(data) : undefined;
+  if (proto !== Object.prototype && proto !== null) {
+    throw invalid('the payload must be a plain object');
+  }
+  try {
+    JSON.stringify(data);
+  } catch {
+    throw invalid('the payload must be JSON (no bigint, no circular reference)');
+  }
+}
+
+function assertKey(key: unknown): asserts key is string {
+  if (typeof key !== 'string' || key.length === 0 || key.includes(US)) {
+    throw invalid('the key must be a non-empty string');
+  }
+}
+
+/** The one statement that withdraws pending timers: created or waiting for a retry, never running. */
+const CANCEL_PENDING = (where: string) => `
+  UPDATE ${PGBOSS_SCHEMA}.job
+  SET state = 'cancelled', completed_on = now()
+  WHERE name = $1 AND ${where} AND state IN ('created', 'retry')
+`;
+/**
+ * The statement that takes a RUNNING timer's retries away, so that if the
+ * run fails it ends `failed` and never comes back as a pending `retry` row
+ * under the withdrawn key or id (pg-boss retries while
+ * `retry_count < retry_limit`).
+ */
+const DISARM_ACTIVE = (where: string) => `
+  UPDATE ${PGBOSS_SCHEMA}.job
+  SET retry_limit = retry_count
+  WHERE name = $1 AND ${where} AND state = 'active'
+`;
+
+interface Queryable {
+  query(text: string, values: unknown[]): Promise<{ rowCount: number | null }>;
+}
+
+/** Withdraw the pending timers `ref` names and disarm a running one; answers the pending count withdrawn. */
+async function cancelPending(client: Queryable, queue: string, ref: TimerRef): Promise<number> {
+  let where: string;
+  let value: string;
+  if (ref.id !== undefined) {
+    if (!UUID.test(ref.id)) throw invalid('the id must be a job id');
+    where = 'id = $2::uuid';
+    value = ref.id;
+  } else {
+    assertKey(ref.key);
+    where = 'singleton_key = $2';
+    value = ref.key;
+  }
+  // The disarm FIRST, then the withdraw (verifier round 2, F7): pg-boss's fail
+  // path deletes the active row and re-inserts it as `retry` under the same
+  // key. Disarm first either takes the row lock before that fail (which then
+  // waits for the commit and computes `failed` on the disarmed row) or runs
+  // after it, and the withdraw, a new statement with a new snapshot, then
+  // sees the re-inserted `retry` row and cancels it. In the other order both
+  // statements could miss the row, one round trip wide. A replace whose
+  // insert then fails rolls the disarm back with it: the old run keeps its
+  // retries, a failed replace changes nothing.
+  await client.query(DISARM_ACTIVE(where), [queue, value]);
+  const res = await client.query(CANCEL_PENDING(where), [queue, value]);
+  return res.rowCount ?? 0;
+}
+
+export class PgBossTimers implements Timers {
+  constructor(
+    private readonly boss: PgBoss,
+    private readonly pool: pg.Pool,
+    private readonly logger: Logger
+  ) {}
+
+  async schedule<TData extends object>(queue: string, data: TData, options: TimerOptions): Promise<string> {
+    assertQueue(queue);
+    assertData(data);
+    const send: PgBoss.SendOptions = { startAfter: startAfterOf(options), ...retryOptionsOf(options.retry) };
+    if (options.key === undefined) {
+      return this.insert(queue, data, send);
+    }
+    assertKey(options.key);
+    const key = options.key;
+    // Replace = withdraw + insert in one transaction, serialized per key
+    // across replicas by a transaction-scoped advisory lock on a client of
+    // our own: pg-boss runs the insert through the `db` executor we hand it.
+    const client = await this.pool.connect();
+    try {
+      await client.query('BEGIN');
+      await client.query('SELECT pg_advisory_xact_lock($1, hashtext($2))', [
+        TIMER_KEY_LOCK_CLASS,
+        queue + US + key
+      ]);
+      const replaced = await cancelPending(client, queue, { key });
+      const id = await this.insert(queue, data, {
+        ...send,
+        singletonKey: key,
+        db: { executeSql: (text, values) => client.query(text, values) }
+      });
+      await client.query('COMMIT');
+      if (replaced > 0) this.logger.debug({ queue, key, replaced }, 'timers: a pending timer was replaced');
+      return id;
+    } catch (err) {
+      await client.query('ROLLBACK').catch(() => {});
+      throw err;
+    } finally {
+      client.release();
+    }
+  }
+
+  async cancel(queue: string, ref: TimerRef): Promise<number> {
+    assertQueue(queue);
+    if ((ref.id === undefined) === (ref.key === undefined))
+      throw invalid('exactly one of `id` and `key` is required');
+    return cancelPending(this.pool, queue, ref);
+  }
+
+  /** pg-boss answers null for a queue that does not exist (its insert joins the queue row): that is an unknown queue, named. */
+  private async insert(queue: string, data: object, send: PgBoss.SendOptions): Promise<string> {
+    const id = await this.boss.send(queue, data, send);
+    if (id === null) {
+      throw new TimerError(
+        'unknown_queue',
+        `timers: the queue "${queue}" is not declared by the tool's jobs slot (a timer rides a declared queue)`
+      );
+    }
+    return id;
+  }
+}

package/src/logger.ts

@@ -0,0 +1,67 @@
+import { pino, type Logger } from 'pino';
+import type { Env } from './env.js';
+
+export type { Logger };
+
+/**
+ * The single redaction list — secrets never reach the log stream.
+ *
+ * Two rules when adding to it. (1) pino's `*.x` glob matches the key `x` at
+ * depth 1 ONLY, and it is an EXACT key match: `*.secret` does NOT cover
+ * `clientSecret`, `client_secret`, or `apiSecret`, so every camel/snake spelling
+ * a payload can carry needs its own entry. (2) Redaction keys off object
+ * PROPERTIES — it can do nothing about a secret interpolated into a message
+ * string. Never build a log message out of a config payload; log the shape
+ * (`{ length, path }`), never the bytes.
+ */
+export const REDACT_PATHS = [
+  'req.headers.authorization',
+  'req.headers.cookie',
+  '*.password',
+  '*.secret',
+  '*.token',
+  // Exact-key spellings the `*.secret` glob misses — OAuth/hub-federation
+  // payloads carry these verbatim.
+  '*.clientSecret',
+  '*.client_secret',
+  '*.accessToken',
+  '*.access_token',
+  '*.refreshToken',
+  '*.refresh_token',
+  '*.apiKey',
+  '*.api_key',
+  'DATABASE_URL',
+  'AUTH_SECRET',
+  'API_KEY_PEPPERS',
+  'SETUP_TOKEN',
+  'METRICS_TOKEN',
+  'SMTP_URL',
+  'RESEND_API_KEY',
+  'BREVO_API_KEY',
+  'S3_SECRET_ACCESS_KEY',
+  'S3_ACCESS_KEY_ID',
+  // Optional social credential — read in env.ts, so any "here is the parsed
+  // env" line would otherwise carry it.
+  'GOOGLE_CLIENT_SECRET',
+  // Cloud edition: the hub-federation client credential (ADR 015 / user-scoped
+  // federation). It is THIS tool's identity at the Antasphere hub — leaking it
+  // lets anyone impersonate the tool at the authorization server.
+  'HUB_CLIENT_SECRET'
+];
+
+export function createLogger(env: Pick<Env, 'LOG_LEVEL' | 'NODE_ENV'>): Logger {
+  const options = {
+    level: env.LOG_LEVEL,
+    redact: { paths: REDACT_PATHS, censor: '[redacted]' }
+  };
+  if (env.NODE_ENV === 'development') {
+    // pino-pretty is a devDependency; if it is absent (e.g. NODE_ENV flipped
+    // on a pruned production image) fall back to JSON instead of crashing.
+    try {
+      return pino({ ...options, transport: { target: 'pino-pretty', options: { colorize: true } } });
+    } catch {
+      // fall through to JSON output
+    }
+  }
+  return pino(options);
+}

package/src/mcp/errors.ts

@@ -0,0 +1,111 @@
+/**
+ * API error → model-readable hint mapping (the predecessor MCP template's
+ * DOMAIN_HINTS pattern). The API returns `{ error: { code, message } }` on
+ * failure; each domain code can carry an actionable hint so the model
+ * self-corrects instead of retrying blindly. The table below holds the hints of
+ * the chassis' own codes; a tool adds its domain's through
+ * {@link mergeErrorHints} (the `errorHints` of its MCP definition).
+ */
+export type ErrorHints = Readonly<Record<string, string>>;
+
+const DOMAIN_HINTS: Record<string, string> = {
+  insufficient_scope:
+    'Reconnect the MCP server and approve the permission on the consent screen ' +
+    '(or mint an API key that includes the scope).',
+  endpoint_not_allowed:
+    'This endpoint is not opened to machine credentials — a human must do this in the dashboard.',
+  invalid_token: 'The OAuth token expired or was revoked. Reconnect the MCP server.',
+  unauthenticated: 'No valid credential reached the API. Reconnect the MCP server.',
+  rate_limited: 'Rate limited — wait before retrying.',
+  plan_required:
+    'The workspace\u2019s plan does not allow this — the upgrade link in this message is where a human raises it.',
+  // The same code on both editions: the cloud's credit refusal (402, with the
+  // top-up link) and a self-hosted instance's cap (413, no details).
+  entitlement_denied:
+    'The instance refused this action: on the cloud the organization lacks the credits and the top-up link in this message is where a human adds them, or the quantity is beyond what can be priced and no top-up covers it (no link then); on a self-hosted instance the request exceeds the operator’s cap.'
+};
+
+/** The chassis hints plus a tool's own: ONE table, the one every lookup reads. */
+export function mergeErrorHints(toolHints: ErrorHints): ErrorHints {
+  return { ...DOMAIN_HINTS, ...toolHints };
+}
+
+/** Thrown when the in-process API call returns a non-2xx wire-shape response. */
+export class ApiToolError extends Error {
+  readonly status: number;
+  readonly code: string | null;
+
+  /** The wire's `error.details`, when the API sent any (a plan refusal's upgrade link rides here). */
+  readonly details: unknown;
+
+  constructor(status: number, code: string | null, message: string, details?: unknown) {
+    super(message);
+    this.name = 'ApiToolError';
+    this.status = status;
+    this.code = code;
+    this.details = details;
+  }
+
+  toUserFacingText(hints: ErrorHints = DOMAIN_HINTS): string {
+    const hint = this.code ? hints[this.code] : undefined;
+    const codePart = this.code ? `, code: ${this.code}` : '';
+    // A plan refusal carries its upgrade link (the billing rail, §7): the
+    // agent relays it, a human follows it. Text, never a structured field.
+    const upgradeUrl = (this.details as { upgradeUrl?: unknown } | null)?.upgradeUrl;
+    const upgrade = typeof upgradeUrl === 'string' && upgradeUrl ? ` Upgrade: ${upgradeUrl}` : '';
+    // A credit refusal (402 `entitlement_denied`, PRDCT-2664) carries its
+    // top-up link, the price and the balance: the same, as text. The
+    // self-hosted cap's 413 has no details, so no top-up sentence.
+    const { topUpUrl, credits, balance } = (this.details ?? {}) as {
+      topUpUrl?: unknown;
+      credits?: unknown;
+      balance?: unknown;
+    };
+    let topUp = '';
+    // The gate's message already carries the link, the price and the balance;
+    // the sentence is added only for a message that does not (verifier
+    // round 1: the URL was printed twice).
+    if (typeof topUpUrl === 'string' && topUpUrl && !this.message.includes(topUpUrl)) {
+      const needs = typeof credits === 'number' ? [`this needs ${credits} credits`] : [];
+      const holds = typeof balance === 'number' ? [`the organization holds ${balance}`] : [];
+      const numbers = [...needs, ...holds].join(', ');
+      topUp = ` Top up: ${topUpUrl}${numbers ? ` (${numbers}).` : ''}`;
+    }
+    return `API error (HTTP ${this.status}${codePart}): ${this.message}${hint ? ` — Next: ${hint}` : ''}${upgrade}${topUp}`;
+  }
+}
+
+export interface ToolTextResult {
+  // Index signature: the MCP SDK's CallToolResult carries extra open fields.
+  [key: string]: unknown;
+  content: Array<{ type: 'text'; text: string }>;
+  isError?: true;
+}
+
+export const jsonText = (result: unknown): ToolTextResult => ({
+  content: [{ type: 'text' as const, text: JSON.stringify(result, null, 2) }]
+});
+
+export const deny = (text: string): ToolTextResult => ({
+  content: [{ type: 'text' as const, text }],
+  isError: true as const
+});
+
+/**
+ * Wrap a tool body so any thrown ApiToolError surfaces as a structured MCP
+ * tool error (`isError: true` + text) rather than a protocol-level exception.
+ * Other errors propagate to the SDK.
+ */
+export async function wrapToolErrors(
+  fn: () => Promise<ToolTextResult>,
+  hints: ErrorHints = DOMAIN_HINTS
+): Promise<ToolTextResult> {
+  try {
+    return await fn();
+  } catch (err) {
+    if (err instanceof ApiToolError) {
+      return { content: [{ type: 'text', text: err.toUserFacingText(hints) }], isError: true };
+    }
+    throw err;
+  }
+}

package/src/mcp/http.ts

@@ -0,0 +1,129 @@
+import { Hono } from 'hono';
+import type { MiddlewareHandler } from 'hono';
+import { bodyLimit } from 'hono/body-limit';
+import { HTTPException } from 'hono/http-exception';
+import { StreamableHTTPTransport } from '@hono/mcp';
+import type { Principal } from '@antasphere/chassis-contract';
+import { looksLikeJwt } from '../middleware/scopes.js';
+import { buildMcpServer, type McpIdentity, type McpToolDefinition } from './server.js';
+
+/**
+ * The bundled /mcp endpoint (streamable HTTP, STATELESS — see ADR 002).
+ *
+ * Auth gate first: a valid OAuth bearer (token this instance minted) or an
+ * API key — both machine principals, resolved through the same machinery as
+ * /api/v1. Anything else gets the RFC 9728 401 challenge whose
+ * `resource_metadata` URL drives the whole client OAuth dance.
+ *
+ * Stateless transport: a fresh McpServer + transport per request, no session
+ * ids, no in-process stream state — the platform's statelessness invariant
+ * applies to MCP too (any replica can serve any request).
+ */
+export interface McpHttpDeps {
+  publicBaseUrl: string;
+  version: string;
+  /** In-process fetch against the root app; tools forward the caller's bearer. */
+  fetchApi: (path: string, init?: RequestInit) => Promise<Response>;
+  resolveOauthJwt: (token: string) => Promise<Principal | null>;
+  resolveApiKey: (token: string) => Promise<Principal | null>;
+  isApiKeyToken: (token: string) => boolean;
+  /** Instance display name for the server instructions (cached by the caller). */
+  instanceName: () => Promise<string>;
+  /** Per-IP rate limit, applied before the auth gate (floods rejected cheaply). */
+  limiter: MiddlewareHandler;
+  /** The tool's MCP definition: its tools, instructions, error hints and scope names. */
+  tool: McpToolDefinition;
+  /** The server's name and the tool names' prefix (`identity.mcp`). */
+  identity: McpIdentity;
+}
+
+export function mcpRoutes(deps: McpHttpDeps): Hono {
+  const app = new Hono();
+  const challengeUrl = `${deps.publicBaseUrl.replace(/\/+$/, '')}/.well-known/oauth-protected-resource/mcp`;
+
+  app.use('*', deps.limiter);
+  // JSON-RPC bodies are small; cap them so a caller can't force the transport
+  // to buffer an arbitrarily large body (the /api/v1 cap does not cover /mcp).
+  app.use(
+    '*',
+    bodyLimit({
+      maxSize: 1024 * 1024,
+      onError: (c) =>
+        c.json({ error: 'payload_too_large', error_description: 'MCP request body exceeds 1 MiB' }, 413)
+    })
+  );
+
+  const unauthorized = (description: string) =>
+    new Response(JSON.stringify({ error: 'invalid_token', error_description: description }), {
+      status: 401,
+      headers: {
+        'content-type': 'application/json',
+        'www-authenticate': `Bearer resource_metadata="${challengeUrl}"`
+      }
+    });
+
+  app.post('/', async (c) => {
+    const authHeader = c.req.header('authorization')?.trim() ?? '';
+    const bearer = /^Bearer\s+(.+)$/i.exec(authHeader)?.[1]?.trim() ?? null;
+    if (!bearer) {
+      return unauthorized('Authentication required');
+    }
+
+    let principal: Principal | null = null;
+    if (deps.isApiKeyToken(bearer)) {
+      principal = await deps.resolveApiKey(bearer);
+    } else if (looksLikeJwt(bearer)) {
+      principal = await deps.resolveOauthJwt(bearer);
+    }
+    if (!principal) {
+      return unauthorized('Bearer token is invalid, expired, or revoked');
+    }
+
+    const server = buildMcpServer(
+      {
+        fetchApi: deps.fetchApi,
+        principal,
+        authorizationHeader: `Bearer ${bearer}`,
+        publicBaseUrl: deps.publicBaseUrl
+      },
+      { version: deps.version, instanceName: await deps.instanceName() },
+      deps.tool,
+      deps.identity
+    );
+    // No sessionIdGenerator = stateless: every POST is self-contained.
+    // enableJsonResponse returns plain JSON bodies (no SSE), so the Response
+    // handed back to Hono is complete — no stream outlives the request,
+    // nothing to tear down (the per-request server + transport are
+    // unreferenced after this).
+    const transport = new StreamableHTTPTransport({ enableJsonResponse: true });
+    await server.connect(transport);
+    try {
+      const res = await transport.handleRequest(c);
+      return res ?? c.body(null, 204);
+    } catch (cause) {
+      // The transport reports protocol failures by THROWING HTTPException
+      // (400 -32700 for a malformed / non-JSON-RPC body, 406/415 for header
+      // problems), each carrying a complete JSON-RPC error response. Return
+      // that response instead of letting the root onError turn it into a
+      // generic 500.
+      if (cause instanceof HTTPException) {
+        return cause.getResponse();
+      }
+      throw cause;
+    }
+  });
+
+  // Non-POST is rejected here EXPLICITLY (ADR 002): the stateless transport
+  // does NOT 405 on its own — its GET handler would happily open a long-lived
+  // server-initiated SSE stream, and DELETE would answer a session teardown.
+  // Neither exists in stateless mode, so every non-POST method gets
+  // 405 + Allow: POST with a JSON-RPC error envelope (the shape the official
+  // SDK expects and tolerates).
+  app.all('/', (c) =>
+    c.json({ jsonrpc: '2.0', error: { code: -32000, message: 'Method not allowed' }, id: null }, 405, {
+      allow: 'POST'
+    })
+  );
+
+  return app;
+}

package/src/mcp/index.ts

@@ -0,0 +1,28 @@
+export {
+  ApiToolError,
+  type ErrorHints,
+  type ToolTextResult,
+  deny,
+  jsonText,
+  mergeErrorHints,
+  wrapToolErrors
+} from './errors.js';
+export { mcpRoutes } from './http.js';
+export { projectErrorHints, registerProjectTools } from './projects.js';
+export { registerTeamTools } from './teams.js';
+export { type McpInputs, mcpInputs } from './inputs.js';
+export {
+  type McpIdentity,
+  type McpServerInfo,
+  type McpToolDefinition,
+  buildMcpServer,
+  composeErrorHints
+} from './server.js';
+export {
+  type McpToolContext,
+  callApi,
+  createScopeCheck,
+  fetchApiRaw,
+  forWorkspace,
+  pageQuery
+} from './tool-kit.js';

package/src/mcp/inputs.ts

@@ -0,0 +1,33 @@
+import { z } from 'zod';
+import type { ToolIdentity } from '@antasphere/chassis-contract';
+
+/**
+ * The inputs every MCP tool of an instance shares, chassis tools and the
+ * tool's own alike: ONE definition, so the same argument reads the same in
+ * every tool of `tools/list`. The workspace input names `<toolPrefix>whoami`
+ * (the identity tool the chassis registers), hence a factory over the MCP half
+ * of the tool's identity. Build it once per server, next to `registerTools`.
+ */
+export function mcpInputs(identity: Pick<ToolIdentity['mcp'], 'toolPrefix'>) {
+  return {
+    /** The per-call target workspace; omitted, the caller's default one. */
+    workspaceInput: z
+      .uuid()
+      .optional()
+      .describe(
+        `Target organization (workspace id). Omit to use your default org — see ${identity.toolPrefix}whoami.`
+      ),
+    /** The cursor of a paginated list, passed through to the API. */
+    cursorInput: z.string().optional().describe('nextCursor from a previous page.'),
+    /** The page size of a paginated list. */
+    limitInput: z
+      .number()
+      .int()
+      .min(1)
+      .max(100)
+      .optional()
+      .describe('Page size (server max 100). Default 50.')
+  };
+}
+
+export type McpInputs = ReturnType<typeof mcpInputs>;