@cyanheads/mcp-ts-core 0.13.9 → 0.13.10

package/scripts/lint-packaging.ts

@@ -69,12 +69,17 @@
  *      same rule check 10 applies to the plugin manifests — the bundle's install
  *      dialog shows it. Skipped when `manifest.json` or the package version is
  *      absent.
- *  15. Dockerfile build platform: every stage that runs `bun run build` must
- *      start `FROM --platform=$BUILDPLATFORM`. Without it the non-native leg of
- *      a multi-arch `docker buildx` build runs under QEMU, where bun >= 1.4
- *      aborts inside the build and no image publishes for either architecture —
- *      and the image publishes last, after npm and the MCP Registry. Skipped
- *      when there is no `Dockerfile` or no stage builds.
+ *  15. Dockerfile build platform: a stage that does not start
+ *      `FROM --platform=$BUILDPLATFORM` must not run JavaScript while it
+ *      builds — no `RUN` invoking `bun` for anything but `install`/`add`
+ *      (`bun run build`, `bun -e`, a script, `bunx`), and no `bun install`/
+ *      `bun add` once `bunfig.toml` is in the stage, since its security scanner
+ *      runs as a Bun program. The non-native leg of a multi-arch `docker buildx`
+ *      build runs such a stage under QEMU, where bun >= 1.4 aborts and no image
+ *      publishes for either architecture — and the image publishes last, after
+ *      npm and the MCP Registry. `HEALTHCHECK`/`CMD`/`ENTRYPOINT` run at
+ *      container start and never count. One error per stage, naming each
+ *      offending line (issue #575). Skipped when there is no `Dockerfile`.
  *
  * Every check skips cleanly when its input is absent — consumers who deleted
  * `manifest.json` for an HTTP-only deploy, or who haven't built a bundle,
@@ -183,10 +188,10 @@ function tryReadJson<T>(path: string): T | undefined {
  * to evaluate which paths survive the ignore rules. Returns an array of error
  * strings; empty means all checks passed.
  *
- * **Context note:** this guard runs inside the scaffolded server project, not
- * inside mcp-ts-core itself. `ignore` is listed in `templates/package.json`
- * devDependencies (`^7.0.5`) and is therefore available in the server's
- * `node_modules` when `bun run lint:packaging` is invoked there.
+ * **Context note:** `ignore` is a devDependency of the framework and of every
+ * scaffold (`templates/package.json`), so it resolves wherever
+ * `bun run lint:packaging` runs against an `.mcpbignore` — a server project, or
+ * mcp-ts-core itself. Where it cannot load, the guard is skipped.
  */
 interface IgnoreMatcher {
   add(patterns: string[]): IgnoreMatcher;
@@ -799,33 +804,189 @@ export function checkManifestVersion(manifest: Manifest, packageVersion?: string
   ];
 }
 
-const DOCKERFILE_FROM = /^\s*FROM\s/i;
+/** One Dockerfile instruction: continuations joined, a `RUN` heredoc body folded in. */
+interface DockerInstruction {
+  args: string;
+  keyword: string;
+  /** 1-based line the instruction starts on. */
+  line: number;
+  text: string;
+}
+
+const DOCKERFILE_SKIPPED_LINE = /^\s*(?:#|$)/;
+const DOCKERFILE_CONTINUATION = /\\\s*$/;
+const DOCKERFILE_HEREDOC = /<<-?(["']?)([A-Za-z_]\w*)\1/g;
+
+/**
+ * Splits a Dockerfile into instructions the way BuildKit reads it: a trailing
+ * `\` continues onto the next line, comment and blank lines inside a
+ * continuation are dropped, and a `RUN` heredoc's body belongs to its `RUN`.
+ */
+function dockerInstructions(dockerfile: string): DockerInstruction[] {
+  const lines = dockerfile.split(/\r?\n/);
+  const instructions: DockerInstruction[] = [];
+  for (let i = 0; i < lines.length; i++) {
+    if (DOCKERFILE_SKIPPED_LINE.test(lines[i] ?? '')) continue;
+    const line = i + 1;
+    let text = (lines[i] ?? '').trim();
+    while (DOCKERFILE_CONTINUATION.test(text) && i + 1 < lines.length) {
+      text = text.replace(DOCKERFILE_CONTINUATION, ' ');
+      do i++;
+      while (i < lines.length && DOCKERFILE_SKIPPED_LINE.test(lines[i] ?? ''));
+      text += (lines[i] ?? '').trim();
+    }
+    const keyword = (text.split(/\s/, 1)[0] ?? '').toUpperCase();
+    if (keyword === 'RUN') {
+      for (const [, , delimiter] of text.matchAll(DOCKERFILE_HEREDOC)) {
+        while (i + 1 < lines.length && (lines[++i] ?? '').trim() !== delimiter) {
+          text += `\n${lines[i]}`;
+        }
+      }
+    }
+    instructions.push({ keyword, args: text.slice(keyword.length).trim(), line, text });
+  }
+  return instructions;
+}
+
+/** Words that may precede the command itself in a simple shell command. */
+const SHELL_COMMAND_PREFIX = new Set([
+  '!',
+  'command',
+  'do',
+  'elif',
+  'else',
+  'env',
+  'exec',
+  'if',
+  'then',
+  'time',
+  'until',
+  'while',
+]);
+
+/** A `bun`/`bunx` invocation in a `RUN`: the command word and the words after it. */
+interface BunInvocation {
+  args: string[];
+  command: 'bun' | 'bunx';
+}
+
+function bunCommand(word: string | undefined): BunInvocation['command'] | undefined {
+  const name = word?.split('/').pop();
+  return name === 'bun' || name === 'bunx' ? name : undefined;
+}
+
+/**
+ * The `bun`/`bunx` invocations a `RUN` instruction's command makes, read from
+ * command position only — `chown bun:bun`, `/root/.bun/`, and a quoted
+ * mention are not invocations. Quoted strings are opaque, so a `bun -e '…'`
+ * program never splits into commands of its own.
+ */
+function bunInvocations(runArgs: string): BunInvocation[] {
+  const command = runArgs.replace(/^(?:--[\w-]+=\S+\s+)*/, '');
+  if (command.startsWith('[')) {
+    try {
+      const argv: unknown = JSON.parse(command);
+      if (Array.isArray(argv)) {
+        const name = bunCommand(String(argv[0]));
+        return name ? [{ command: name, args: argv.slice(1).map(String) }] : [];
+      }
+    } catch {
+      // Not a JSON exec form: fall through and read it as shell.
+    }
+  }
+  return command
+    .replace(/'[^']*'|"(?:\\.|[^"\\])*"/g, "'…'")
+    .split(/&&|\|\||[;|&(){}`\n]/)
+    .flatMap((segment) => {
+      const words = segment.trim().split(/\s+/);
+      const start = words.findIndex(
+        (word) => !SHELL_COMMAND_PREFIX.has(word) && !/^[A-Za-z_]\w*=/.test(word),
+      );
+      const name = bunCommand(words[start]);
+      return name ? [{ command: name, args: words.slice(start + 1) }] : [];
+    });
+}
+
 const DOCKERFILE_BUILD_PLATFORM = /--platform=\$\{?BUILDPLATFORM\}?(?:\s|$)/;
-const DOCKERFILE_BUILD_STEP = /\bbun run (?:re)?build\b/;
+const BUN_INSTALL_SUBCOMMANDS = new Set(['install', 'i', 'add', 'a']);
+const BUNFIG_SOURCE = /(?:^|[\s/"'[,])bunfig\.toml(?=[\s"',\]]|$)/;
+
+/** Whether a `COPY`/`ADD` brings `bunfig.toml` into the stage, by name or with the whole context. */
+function copiesBunfig(args: string): boolean {
+  if (BUNFIG_SOURCE.test(args)) return true;
+  const words = args.split(/\s+/);
+  if (words.some((word) => word.startsWith('--from='))) return false;
+  const sources = words.filter((word) => !word.startsWith('--')).slice(0, -1);
+  return sources.some((source) => source === '.' || source === './');
+}
 
 /**
- * Check 15: every Dockerfile stage that runs `bun run build` must be pinned to
- * the build platform. Stages are split at `FROM` lines; comment lines are
- * ignored so a note mentioning the build does not count as one.
+ * Check 15: a Dockerfile stage built for the target platform must not run
+ * JavaScript while it builds. A multi-arch `docker buildx` build runs every
+ * such stage under QEMU on the non-native leg, where bun >= 1.4 aborts, and the
+ * image publishes last — after npm and the MCP Registry. A stage counts as
+ * running JavaScript when a `RUN` invokes `bun` for anything but
+ * `install`/`add` (`bun run build`, `bun -e`, a script, `bunx`), or runs
+ * `bun install`/`bun add` once `bunfig.toml` is in the stage, since its
+ * `[install.security]` scanner runs as a Bun program. A stage whose `FROM`
+ * carries `--platform=$BUILDPLATFORM` is exempt, and so are `HEALTHCHECK`,
+ * `CMD`, and `ENTRYPOINT`, which run at container start on the real target.
+ * One error per stage, naming each offending line.
  */
 export function checkDockerfileBuildPlatform(dockerfile: string): string[] {
-  const stages: { from: string; line: number; builds: boolean }[] = [];
-  for (const [index, line] of dockerfile.split('\n').entries()) {
-    if (DOCKERFILE_FROM.test(line)) {
-      stages.push({ from: line.trim(), line: index + 1, builds: false });
-    } else if (!line.trimStart().startsWith('#') && DOCKERFILE_BUILD_STEP.test(line)) {
-      const stage = stages.at(-1);
-      if (stage) stage.builds = true;
+  const stages: {
+    alias: string | undefined;
+    bunfig: boolean;
+    findings: string[];
+    from: DockerInstruction;
+    pinned: boolean;
+  }[] = [];
+
+  for (const instruction of dockerInstructions(dockerfile)) {
+    if (instruction.keyword === 'FROM') {
+      const [image = '', , alias] = instruction.args
+        .toLowerCase()
+        .split(/\s+/)
+        .filter((word) => !word.startsWith('--'));
+      stages.push({
+        alias,
+        // A stage built FROM an earlier one starts with that stage's files.
+        bunfig: stages.find((earlier) => earlier.alias === image)?.bunfig ?? false,
+        findings: [],
+        from: instruction,
+        pinned: DOCKERFILE_BUILD_PLATFORM.test(instruction.args),
+      });
+      continue;
+    }
+    const stage = stages.at(-1);
+    if (!stage) continue;
+    if (instruction.keyword === 'COPY' || instruction.keyword === 'ADD') {
+      stage.bunfig ||= copiesBunfig(instruction.args);
+    } else if (instruction.keyword === 'RUN' && !stage.pinned) {
+      const finding = bunInvocations(instruction.args)
+        .map(({ command, args }) => {
+          const subcommand = args.find((arg) => !arg.startsWith('-'));
+          if (command === 'bun' && BUN_INSTALL_SUBCOMMANDS.has(subcommand ?? '')) {
+            return stage.bunfig
+              ? `\`bun ${subcommand}\` after bunfig.toml is in the stage, which starts its security scanner as a Bun program`
+              : undefined;
+          }
+          return `\`${[command, args[0]].filter(Boolean).join(' ')}\``;
+        })
+        .find(Boolean);
+      if (finding) stage.findings.push(`Dockerfile:${instruction.line} runs ${finding}`);
     }
   }
 
   return stages
-    .filter((stage) => stage.builds && !DOCKERFILE_BUILD_PLATFORM.test(stage.from))
+    .filter((stage) => stage.findings.length > 0)
     .map(
-      (stage) =>
-        `Dockerfile:${stage.line} "${stage.from}" runs \`bun run build\` without --platform=$BUILDPLATFORM — ` +
-        `a multi-arch buildx build then runs it under QEMU, where bun aborts and no image publishes; ` +
-        `start the build stage with "FROM --platform=$BUILDPLATFORM" and copy dist/ into a separate runtime stage`,
+      ({ from, findings }) =>
+        `Dockerfile:${from.line} "${from.text}" builds for the target platform but runs JavaScript while ` +
+        `building — ${findings.join('; ')}. A multi-arch buildx build runs that under QEMU on the non-native ` +
+        `leg, where bun aborts and no image publishes. Move these steps into a stage that starts ` +
+        `"FROM --platform=$BUILDPLATFORM" (cross-install with \`bun install --os=<os> --cpu=<x64|arm64>\`) and ` +
+        `copy their output (dist/, node_modules/) into this stage`,
     );
 }
 

package/templates/.env.example

@@ -9,6 +9,8 @@
 # ── Auth ──────────────────────────────────────────────────────────────
 # MCP_AUTH_MODE=none                # none | jwt | oauth (default: none)
 # MCP_AUTH_SECRET_KEY=              # JWT secret (required for jwt mode)
+# MCP_REQUEST_STATE_KEY=            # Opt-in, >= 32 bytes, same on every instance: seals the requestState
+                                    # handlers return; any other state is rejected before the handler runs
 
 # ── Storage ───────────────────────────────────────────────────────────
 # STORAGE_PROVIDER_TYPE=in-memory   # in-memory | filesystem | supabase | cloudflare-r2 | cloudflare-kv | cloudflare-d1

package/templates/AGENTS.md

@@ -201,11 +201,12 @@ Handlers receive a unified `ctx` object. Key properties:
 | `ctx.log` | Request-scoped logger — `.debug()`, `.info()`, `.notice()`, `.warning()`, `.error()`. Auto-correlates requestId, traceId, tenantId. Dual-sink: Pino **and** `notifications/message` to the client, so treat it as client-visible. |
 | `ctx.state` | Tenant-scoped KV — `.get(key)`, `.set(key, value, { ttl? })`, `.delete(key)`, `.getMany(keys)`, `.list(prefix, { cursor, limit })`. Accepts any JSON-serializable value; reads return its JSON form (a `Date` comes back as an ISO string). |
 | `ctx.requestInput` | Suspend and ask the caller for more input — `return ctx.requestInput({ inputRequests: { key: inputRequired.elicit({ message, requestedSchema }) } })`. Never returns; the handler is re-entered with the answers. Always present. |
-| `ctx.inputs` | Reader over a retried request's responses — `.accepted(key, schema)`, `.view(key)`, `.state()`, `.dropped`. Empty on the first round. |
+| `ctx.inputs` | The request's responses — `.accepted(key, schema)`, `.view(key)`, `.state()`, `.dropped` — limited to what the client declared (`elicitation` and its form/url modes, `sampling`, `roots`). Client-supplied: a consent gate trusts only a `ctx.state` record it stored when it asked, bound to the operation, caller, and target (see the `api-context` skill). |
+| `ctx.clientCapabilities` | What the client declared for this request, `undefined` when no view exists. Decides whether to ask for optional context (e.g. roots); never a reason to skip a consent prompt. |
 | `ctx.enrich` | Success-path agent context (empty-result notices, query echo, pagination totals) — `ctx.enrich(...)` or `.notice()` / `.total()` / `.echo()` / `.truncated()`. Reaches `structuredContent` and `content[]`; lands only when the definition declares an `enrichment` block (no-op otherwise). |
 | `ctx.content` | Non-text content blocks — `.image(data, mimeType)`, `.audio(data, mimeType)`, or `ctx.content(block)` for a raw block. Prepended to `content[]` after `format()`; never enters `structuredContent`. |
 | `ctx.signal` | `AbortSignal` for cancellation. |
-| `ctx.requestId` | Unique request ID. |
+| `ctx.requestId` | Request ID — the one every log record of the call carries and its error envelope returns as `data.requestId`. |
 | `ctx.tenantId` | Tenant ID from JWT; `'default'` for stdio or HTTP with auth off. |
 
 ---
@@ -214,7 +215,7 @@ Handlers receive a unified `ctx` object. Key properties:
 
 Handlers throw — the framework catches, classifies, and formats.
 
-**Recommended: typed error contract.** Declare `errors: [{ reason, code, when, recovery, retryable?, severity?, thrownBy? }]` on `tool()` / `resource()` to receive `ctx.fail(reason, …)` typed against the reason union. TypeScript catches typos at compile time, `data.reason` is auto-populated for observability, linter enforces conformance against the handler body. `recovery` is required (≥ 5 words, lint-validated) — the single source of truth for the agent's next move. Pass `ctx.recoveryFor('reason')` as the throw's data to put it on the wire (`data.recovery.hint`, mirrored into `content[]` text unless the message already contains it verbatim); override with an explicit `{ recovery: { hint: '...' } }` when dynamic runtime context matters. Forwarding it is lint-enforced per throw site (`error-contract-recovery-unforwarded`). Mark an entry the service layer throws with `thrownBy: 'service'` so `error-contract-unthrown` skips it — lint-only metadata, nothing at runtime reads it. Baseline codes (`InternalError`, `ServiceUnavailable`, `Timeout`, `ValidationError`, `SerializationError`, `RequestCancelled`) bubble freely and don't need declaring.
+**Recommended: typed error contract.** Declare `errors: [{ reason, code, when, recovery, retryable?, severity?, thrownBy? }]` on `tool()` / `resource()` to receive `ctx.fail(reason, …)` typed against the reason union. TypeScript catches typos at compile time, `data.reason` is auto-populated for observability, linter enforces conformance against the handler body. `recovery` is required (≥ 5 words, lint-validated) — the single source of truth for the agent's next move. The framework puts it on the wire whenever a failure carrying that `reason` arrives without a hint — a bare `ctx.fail('reason')` or a service throw with `data: { reason }` — as `data.recovery.hint`, mirrored into `content[]` text unless the message already contains it verbatim; override with an explicit `{ recovery: { hint: '...' } }` when dynamic runtime context matters. Every error envelope also carries `data.requestId`, the id the server's log records for that call carry, and `content[]` closes with `(reason … · request <id>)`. Mark an entry the service layer throws with `thrownBy: 'service'` so `error-contract-unthrown` skips it — lint-only metadata, nothing at runtime reads it. Baseline codes (`InternalError`, `ServiceUnavailable`, `Timeout`, `ValidationError`, `SerializationError`, `RequestCancelled`) bubble freely and don't need declaring.
 
 ```ts
 import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
@@ -226,7 +227,7 @@ errors: [
 ],
 async handler(input, ctx) {
   const item = await db.find(input.id);
-  if (!item) throw ctx.fail('no_match', `No item ${input.id}`, ctx.recoveryFor('no_match'));
+  if (!item) throw ctx.fail('no_match', `No item ${input.id}`);
   return item;
 }
 ```

package/templates/CLAUDE.md

@@ -201,11 +201,12 @@ Handlers receive a unified `ctx` object. Key properties:
 | `ctx.log` | Request-scoped logger — `.debug()`, `.info()`, `.notice()`, `.warning()`, `.error()`. Auto-correlates requestId, traceId, tenantId. Dual-sink: Pino **and** `notifications/message` to the client, so treat it as client-visible. |
 | `ctx.state` | Tenant-scoped KV — `.get(key)`, `.set(key, value, { ttl? })`, `.delete(key)`, `.getMany(keys)`, `.list(prefix, { cursor, limit })`. Accepts any JSON-serializable value; reads return its JSON form (a `Date` comes back as an ISO string). |
 | `ctx.requestInput` | Suspend and ask the caller for more input — `return ctx.requestInput({ inputRequests: { key: inputRequired.elicit({ message, requestedSchema }) } })`. Never returns; the handler is re-entered with the answers. Always present. |
-| `ctx.inputs` | Reader over a retried request's responses — `.accepted(key, schema)`, `.view(key)`, `.state()`, `.dropped`. Empty on the first round. |
+| `ctx.inputs` | The request's responses — `.accepted(key, schema)`, `.view(key)`, `.state()`, `.dropped` — limited to what the client declared (`elicitation` and its form/url modes, `sampling`, `roots`). Client-supplied: a consent gate trusts only a `ctx.state` record it stored when it asked, bound to the operation, caller, and target (see the `api-context` skill). |
+| `ctx.clientCapabilities` | What the client declared for this request, `undefined` when no view exists. Decides whether to ask for optional context (e.g. roots); never a reason to skip a consent prompt. |
 | `ctx.enrich` | Success-path agent context (empty-result notices, query echo, pagination totals) — `ctx.enrich(...)` or `.notice()` / `.total()` / `.echo()` / `.truncated()`. Reaches `structuredContent` and `content[]`; lands only when the definition declares an `enrichment` block (no-op otherwise). |
 | `ctx.content` | Non-text content blocks — `.image(data, mimeType)`, `.audio(data, mimeType)`, or `ctx.content(block)` for a raw block. Prepended to `content[]` after `format()`; never enters `structuredContent`. |
 | `ctx.signal` | `AbortSignal` for cancellation. |
-| `ctx.requestId` | Unique request ID. |
+| `ctx.requestId` | Request ID — the one every log record of the call carries and its error envelope returns as `data.requestId`. |
 | `ctx.tenantId` | Tenant ID from JWT; `'default'` for stdio or HTTP with auth off. |
 
 ---
@@ -214,7 +215,7 @@ Handlers receive a unified `ctx` object. Key properties:
 
 Handlers throw — the framework catches, classifies, and formats.
 
-**Recommended: typed error contract.** Declare `errors: [{ reason, code, when, recovery, retryable?, severity?, thrownBy? }]` on `tool()` / `resource()` to receive `ctx.fail(reason, …)` typed against the reason union. TypeScript catches typos at compile time, `data.reason` is auto-populated for observability, linter enforces conformance against the handler body. `recovery` is required (≥ 5 words, lint-validated) — the single source of truth for the agent's next move. Pass `ctx.recoveryFor('reason')` as the throw's data to put it on the wire (`data.recovery.hint`, mirrored into `content[]` text unless the message already contains it verbatim); override with an explicit `{ recovery: { hint: '...' } }` when dynamic runtime context matters. Forwarding it is lint-enforced per throw site (`error-contract-recovery-unforwarded`). Mark an entry the service layer throws with `thrownBy: 'service'` so `error-contract-unthrown` skips it — lint-only metadata, nothing at runtime reads it. Baseline codes (`InternalError`, `ServiceUnavailable`, `Timeout`, `ValidationError`, `SerializationError`, `RequestCancelled`) bubble freely and don't need declaring.
+**Recommended: typed error contract.** Declare `errors: [{ reason, code, when, recovery, retryable?, severity?, thrownBy? }]` on `tool()` / `resource()` to receive `ctx.fail(reason, …)` typed against the reason union. TypeScript catches typos at compile time, `data.reason` is auto-populated for observability, linter enforces conformance against the handler body. `recovery` is required (≥ 5 words, lint-validated) — the single source of truth for the agent's next move. The framework puts it on the wire whenever a failure carrying that `reason` arrives without a hint — a bare `ctx.fail('reason')` or a service throw with `data: { reason }` — as `data.recovery.hint`, mirrored into `content[]` text unless the message already contains it verbatim; override with an explicit `{ recovery: { hint: '...' } }` when dynamic runtime context matters. Every error envelope also carries `data.requestId`, the id the server's log records for that call carry, and `content[]` closes with `(reason … · request <id>)`. Mark an entry the service layer throws with `thrownBy: 'service'` so `error-contract-unthrown` skips it — lint-only metadata, nothing at runtime reads it. Baseline codes (`InternalError`, `ServiceUnavailable`, `Timeout`, `ValidationError`, `SerializationError`, `RequestCancelled`) bubble freely and don't need declaring.
 
 ```ts
 import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
@@ -226,7 +227,7 @@ errors: [
 ],
 async handler(input, ctx) {
   const item = await db.find(input.id);
-  if (!item) throw ctx.fail('no_match', `No item ${input.id}`, ctx.recoveryFor('no_match'));
+  if (!item) throw ctx.fail('no_match', `No item ${input.id}`);
   return item;
 }
 ```

package/templates/Dockerfile

@@ -5,10 +5,10 @@
 # source code into JavaScript, and prepares the production assets.
 #
 # Pinned to $BUILDPLATFORM rather than the target platform: `bun run build` emits
-# JavaScript, and only `dist/` crosses into the production stage, which runs its
-# own target-arch install. Built for the target instead, the non-native leg of a
-# `--platform linux/amd64,linux/arm64` build runs under QEMU, where bun >= 1.4
-# aborts with a JavaScriptCore allocator assertion and fails the multi-arch push.
+# JavaScript, and only `dist/` crosses into the production stage. Built for the
+# target instead, the non-native leg of a `--platform linux/amd64,linux/arm64`
+# build runs under QEMU, where bun >= 1.4 aborts with a JavaScriptCore allocator
+# assertion and fails the multi-arch push.
 #
 # The constraint this assumes: the build stage produces platform-independent
 # output. A stage that compiles a native addon needs the target-arch toolchain
@@ -34,80 +34,97 @@ RUN bun run build
 
 
 # ==============================================================================
-# Production Stage
+# Production Dependencies Stage
 #
-# This stage creates a minimal, optimized, and secure image for running the
-# application. It uses a slim base image and only includes production
-# dependencies and build artifacts.
+# Installs the production dependency tree for the target platform. Every step
+# here can run JavaScript — bunfig.toml's security scanner runs as a Bun
+# program, and so does the OTel script — so the stage runs on $BUILDPLATFORM
+# and cross-installs with `--os`/`--cpu`, which pick each platform-specific
+# optional dependency (native bindings such as DuckDB's) for the target. Only
+# `node_modules` leaves this stage.
+#
+# A clean image rather than `FROM build`: the build stage's node_modules holds
+# devDependencies.
 # ==============================================================================
-FROM oven/bun:1.4.2-slim AS production
+FROM --platform=$BUILDPLATFORM oven/bun:1.4.2 AS deps
 
 WORKDIR /usr/src/app
 
-# Set the environment to production for performance and to ensure only
-# production dependencies are installed.
-ENV NODE_ENV=production
-
-# OCI image metadata (https://github.com/opencontainers/image-spec/blob/main/annotations.md)
-ARG APP_VERSION
-LABEL org.opencontainers.image.title="{{PACKAGE_NAME}}"
-LABEL org.opencontainers.image.description=""
-LABEL org.opencontainers.image.licenses="Apache-2.0"
-LABEL org.opencontainers.image.version="${APP_VERSION}"
-LABEL org.opencontainers.image.source=""
-
 # Copy dependency manifests. `bunfig.toml` rides along so every install below
 # passes its release-age gate and security scanner, as a local install does.
 COPY package.json bun.lock bunfig.toml ./
 
 # The scanner bunfig.toml names is a devDependency, and Bun installs a missing
 # scanner through the same production-filtered install, which omits it and
-# aborts. Seed it from the build stage's full install instead. Remove this line
-# together with the scanner if bunfig.toml stops naming one.
+# aborts. Seed it from the build stage's full install instead. Remove this line,
+# and the `rm` at the end of this stage, if bunfig.toml stops naming a scanner.
 COPY --from=build /usr/src/app/node_modules/@socketsecurity/bun-security-scanner ./node_modules/@socketsecurity/bun-security-scanner
 
+# Docker names the target architecture `amd64`/`arm64`; Bun's `--cpu` takes
+# `x64`/`arm64`. Mapped once here, read by both installs below. `oven/bun`
+# publishes only these two architectures, so any other target fails here.
+ARG TARGETOS
+ARG TARGETARCH
+RUN case "$TARGETARCH" in \
+      amd64) echo x64 ;; \
+      arm64) echo arm64 ;; \
+      *) echo "Unsupported TARGETARCH '$TARGETARCH': expected amd64 or arm64" >&2; exit 1 ;; \
+    esac > .bun-cpu
+
 # Install only production dependencies, ignoring any lifecycle scripts (like 'prepare')
 # that are not needed in the final production image.
 # `--omit=peer` drops the framework's optional peer tiers (test runner, service
 # SDKs, parsers) that Bun would otherwise auto-install. Anything this server
 # actually imports belongs in its own `dependencies`, so nothing needed at
