@cyanheads/mcp-ts-core 0.13.8 → 0.13.10

package/scripts/release-github.ts

@@ -18,6 +18,15 @@
  * The framework itself has no `manifest.json`/`.mcpb`, so the attach path is
  * skipped here but scaffolded servers that do have a manifest get the full flow.
  *
+ * Before any `gh` call it validates the tag — `--notes-from-tag` publishes the
+ * message verbatim as the release body, so a malformed tag becomes a malformed
+ * public release. `--check` runs only that validation, for use right after
+ * `git tag -a` and before the tag is pushed. The rules are the ones the
+ * `release-and-publish` skill states for the annotation: an annotated tag, a
+ * subject of at most 72 characters with no version and no `;`, flat bullets
+ * with no section headers, no signature block leaked into the body, and the
+ * `[CHANGELOG v<version>](…)` link as the final line.
+ *
  * @module scripts/release-github
  *
  * @example
@@ -25,6 +34,10 @@
  * // bun run release:github
  *
  * @example
+ * // Validate the tag annotation only (exit 1 on a violation, no gh calls):
+ * // bun run release:github -- --check
+ *
+ * @example
  * // Dry-run — print the command that would be executed without running it:
  * // bun run release:github -- --dry-run
  */
@@ -33,8 +46,86 @@ import { spawnSync } from 'node:child_process';
 import { existsSync, readFileSync } from 'node:fs';
 import { resolve } from 'node:path';
 import process from 'node:process';
+import { fileURLToPath } from 'node:url';
 
 const DRY_RUN = process.argv.includes('--dry-run');
+const CHECK_ONLY = process.argv.includes('--check');
+
+/** A tag subject longer than this reads as a digest, not a release title. */
+const MAX_SUBJECT_LENGTH = 72;
+
+/**
+ * Section headers belong in the changelog entry, never in the tag body: a
+ * markdown heading, a Keep a Changelog section name, or any other line that is
+ * not a bullet and ends in a colon (`Dependency bumps:`, `Highlights:`).
+ */
+const SECTION_HEADER =
+  /^(?:#{1,6}\s.*|(?:Added|Changed|Deprecated|Removed|Fixed|Security|Dependencies)\s*:?|[^\s\-*+[].*:)$/;
+
+/** The parts of an annotated tag that become the GitHub Release title and body. */
+export interface TagMessage {
+  body: string;
+  /** `git for-each-ref %(objecttype)` — `tag` for an annotated tag, `commit` for a lightweight one. */
+  objectType: string;
+  subject: string;
+}
+
+/**
+ * Validates a tag annotation against the release-body rules. Returns one
+ * message per violation; an empty array means the tag is publishable.
+ */
+export function checkTagMessage(tag: TagMessage, version: string): string[] {
+  if (tag.objectType !== 'tag') {
+    return [
+      `v${version} is a lightweight tag — recreate it annotated: git tag -a v${version} -F <file>`,
+    ];
+  }
+
+  const errors: string[] = [];
+  const { subject } = tag;
+  if (subject.length > MAX_SUBJECT_LENGTH) {
+    errors.push(
+      `subject is ${subject.length} characters — keep it one short theme (≤${MAX_SUBJECT_LENGTH}); the bullets carry the digest`,
+    );
+  }
+  if (subject.includes(version)) {
+    errors.push(
+      `subject contains the version "${version}" — GitHub prepends "v${version}:" to the title`,
+    );
+  }
+  if (subject.includes(';')) {
+    errors.push('subject contains ";" — one theme, not a list of changes');
+  }
+
+  if (tag.body.includes('-----BEGIN')) {
+    errors.push(
+      'body contains a signature block — the signature did not parse (usually --cleanup=verbatim); recreate the tag with --cleanup=whitespace before it is pushed',
+    );
+  }
+
+  const lines = tag.body
+    .split('\n')
+    .map((line) => line.trim())
+    .filter((line) => line.length > 0);
+  const headers = lines.filter((line) => SECTION_HEADER.test(line));
+  if (headers.length > 0) {
+    errors.push(
+      `body has section headers (${headers.map((h) => `"${h}"`).join(', ')}) — flat bullets only; sections belong in the changelog entry`,
+    );
+  }
+
+  const escaped = version.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const changelogLink = new RegExp(
+    `^\\[CHANGELOG v${escaped}\\]\\(\\S+/changelog/\\d+\\.\\d+\\.x/${escaped}\\.md\\)`,
+  );
+  if (!changelogLink.test(lines.at(-1) ?? '')) {
+    errors.push(
+      `final line is not the changelog link — end the body with "[CHANGELOG v${version}](https://github.com/<OWNER>/<REPO>/blob/main/changelog/<major.minor>.x/${version}.md)"`,
+    );
+  }
+
+  return errors;
+}
 
 // ── Helpers ───────────────────────────────────────────────────────────────────
 
@@ -107,15 +198,34 @@ function main(): void {
   if (!subject) {
     console.error(
       `Tag ${tag} not found locally or has no subject line. ` +
-        `Create the annotated tag first: git tag -a ${tag} -m "..."`,
+        `Create the annotated tag first: git tag -a ${tag} -F <file>`,
     );
     process.exit(1);
   }
 
+  // 3. Validate the annotation — it becomes the public release body verbatim
+  const errors = checkTagMessage(
+    {
+      subject,
+      body: run('git', ['for-each-ref', `refs/tags/${tag}`, '--format=%(contents:body)']),
+      objectType: run('git', ['for-each-ref', `refs/tags/${tag}`, '--format=%(objecttype)']),
+    },
+    version,
+  );
+  if (errors.length > 0) {
+    console.error(`Tag ${tag} is not publishable:`);
+    for (const error of errors) console.error(`  ✗ ${error}`);
+    process.exit(1);
+  }
+  if (CHECK_ONLY) {
+    console.log(`Tag ${tag} OK.`);
+    return;
+  }
+
   const title = `${tag}: ${subject}`;
   const hasMcpb = existsSync('manifest.json');
 
-  // 3. Build the gh release create command
+  // 4. Build the gh release create command
   const createArgs = [
     'release',
     'create',
@@ -152,7 +262,7 @@ function main(): void {
     console.log('  asset: dist/*.mcpb');
   }
 
-  // 4. Try to create the release
+  // 5. Try to create the release
   const createResult = gh(createArgs, { required: false });
 
   if (!createResult.startsWith('__ERROR__:')) {
@@ -170,7 +280,7 @@ function main(): void {
     process.exit(1);
   }
 
-  // 5. Release already exists — repair: upload asset (if applicable) and set title.
+  // 6. Release already exists — repair: upload asset (if applicable) and set title.
   console.log(`Release ${tag} already exists. Repairing…`);
 
   if (hasMcpb) {
@@ -184,4 +294,6 @@ function main(): void {
   console.log(`Release ${tag} repaired.`);
 }
 
-main();
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  main();
+}

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/_.mcpbignore

@@ -3,6 +3,8 @@
 /.claude/
 /.agents/
 /framework-skills/
+/docs/idea.md
+/logs/
 /Dockerfile
 /bun.lock
 /bunfig.toml

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 });