@cyanheads/mcp-ts-core 0.13.9 → 0.13.11

package/scripts/lint-packaging.ts

@@ -69,12 +69,26 @@
  *      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`.
+ *  16. server.json npm launch shape: a registry client runs an npm entry as
+ *      `npx <identifier>@<version> <packageArguments>` with the entry's
+ *      `environmentVariables`, so the package's bin starts, never an npm
+ *      script. No npm entry may carry the positional `run` + `start:*` pair
+ *      (npm-script syntax the bin receives as ignored argv), and a
+ *      `streamable-http` npm entry must fix `MCP_TRANSPORT_TYPE` as
+ *      `"value": "http"` — absent, or only a user-editable `default`, the
+ *      server starts on stdio. Runs with or without `manifest.json`; skipped
+ *      when there is no `server.json` (issue #622).
  *
  * 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 +197,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,36 +813,268 @@ 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`,
     );
 }
 
+/** The environment entry a `streamable-http` npm package carries, as the mcp-ts-core scaffold writes it. */
+const HTTP_TRANSPORT_ENV =
+  '{ "name": "MCP_TRANSPORT_TYPE", "description": "Selects the HTTP transport.", "format": "string", "value": "http" }';
+
+/** An npm script name the `run` positional selects: `start` or `start:<variant>`. */
+const NPM_START_SCRIPT = /^start(?::|$)/;
+
+/** The `value` of a positional package argument; undefined for anything else. */
+function positionalValue(arg: unknown): string | undefined {
+  return isRecord(arg) && arg.type === 'positional' && typeof arg.value === 'string'
+    ? arg.value
+    : undefined;
+}
+
+/**
+ * Check 16: the launch shape of `server.json` npm entries. A registry client
+ * runs an npm entry as `npx <identifier>@<version> <packageArguments>` with the
+ * entry's `environmentVariables`, so the package's bin starts, never an npm
+ * script. A positional `run` followed by `start` or `start:<variant>` is
+ * npm-script syntax the bin receives as argv and ignores. The transport comes
+ * only from `MCP_TRANSPORT_TYPE`, so a `streamable-http` npm entry must fix it
+ * as `"value": "http"`: absent, it starts on stdio, and a `default` is
+ * user-editable. Entries of other registry types are left alone. Every error
+ * names the entry's index and the change that fixes it.
+ */
+export function checkServerJsonLaunch(serverJson: unknown): string[] {
+  const errors: string[] = [];
+  const packages =
+    isRecord(serverJson) && Array.isArray(serverJson.packages) ? serverJson.packages : [];
+
+  for (const [index, entry] of packages.entries()) {
+    if (!isRecord(entry) || entry.registryType !== 'npm') continue;
+    const label = `server.json packages[${index}]`;
+
+    const args: unknown[] = Array.isArray(entry.packageArguments) ? entry.packageArguments : [];
+    const runAt = args.findIndex(
+      (arg, i) =>
+        positionalValue(arg) === 'run' && NPM_START_SCRIPT.test(positionalValue(args[i + 1]) ?? ''),
+    );
+    if (runAt !== -1) {
+      errors.push(
+        `${label} packageArguments carry "run" "${positionalValue(args[runAt + 1])}" — npm-script ` +
+          'syntax: a registry client launches the entry as `npx <identifier>@<version> <packageArguments>`, ' +
+          "so the package's bin receives both as argv it ignores; remove both arguments",
+      );
+    }
+
+    if (!isRecord(entry.transport) || entry.transport.type !== 'streamable-http') continue;
+    const envVars: unknown[] = Array.isArray(entry.environmentVariables)
+      ? entry.environmentVariables
+      : [];
+    const transportVar = envVars.find((v) => isRecord(v) && v.name === 'MCP_TRANSPORT_TYPE');
+    if (!isRecord(transportVar)) {
+      errors.push(
+        `${label} (streamable-http) does not set MCP_TRANSPORT_TYPE, so the server it launches ` +
+          `starts on stdio; add ${HTTP_TRANSPORT_ENV} to its environmentVariables`,
+      );
+    } else if (transportVar.value === undefined) {
+      const reason =
+        transportVar.default === 'http'
+          ? '"default": "http" is user-editable, so the HTTP transport is not guaranteed'
+          : 'the server it launches starts on stdio';
+      errors.push(
+        `${label} (streamable-http) MCP_TRANSPORT_TYPE has no "value" — ${reason}; set "value": "http"`,
+      );
+    } else if (transportVar.value !== 'http') {
+      errors.push(
+        `${label} (streamable-http) MCP_TRANSPORT_TYPE "value" is "${String(transportVar.value)}" — ` +
+          'set it to "http"',
+      );
+    }
+  }
+
+  return errors;
+}
+
 /** Read `packaging.pluginManifests` from devcheck.config.json; default on. */
 function pluginManifestsEnabled(): boolean {
   const cfg = tryReadJson<{ packaging?: { pluginManifests?: boolean } }>(
@@ -846,6 +1092,7 @@ async function main(): Promise<void> {
     resolve('package.json'),
   );
   const unscopedName = pkg?.name?.split('/').pop();
+  const serverJson = tryReadJson<ServerJson>(resolve('server.json'));
 
   // ── Manifest-dependent checks (1–4 + manifest identity) ──
   const manifestPath = resolve('manifest.json');
@@ -878,7 +1125,6 @@ async function main(): Promise<void> {
 
     errors.push(...checkManifestUserConfigWiring(manifest));
 
-    const serverJson = tryReadJson<ServerJson>(resolve('server.json'));
     if (serverJson) {
       const manifestEnv = manifest.server?.mcp_config?.env ?? {};
       const manifestEnvKeys = new Set(Object.keys(manifestEnv));
@@ -922,6 +1168,11 @@ async function main(): Promise<void> {
     notes.push('No manifest.json — skipping manifest/server.json alignment checks.');
   }
 
+  // ── server.json npm launch shape (check 16) ──
+  if (serverJson) {
+    errors.push(...checkServerJsonLaunch(serverJson));
+  }
+
   // ── Bundle-content guard (checks 5–7) ──
   const mcpbignorePath = resolve('.mcpbignore');
   if (existsSync(mcpbignorePath)) {

package/scripts/prune-musl-packages.ts

@@ -0,0 +1,146 @@
+#!/usr/bin/env bun
+/**
+ * @fileoverview Deletes musl-only packages from a production `node_modules` —
+ * the Dockerfile `deps` stage's step after the OTel install.
+ *
+ * `bun install --os/--cpu` has no libc filter, so an optional dependency
+ * published in glibc and musl variants installs both: DuckDB's native
+ * bindings add a ~70 MB musl copy per image. The runtime image
+ * (`oven/bun:<version>-slim`) is Debian, glibc, and never loads it. Every
+ * installed package whose own `package.json` `libc` lists `musl` and not
+ * `glibc` is deleted, at any depth — hoisted, scoped, nested `node_modules`,
+ * and Bun's isolated `node_modules/.bun` store — along with each symlink that
+ * pointed into it. The manifest decides, never the package name. A later
+ * `bun install` restores what this removes, so it runs after every install.
+ * A server whose runtime image is musl-based (Alpine) drops the step.
+ *
+ * @example
+ * // In the Dockerfile deps stage, after the OTel step:
+ * // bun scripts/prune-musl-packages.ts
+ * @module scripts/prune-musl-packages
+ */
+import { existsSync, readdirSync, readFileSync, readlinkSync, rmSync } from 'node:fs';
+import { dirname, join, relative, resolve, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+interface Manifest {
+  libc?: string | string[];
+  name: string;
+  version: string;
+}
+
+/** An installed package the prune deleted. */
+export interface PrunedPackage {
+  /** Absolute path of the deleted package directory. */
+  dir: string;
+  name: string;
+  version: string;
+}
+
+/** What one prune deleted. */
+export interface PruneResult {
+  removed: PrunedPackage[];
+  /** Absolute paths of the symlinks removed because they pointed into a deleted package. */
+  unlinked: string[];
+}
+
+/** True when a manifest's `libc` admits musl and not glibc — a package a glibc runtime cannot load. */
+export function isMuslOnly(manifest: Pick<Manifest, 'libc'>): boolean {
+  const libc = [manifest.libc ?? []].flat();
+  return libc.includes('musl') && !libc.includes('glibc');
+}
+
+/**
+ * Deletes every musl-only package under `nodeModules`, plus the symlinks into
+ * them. Symlinks are never followed, so each package is visited once, at its
+ * real directory.
+ */
+export function pruneMuslPackages(nodeModules: string): PruneResult {
+  const removed: PrunedPackage[] = [];
+  const links: string[] = [];
+
+  const visitPackage = (dir: string): void => {
+    const manifestPath = join(dir, 'package.json');
+    if (!existsSync(manifestPath)) return;
+    const manifest = JSON.parse(readFileSync(manifestPath, 'utf8')) as Manifest;
+    if (isMuslOnly(manifest)) {
+      removed.push({ dir, name: manifest.name, version: manifest.version });
+      return;
+    }
+    const nested = join(dir, 'node_modules');
+    if (existsSync(nested)) scanNodeModules(nested);
+  };
+
+  /** Visits each package position of a `node_modules` directory: `<name>` and `@scope/<name>`. */
+  const scanNodeModules = (dir: string): void => {
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+      const path = join(dir, entry.name);
+      if (entry.isSymbolicLink()) links.push(path);
+      else if (!entry.isDirectory()) continue;
+      else if (entry.name === '.bun') scanBunStore(path);
+      else if (entry.name.startsWith('@')) {
+        for (const scoped of readdirSync(path, { withFileTypes: true })) {
+          const scopedPath = join(path, scoped.name);
+          if (scoped.isSymbolicLink()) links.push(scopedPath);
+          else if (scoped.isDirectory()) visitPackage(scopedPath);
+        }
+      } else if (!entry.name.startsWith('.')) visitPackage(path);
+    }
+  };
+
+  /** Bun's isolated store: `.bun/<entry>/node_modules` per package, plus the hoisted `.bun/node_modules`. */
+  const scanBunStore = (store: string): void => {
+    for (const entry of readdirSync(store, { withFileTypes: true })) {
+      if (!entry.isDirectory()) continue;
+      const modules =
+        entry.name === 'node_modules'
+          ? join(store, entry.name)
+          : join(store, entry.name, 'node_modules');
+      if (existsSync(modules)) scanNodeModules(modules);
+    }
+  };
+
+  scanNodeModules(nodeModules);
+
+  const insideRemoved = (target: string): boolean =>
+    removed.some(({ dir }) => target === dir || target.startsWith(`${dir}${sep}`));
+  const unlinked = links.filter((path) =>
+    insideRemoved(resolve(dirname(path), readlinkSync(path))),
+  );
+  for (const { dir } of removed) rmSync(dir, { recursive: true, force: true });
+  for (const path of unlinked) rmSync(path);
+  return { removed, unlinked };
+}
+
+function main(): number {
+  const nodeModules = join(process.cwd(), 'node_modules');
+  if (!existsSync(nodeModules)) {
+    console.error(
+      `prune-musl-packages: ${nodeModules} does not exist — run it from the project root after bun install.`,
+    );
+    return 1;
+  }
+
+  const { removed, unlinked } = pruneMuslPackages(nodeModules);
+  if (removed.length === 0) {
+    console.log('prune-musl-packages: no musl-only packages in node_modules.');
+    return 0;
+  }
+  const plural = (count: number, noun: string) => `${count} ${noun}${count === 1 ? '' : 's'}`;
+  console.log(
+    `prune-musl-packages: removed ${plural(removed.length, 'musl-only package')} a glibc runtime cannot load:`,
+  );
+  for (const { dir, name, version } of removed) {
+    console.log(`  ${name}@${version} (${relative(process.cwd(), dir)})`);
+  }
+  if (unlinked.length > 0) {
+    console.log(
+      `prune-musl-packages: removed ${plural(unlinked.length, 'symlink')} into those packages.`,
+    );
+  }
+  return 0;
+}
+
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  process.exit(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/.github/workflows/codeql.yml

@@ -2,6 +2,9 @@
 # Verification (typecheck, lint, tests) is local; this file exists because CodeQL
 # is GitHub-owned end to end and a workflow file is visible in the repo where a
 # repo-level "default setup" is not. Default setup must be OFF for this to run.
+# Each language uploads under `/language:<language>`, default setup's category.
+# GitHub re-evaluates an alert only through analyses in the alert's own
+# category, so alerts default setup raised close here once the code is fixed.
 name: CodeQL
 
 on:
@@ -24,6 +27,10 @@ jobs:
       security-events: write
       contents: read
       actions: read
+    strategy:
+      fail-fast: false
+      matrix:
+        language: [actions, javascript-typescript]
 
     steps:
       - name: Checkout repository
@@ -32,8 +39,10 @@ jobs:
       - name: Initialize CodeQL
         uses: github/codeql-action/init@v4
         with:
-          languages: javascript-typescript, actions
+          languages: ${{ matrix.language }}
           build-mode: none
 
       - name: Perform CodeQL Analysis
         uses: github/codeql-action/analyze@v4
+        with:
+          category: /language:${{ matrix.language }}

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