-# runtime is lost. The OTEL step below carries the same flag — without it, that
-# install re-resolves the graph and pulls every optional peer back in.
+# runtime is lost.
 RUN --mount=type=cache,target=/root/.bun/install/cache \
-    bun install --production --omit=peer --frozen-lockfile --ignore-scripts
+    bun install --production --omit=peer --frozen-lockfile --ignore-scripts \
+      --os="$TARGETOS" --cpu="$(cat .bun-cpu)"
 
 # Conditionally install OpenTelemetry optional peer dependencies (Tier 3).
 # Installed by default. Omit them for a leaner image at build time
 # with: docker build --build-arg OTEL_ENABLED=false
-# Each package is requested at the range the installed framework declares in
-# `peerDependencies`, so the resolution stays inside the framework's tested
-# peer range; a name with no declared range fails the build.
+# The script reads the list and each range from the installed framework's
+# `peerDependencies` and passes the target flags on to its `bun install`.
+COPY scripts/install-otel.ts ./scripts/
 ARG OTEL_ENABLED=true
 RUN --mount=type=cache,target=/root/.bun/install/cache \
     if [ "$OTEL_ENABLED" = "true" ]; then \
-      specs=$(bun -e ' \
-        const { peerDependencies: peers } = await Bun.file("node_modules/@cyanheads/mcp-ts-core/package.json").json(); \
-        const names = process.argv.slice(1); \
-        const missing = names.filter((name) => !peers?.[name]); \
-        if (missing.length > 0) throw new Error(`no peerDependencies range for ${missing.join(", ")}`); \
-        console.log(names.map((name) => `${name}@${peers[name]}`).join(" ")); \
-      ' \
-        @hono/otel \
-        @opentelemetry/api-logs \
-        @opentelemetry/exporter-logs-otlp-http \
-        @opentelemetry/exporter-metrics-otlp-http \
-        @opentelemetry/exporter-trace-otlp-http \
-        @opentelemetry/instrumentation-http \
-        @opentelemetry/instrumentation-pino \
-        @opentelemetry/resources \
-        @opentelemetry/sdk-logs \
-        @opentelemetry/sdk-metrics \
-        @opentelemetry/sdk-node \
-        @opentelemetry/sdk-trace-node \
-        @opentelemetry/semantic-conventions) \
-      && bun add --omit=dev --omit=peer --ignore-scripts $specs; \
+      bun scripts/install-otel.ts --os="$TARGETOS" --cpu="$(cat .bun-cpu)"; \
     fi
 
+# The seeded scanner served only the installs above; keep it out of the image.
+RUN rm -rf node_modules/@socketsecurity/bun-security-scanner
+
+
+# ==============================================================================
+# Production Stage
+#
+# This stage creates a minimal, optimized, and secure image for running the
+# application. It uses a slim base image and only includes production
+# dependencies and build artifacts. Its only Bun invocations are HEALTHCHECK
+# and CMD, which run on the real target at container start.
+# ==============================================================================
+FROM oven/bun:1.4.2-slim AS production
+
+WORKDIR /usr/src/app
+
+# Set the environment to production for performance.
+ENV NODE_ENV=production
+
+# OCI image metadata (https://github.com/opencontainers/image-spec/blob/main/annotations.md)
+ARG APP_VERSION
+LABEL org.opencontainers.image.title="{{PACKAGE_NAME}}"
+LABEL org.opencontainers.image.description=""
+LABEL org.opencontainers.image.licenses="Apache-2.0"
+LABEL org.opencontainers.image.version="${APP_VERSION}"
+LABEL org.opencontainers.image.source=""
+
+# The manifest comes from the build context: the deps stage's copy was rewritten
+# by the OTel install, and the runtime reads only its name, version, and type.
+COPY package.json ./
+COPY --from=deps /usr/src/app/node_modules ./node_modules
+
 # Copy the compiled application code from the build stage
 COPY --from=build /usr/src/app/dist ./dist
 

package/templates/src/mcp-server/tools/definitions/echo.tool.ts

@@ -27,7 +27,8 @@ export const echoTool = tool('template_echo_message', {
   },
 
   // Declare each domain failure mode the agent should plan around. The framework
-  // types `ctx.fail(reason, …)` against the declared union. Baseline codes
+  // types `ctx.fail(reason, …)` against the declared union and puts the entry's
+  // `recovery` on both client surfaces when the throw carries none. Baseline codes
   // (InternalError, ServiceUnavailable, Timeout, ValidationError,
   // SerializationError) bubble freely — only declare domain-specific reasons.
   // Delete this block if no domain-specific failures apply to your tool.
@@ -42,13 +43,7 @@ export const echoTool = tool('template_echo_message', {
 
   handler(input, ctx) {
     if (input.message.trim().length === 0) {
-      // Spreading ctx.recoveryFor puts the declared recovery on the wire. Without
-      // it the hint reaches neither structuredContent nor content[].
-      throw ctx.fail(
-        'empty_message',
-        'Message must contain at least one non-whitespace character.',
-        { ...ctx.recoveryFor('empty_message') },
-      );
+      throw ctx.fail('empty_message', 'Message must contain at least one non-whitespace character.');
     }
     // Reaches both client surfaces with no format() plumbing.
     ctx.enrich({ characterCount: input.message.length });