@cyanheads/mcp-ts-core 0.13.0 → 0.13.2

package/framework-skills/release-and-publish/SKILL.md

@@ -4,7 +4,7 @@ description: >
   Ship a release end-to-end across every registry the project targets (npm, MCP Registry, GitHub Releases for `.mcpb` bundles, GHCR). Runs the final verification gate, fast-forwards `main` when the release rode a release PR, creates the annotated tag on the commit `main` now points at, pushes commits and tags, then publishes to each applicable destination. Assumes git wrapup (version bumps, changelog, commit stack — and in release PR mode, the pushed branch and open PR) is already complete — this skill is the post-wrapup merge + tag + publish workflow. Retries transient network failures on publish steps; halts with a partial-state report when retries are exhausted or the failure is terminal.
 metadata:
   author: cyanheads
-  version: "2.16"
+  version: "2.17"
   audience: external
   type: workflow
 ---
@@ -111,12 +111,15 @@ If `--ff-only` refuses, `main` moved underneath the release branch. Halt and rep
 The tag goes on HEAD. In release PR mode that is `main`'s tip after step 3 — the commit the PR's `headRefOid` names — so the tag is created on the branch it stays reachable from.
 
 ```bash
-git tag -a v<version> --cleanup=whitespace -m "<tag message with embedded newlines>"
+cat > /tmp/tag-v<version>.md <<'TAG'
+<tag message>
+TAG
+git tag -a v<version> --cleanup=whitespace -F /tmp/tag-v<version>.md
 ```
 
 If `v<version>` already exists and points at HEAD, a prior run created it — proceed. If it exists and points anywhere else, **halt and report the conflict** with the version string, the existing tag SHA, and HEAD. Never delete or move a tag without explicit authorization.
 
-Use `-m` with embedded newlines in the string (plain `-m` only — no heredoc, no command substitution). The tag message renders as the GitHub Release body via `--notes-from-tag`. It must be structured markdown, not a flat string.
+Write the message to a file through a quoted-delimiter heredoc and pass it with `-F`, never inline with `-m`: the body carries backticks, which a double-quoted string runs as command substitution and silently deletes, and apostrophes, which end a single-quoted string. The tag message renders as the GitHub Release body via `--notes-from-tag`. It must be structured markdown, not a flat string.
 
 **Release PR mode: the tag body is the PR body's `## Changes` bullets plus its final changelog link, verbatim** — `gh pr view <N> --json body -q .body` (`<N>` from step 1 — on `main` there is no branch for `gh` to infer it from), take the theme line as the subject, the bullets under `## Changes`, and the last line; drop `## Gates` and the headers. That digest was authored at wrapup and reviewed on the PR; re-authoring it here would publish unreviewed words. The one addition: append ` · release PR #<N>` to that final line, so the GitHub Release points at its audit trail (GitHub autolinks the bare `#<N>`). Without a PR, author it from the changelog entry at `changelog/<major.minor>.x/<version>.md` — every claim in the tag must appear in that file, and the file's `summary:` line is the tag's theme.
 
@@ -193,10 +196,16 @@ Halt on publish error other than "version already exists" (which means this step
 
 Only if `server.json` exists at the repo root (otherwise skip). Note: `server.json` (MCP Registry metadata) and `manifest.json` (MCPB bundle manifest, step 8) are independent — a project may have either, both, or neither.
 
+The registry checks that the npm version exists before it registers, and npm's read endpoint can lag `bun publish` by several minutes. Wait for the version to be served before publishing; a publisher error saying the npm version was not found is this lag, not a terminal failure:
+
 ```bash
+curl -sf --retry 30 --retry-delay 30 --retry-all-errors -o /dev/null \
+  "https://registry.npmjs.org/<package-name>/<version>"
 bun run publish-mcp
 ```
 
+Step 8 depends only on the pushed tag, so it may run while this wait is in progress.
+
 If `publish-mcp` isn't defined in `package.json`, add it permanently (one-time setup, macOS):
 
 ```json

package/framework-skills/report-issue-framework/SKILL.md

@@ -4,7 +4,7 @@ description: >
   File a bug or feature request against @cyanheads/mcp-ts-core when you hit a framework issue. Use when a builder, utility, context method, or config behaves contrary to the documented API — not for server-specific application bugs.
 metadata:
   author: cyanheads
-  version: "1.10"
+  version: "1.11"
   audience: external
   type: workflow
 ---
@@ -181,6 +181,7 @@ Every issue needs exactly one primary label. Stack secondary labels on top when
 | `performance` | Memory, CPU, latency, or resource usage |
 | `security` | Vulnerability, CVE, or hardening work |
 | `breaking-change` | Fix/feature will break public API; requires a major bump |
+| `blocked-by-sdk` | Fix requires changes in `@modelcontextprotocol/sdk` |
 | `surplus-token-idea` | Worth exploring when token budget allows |
 
 Combine labels: `--label "bug" --label "regression"`.

package/framework-skills/report-issue-local/SKILL.md

@@ -4,7 +4,7 @@ description: >
   File a bug or feature request against this MCP server's own repo. Use for server-specific issues — tool logic, service integrations, config problems, or domain bugs that aren't caused by the framework.
 metadata:
   author: cyanheads
-  version: "1.8"
+  version: "1.9"
   audience: external
   type: workflow
 ---
@@ -165,8 +165,12 @@ Every issue needs exactly one primary label. Stack secondary labels on top when
 | `performance` | Memory, CPU, latency, or resource usage |
 | `security` | Vulnerability, CVE, or hardening work |
 | `breaking-change` | Change will break public API; requires a major bump |
+| `blocked-by-framework` | Fix requires a released change in `@cyanheads/mcp-ts-core`; pairs with a `Depends on: cyanheads/mcp-ts-core#N` line in the body |
+| `blocked-by-sdk` | Fix requires changes in `@modelcontextprotocol/sdk` |
 | `surplus-token-idea` | Worth exploring when token budget allows |
 
+`blocked-by-framework` comes off when this server adopts the release that ships the fix. An issue blocked on the SDK *through* the framework takes `blocked-by-framework`, not `blocked-by-sdk` — the server's own unblock is still a framework release.
+
 Combine labels: `--label "bug" --label "regression"`.
 
 Secondary labels are not GitHub defaults — if `gh issue create --label "regression"` fails with `label not found`, create it once:
@@ -176,6 +180,8 @@ gh label create regression --color e99695 --description "Worked before, broken a
 gh label create performance --color 5319e7 --description "Memory, CPU, latency, or resource usage"
 gh label create security --color b60205 --description "Vulnerability, CVE, or hardening work"
 gh label create breaking-change --color d93f0b --description "Change will break public API; requires a major bump"
+gh label create blocked-by-framework --color fbca04 --description "Fix requires a released change in @cyanheads/mcp-ts-core"
+gh label create blocked-by-sdk --color c5def5 --description "Fix requires changes in @modelcontextprotocol/sdk"
 gh label create surplus-token-idea --color FF10F0 --description "Worth exploring when token budget allows"
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cyanheads/mcp-ts-core",
-  "version": "0.13.0",
+  "version": "0.13.2",
   "mcpName": "io.github.cyanheads/mcp-ts-core",
   "description": "Agent-native TypeScript framework for MCP servers. Includes runtime infrastructure and agent skills for building, testing, and shipping servers.",
   "files": [
@@ -25,7 +25,7 @@
     "templates/",
     "AGENTS.md",
     "CLAUDE.md",
-    "tsconfig.base.json",
+    "config/tsconfig.base.json",
     "vitest.config.base.mjs",
     "biome.json"
   ],
@@ -123,7 +123,7 @@
       "import": "./dist/testing/vitest.js",
       "default": "./dist/testing/vitest.js"
     },
-    "./tsconfig.base.json": "./tsconfig.base.json",
+    "./tsconfig.base.json": "./config/tsconfig.base.json",
     "./vitest.config": "./vitest.config.base.mjs",
     "./biome": "./biome.json",
     "./package.json": "./package.json"
@@ -163,8 +163,8 @@
     "format": "biome check --write .",
     "format:unsafe": "biome check --write --unsafe .",
     "typecheck": "bunx tsc --noEmit",
-    "typecheck:scripts": "bunx tsc --project tsconfig.scripts.json --noEmit",
-    "typecheck:worker": "bunx tsc --project tsconfig.worker.json --noEmit",
+    "typecheck:scripts": "bunx tsc --project config/tsconfig.scripts.json --noEmit",
+    "typecheck:worker": "bunx tsc --project config/tsconfig.worker.json --noEmit",
     "list-skills": "bun run scripts/list-skills.ts",
     "tree": "bun run scripts/tree.ts",
     "fetch-spec": "bun run scripts/fetch-openapi-spec.ts",
@@ -234,7 +234,7 @@
     "js-yaml": "^5.4.1",
     "linkedom": "^0.18.13",
     "node-cron": "^4.6.0",
-    "openai": "^7.10.0",
+    "openai": "^7.15.0",
     "papaparse": "^5.7.0",
     "partial-json": "^0.1.7",
     "pdf-lib": "^1.17.1",
@@ -309,7 +309,7 @@
     "hono": "^4.13.7",
     "jose": "^6.2.12",
     "pino": "^10.3.1",
-    "zod": "^4.6.1"
+    "zod": "^4.6.2"
   },
   "peerDependencies": {
     "@duckdb/node-api": "^1.5.5-r.1",

package/scripts/build.ts

@@ -14,7 +14,7 @@
  */
 
 import { execFile } from 'node:child_process';
-import { readFileSync } from 'node:fs';
+import { existsSync, readFileSync } from 'node:fs';
 import { readdir, stat } from 'node:fs/promises';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -22,6 +22,32 @@ import { fileURLToPath } from 'node:url';
 const ROOT_DIR = join(dirname(fileURLToPath(import.meta.url)), '..');
 const DIST_DIR = join(ROOT_DIR, 'dist');
 
+/** Where `bunx @cyanheads/mcp-ts-core init` writes the build tsconfig. */
+const SCAFFOLD_BUILD_PROJECT = 'tsconfig.build.json';
+
+/**
+ * Build tsconfig locations, in precedence order. A project may keep its project
+ * tsconfigs in `config/` or at the root, and this script ships to both
+ * verbatim, so the default is probed rather than hardcoded.
+ */
+const BUILD_PROJECT_CANDIDATES = ['config/tsconfig.build.json', SCAFFOLD_BUILD_PROJECT];
+
+/**
+ * The tsconfig to build: an explicit `--project <path>` verbatim — a missing
+ * one still reaches the compiler and fails there — otherwise the first
+ * candidate location present. With neither present the scaffold's layout is
+ * named, so the compiler error points at the file the project should have.
+ */
+function resolveProject(argv: string[]): string {
+  const flagIndex = argv.indexOf('--project');
+  const explicit = flagIndex === -1 ? undefined : argv[flagIndex + 1];
+  if (explicit !== undefined) return explicit;
+  return (
+    BUILD_PROJECT_CANDIDATES.find((candidate) => existsSync(join(ROOT_DIR, candidate))) ??
+    SCAFFOLD_BUILD_PROJECT
+  );
+}
+
 async function exec(
   cmd: string[],
   label: string,
@@ -92,11 +118,7 @@ function formatBytes(bytes: number): string {
 async function main() {
   // Read package info
   const pkg = JSON.parse(readFileSync(join(ROOT_DIR, 'package.json'), 'utf-8'));
-  const projectIdx = process.argv.indexOf('--project');
-  const project =
-    projectIdx !== -1
-      ? (process.argv[projectIdx + 1] ?? 'tsconfig.build.json')
-      : 'tsconfig.build.json';
+  const project = resolveProject(process.argv);
 
   console.log(`\x1b[1mBuilding ${pkg.name}@${pkg.version}\x1b[0m`);
   console.log(`\x1b[2m  tsconfig: ${project}\x1b[0m`);

package/scripts/clean-mcpb.ts

@@ -33,7 +33,10 @@ import { fileURLToPath } from 'node:url';
 /**
  * Agent-doc entries under `node_modules/` that must not ship in a bundle.
  * KEEP IN SYNC with `AGENT_DOC_ENTRY` in `scripts/lint-packaging.ts`
- * (post-bundle content check) — a unit test asserts the two are identical.
+ * (post-bundle content check) — edit both literals together. The assertion that
+ * they match lives in the mcp-ts-core repository's own test suite; `tests/` is
+ * not part of the published package, so nothing enforces the pair in a server
+ * these scripts were copied into.
  */
 export const AGENT_DOC_ENTRY =
   /^node_modules\/.*(?:\/framework-skills\/|\/skills\/|\/\.claude\/|\/\.agents\/|\/SKILL\.md$)/;
@@ -41,7 +44,10 @@ export const AGENT_DOC_ENTRY =
 /**
  * Platform-specific native binding packages, which must not ship in a bundle.
  * KEEP IN SYNC with `NATIVE_BINDING_ENTRY` in `scripts/lint-packaging.ts`
- * (post-bundle content check) — a unit test asserts the two are identical.
+ * (post-bundle content check) — edit both literals together. The assertion that
+ * they match lives in the mcp-ts-core repository's own test suite; `tests/` is
+ * not part of the published package, so nothing enforces the pair in a server
+ * these scripts were copied into.
  *
  * `mcpb pack` archives the whole project directory, so a native dependency
  * contributes the build host's platform slice and nothing else — for

package/scripts/clean.ts

@@ -1,12 +1,16 @@
 /**
  * @fileoverview Utility script to clean build artifacts and temporary directories.
  * @module scripts/clean
- *   By default, it removes the 'dist' and 'logs' directories.
- *   Custom directories can be specified as command-line arguments.
+ *   By default, it removes the 'dist' and 'logs' directories plus every
+ *   TypeScript build-info file the project's tsconfigs write — in the root and
+ *   in 'config/', where a tsconfig kept there resolves its relative
+ *   `tsBuildInfoFile` against itself.
+ *   Custom directories can be specified as command-line arguments, which
+ *   replace the default set entirely.
  *   Works on all platforms using Node.js path normalization.
  *
  * @example
- * // Default directories (dist, logs):
+ * // Default targets (dist, logs, build info):
  * // bun run scripts/clean.ts
  *
  * // Custom directories:
@@ -21,6 +25,38 @@ interface CleanResult {
   status: 'cleaned' | 'skipped' | 'error';
 }
 
+/**
+ * A TypeScript build-info file: the plain `.tsbuildinfo`, a `<name>.tsbuildinfo`,
+ * and the lane-suffixed `.tsbuildinfo.<lane>` forms a multi-tsconfig project
+ * writes (`tsBuildInfoFile: ".tsbuildinfo.worker"`).
+ */
+const BUILD_INFO_FILE = /\.tsbuildinfo(\.[^.]*)?$/;
+
+/**
+ * Directories a tsconfig may write its build info into. A `tsBuildInfoFile` is
+ * resolved against the tsconfig that declares it, so a project keeping its
+ * tsconfigs in `config/` leaves build info there rather than at the root.
+ */
+const BUILD_INFO_DIRS = ['.', 'config'];
+
+/** Every build-info file under the scanned directories, as root-relative paths. */
+async function findBuildInfoFiles(root: string): Promise<string[]> {
+  const found = await Promise.all(
+    BUILD_INFO_DIRS.map(async (dir) => {
+      let entries: string[];
+      try {
+        entries = await readdir(resolve(root, dir));
+      } catch {
+        return []; // directory absent — nothing to clean there
+      }
+      return entries
+        .filter((entry) => BUILD_INFO_FILE.test(entry))
+        .map((entry) => (dir === '.' ? entry : `${dir}/${entry}`));
+    }),
+  );
+  return found.flat();
+}
+
 /**
  * Validates that a resolved path stays within the project root.
  * Rejects absolute paths, '..' traversal, and paths that escape cwd.
@@ -46,7 +82,7 @@ const clean = async (): Promise<void> => {
   try {
     const root = process.cwd();
     const args = process.argv.slice(2);
-    const buildInfoFiles = (await readdir(root)).filter((f) => f.endsWith('.tsbuildinfo'));
+    const buildInfoFiles = await findBuildInfoFiles(root);
     const dirsToClean = [...new Set(args.length > 0 ? args : ['dist', 'logs', ...buildInfoFiles])];
 
     console.log(`Cleaning directories: ${dirsToClean.join(', ')}`);

package/scripts/devcheck.ts

@@ -624,6 +624,13 @@ function classifyAuditVulns(output: string): { direct: string[]; upstream: strin
 // Define file extensions for linting and formatting
 const LINT_EXTS = ['.ts', '.tsx', '.js', '.jsx'];
 
+/**
+ * Worker tsconfig locations, in precedence order. A project keeps its project
+ * tsconfigs in `config/` or at the root — the `init` scaffold writes the root
+ * form — and this script ships to both verbatim.
+ */
+const WORKER_PROJECT_CANDIDATES = ['config/tsconfig.worker.json', 'tsconfig.worker.json'];
+
 const ALL_CHECKS: Check[] = [
   // Fast checks first (local operations, no network)
   {
@@ -703,18 +710,23 @@ const ALL_CHECKS: Check[] = [
     flag: '--no-packaging',
     canFix: false,
     // Validates env var alignment between manifest.json (MCPB bundle) and
-    // server.json (MCP Registry), plus plugin marketplace manifests (#240), and
-    // the bundle-content guards on .mcpbignore (#343). Runs when any of those
-    // inputs is present; skipped cleanly when none exist — consumers on an
-    // HTTP-only deploy are unaffected.
+    // server.json (MCP Registry), plus plugin marketplace manifests (#240), the
+    // bundle-content guards on .mcpbignore (#343), and the README version badge
+    // (#418). Runs when any of those inputs is present; skipped cleanly when
+    // none exist — consumers on an HTTP-only deploy are unaffected. README.md is
+    // a trigger in its own right: the badge check must gate a project that
+    // carries no bundle or plugin metadata at all, which the other three inputs
+    // only covered incidentally.
     getCommand: () => {
-      const hasManifest = existsSync(path.join(ROOT_DIR, 'manifest.json'));
-      const hasPluginManifest =
-        existsSync(path.join(ROOT_DIR, '.claude-plugin/plugin.json')) ||
-        existsSync(path.join(ROOT_DIR, '.codex-plugin/plugin.json')) ||
-        existsSync(path.join(ROOT_DIR, '.codex-plugin/mcp.json'));
-      const hasMcpbIgnore = existsSync(path.join(ROOT_DIR, '.mcpbignore'));
-      if (!hasManifest && !hasPluginManifest && !hasMcpbIgnore) return null;
+      const inputs = [
+        'manifest.json',
+        '.claude-plugin/plugin.json',
+        '.codex-plugin/plugin.json',
+        '.codex-plugin/mcp.json',
+        '.mcpbignore',
+        'README.md',
+      ];
+      if (!inputs.some((input) => existsSync(path.join(ROOT_DIR, input)))) return null;
       return ['bun', 'run', 'scripts/lint-packaging.ts'];
     },
     tip: (c) =>
@@ -864,14 +876,20 @@ const ALL_CHECKS: Check[] = [
     canFix: false,
     // The workerd type environment is its own program: Cloudflare's ambient
     // globals cannot share one with @types/node's (#397). It reads the built
-    // declarations, so it only has something to check after a build.
+    // declarations, so it only has something to check after a build. The
+    // tsconfig is looked for in both supported layouts — `config/` and the
+    // project root, which is where the `init` scaffold writes its tsconfigs
+    // (#440) — and the step skips only when neither carries one.
     getCommand: (ctx) => {
-      if (!existsSync(path.join(ctx.rootDir, 'tsconfig.worker.json'))) return null;
+      const project = WORKER_PROJECT_CANDIDATES.find((candidate) =>
+        existsSync(path.join(ctx.rootDir, candidate)),
+      );
+      if (!project) return null;
       if (!existsSync(path.join(ctx.rootDir, 'dist'))) return null;
       return [
         path.join(ctx.rootDir, 'node_modules', '.bin', 'tsc'),
         '--project',
-        'tsconfig.worker.json',
+        project,
         '--noEmit',
       ];
     },
@@ -1030,8 +1048,21 @@ const UI = {
     return `${c.bold(c.yellow(`🔶 Skipping ${check.name}...`))}${c.dim(` (${reason})`)}`;
   },
 
+  /**
+   * The running-log line for a finished step. A result `isSuccess` demoted to a
+   * warning is reported as one here too, on `printSummary`'s own guard
+   * (`exitCode === 0 && warning`), so the two surfaces cannot disagree about a
+   * single outcome (#344). A `{ success: false, warning }` return keeps its
+   * non-zero exit and so still renders as a failure.
+   */
   formatCheckResult(result: CommandResult, _mode: UIMode): string {
-    const { checkName, exitCode, duration } = result;
+    const { checkName, exitCode, duration, warning } = result;
+    if (exitCode === 0 && warning) {
+      return [
+        `${c.bold(c.yellow('⚠️'))} ${c.yellow(checkName)} ${c.yellow(`finished with a warning in ${duration}ms.`)}`,
+        c.yellow(warning.replace(/^/gm, '   | ')),
+      ].join('\n');
+    }
     if (exitCode === 0) {
       return `${c.bold(c.green('✅'))} ${c.yellow(checkName)} ${c.green(`finished successfully in ${duration}ms.`)}`;
     }

package/scripts/lint-packaging.ts

@@ -54,6 +54,11 @@
  *      path variables (the host delivers anything else as the literal string),
  *      and an optional string option has `"default": ""` so a blank answer
  *      arrives as empty rather than as the unsubstituted placeholder.
+ *  12. README version badge parity: a shields.io `Version-<semver>-` badge in
+ *      `README.md` must carry the `package.json` `version`. The badge is the
+ *      package's headline version on GitHub and npmjs.com and ships in the
+ *      tarball, so a half-finished bump is publicly visible. Skipped when the
+ *      README, the badge, or the package version is absent (issue #418).
  *
  * 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,
@@ -99,8 +104,10 @@ const USER_CONFIG_REF = /^\$\{user_config\.([\w-]+)\}$/;
 /**
  * Root dev directories the scaffold template excludes from the bundle, and
  * whose `.mcpbignore` patterns must be anchored with `/` to avoid also
- * stripping nested runtime paths like `node_modules/x/framework-skills/`. Keep in step
- * with the directory entries in `templates/_.mcpbignore`.
+ * stripping nested runtime paths like `node_modules/x/framework-skills/`. Keep
+ * in step with the directory entries in this project's `.mcpbignore` — seeded
+ * from the mcp-ts-core repository's `templates/_.mcpbignore`, whose `_` prefix
+ * `init` drops on copy.
  */
 export const KNOWN_DEV_DIRS = ['framework-skills/', '.agents/', '.claude/'];
 
@@ -121,7 +128,10 @@ export const CRITICAL_RUNTIME_PATHS = [
  * `framework-skills/` is this framework's tree; `skills/` covers any other
  * dependency that vendors agent skills.
  * KEEP IN SYNC with `AGENT_DOC_ENTRY` in `scripts/clean-mcpb.ts` (the strip
- * step this check verifies) — a unit test asserts the two are identical.
+ * step this check verifies) — edit both literals together. The assertion that
+ * they match lives in the mcp-ts-core repository's own test suite; `tests/` is
+ * not part of the published package, so nothing enforces the pair in a server
+ * these scripts were copied into.
  */
 export const AGENT_DOC_ENTRY =
   /^node_modules\/.*(?:\/framework-skills\/|\/skills\/|\/\.claude\/|\/\.agents\/|\/SKILL\.md$)/;
@@ -129,7 +139,10 @@ export const AGENT_DOC_ENTRY =
 /**
  * Platform-specific native binding packages that must not ship in a bundle.
  * KEEP IN SYNC with `NATIVE_BINDING_ENTRY` in `scripts/clean-mcpb.ts` (the
- * strip step this check verifies) — a unit test asserts the two are identical.
+ * strip step this check verifies) — edit both literals together. The assertion
+ * that they match lives in the mcp-ts-core repository's own test suite;
+ * `tests/` is not part of the published package, so nothing enforces the pair
+ * in a server these scripts were copied into.
  */
 export const NATIVE_BINDING_ENTRY = /^node_modules\/@duckdb\/node-bindings-[^/]+\//;
 
@@ -673,6 +686,62 @@ export function checkPluginManifests(
   return errors;
 }
 
+/**
+ * The shields.io static version badge, anchored on the `Version-` label and the
+ * `-` that closes the version segment. A literal `-` inside a badge segment is
+ * escaped as `--`, so the segment is "runs of non-dash characters joined by
+ * escaped dashes" — which also keeps the scan linear, since the alternation
+ * cannot match the same character two ways. Anchoring on the label and the
+ * trailing `-` tolerates colour, extension, and query-string variation without
+ * enumerating them, and matches no other badge: a live `img.shields.io/npm/v/…`
+ * badge has no `badge/Version-` path.
+ */
+const README_VERSION_BADGE = /img\.shields\.io\/badge\/Version-([^-]*(?:--[^-]*)*)-/;
+
+/**
+ * A version the badge can be compared against once its `--` escapes are
+ * decoded: the semver core, then at most one `-` prerelease segment and one
+ * `+` build segment. The two are separate optionals rather than one repeated
+ * `(?:[-+]…)*`, because `-` is itself a member of the segment character class
+ * — a repeated group can split a run of dashes two ways and backtracks
+ * exponentially on a segment the check is about to reject (CodeQL `js/redos`,
+ * CWE-1333). `+` is outside the class, so each segment's end is determined and
+ * the scan stays linear.
+ */
+const READABLE_VERSION = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/;
+
+/**
+ * Check 12: README version badge parity. When `README.md` carries a shields.io
+ * `Version-<semver>-` badge, its version must equal `package.json` `version` —
+ * the badge is the package's headline version on GitHub and npmjs.com, and it
+ * ships in the tarball, so a half-finished bump is publicly visible.
+ *
+ * Skipped when the README, the badge, or the package version is absent: a
+ * server that replaced the static badge with a live `npm/v` one has nothing to
+ * check, and a version-less `package.json` is the same fail-safe the
+ * plugin-manifest parity check applies. A badge that exists but cannot be read
+ * is drift the check cannot rule out, so it fails rather than skips.
+ */
+export function checkReadmeVersionBadge(readme: string, packageVersion?: string): string[] {
+  if (!packageVersion) return [];
+
+  const segment = README_VERSION_BADGE.exec(readme)?.[1];
+  if (segment === undefined) return [];
+
+  const badgeVersion = segment.replaceAll('--', '-');
+  if (!READABLE_VERSION.test(badgeVersion)) {
+    return [
+      `README.md version badge segment is "${segment}" — not a readable version, so it cannot be ` +
+        `checked against the package.json version "${packageVersion}"; write the badge as ` +
+        `"Version-${packageVersion.replaceAll('-', '--')}-"`,
+    ];
+  }
+  if (badgeVersion === packageVersion) return [];
+  return [
+    `README.md version badge is "${badgeVersion}" — must equal the package.json version "${packageVersion}"`,
+  ];
+}
+
 /** Read `packaging.pluginManifests` from devcheck.config.json; default on. */
 function pluginManifestsEnabled(): boolean {
   const cfg = tryReadJson<{ packaging?: { pluginManifests?: boolean } }>(
@@ -805,6 +874,12 @@ async function main(): Promise<void> {
     }
   }
 
+  // ── README version badge (check 12) ──
+  const readmePath = resolve('README.md');
+  if (existsSync(readmePath)) {
+    errors.push(...checkReadmeVersionBadge(readFileSync(readmePath, 'utf-8'), pkg?.version));
+  }
+
   // ── Plugin marketplace manifests (check 10) ──
   if (unscopedName && pkg?.name) {
     if (pluginManifestsEnabled()) {

package/templates/.env.example

@@ -1,7 +1,7 @@
 # ── Transport ──────────────────────────────────────────────────────────
 # MCP_TRANSPORT_TYPE=stdio          # stdio | http (default: stdio)
 # MCP_HTTP_PORT=3010                # HTTP port (default: 3010)
-# MCP_HTTP_HOST=localhost           # HTTP host (default: localhost)
+# MCP_HTTP_HOST=127.0.0.1           # HTTP host (default: 127.0.0.1)
 # MCP_HTTP_ENDPOINT_PATH=/mcp      # HTTP endpoint path (default: /mcp)
 # MCP_HTTP_MAX_BODY_BYTES=1048576  # Max request body bytes; 413 over limit, 0 disables (default: 1048576)
 # MCP_PUBLIC_URL=                  # Public origin behind a TLS-terminating proxy (e.g. https://mcp.example.com)
@@ -14,7 +14,10 @@
 # STORAGE_PROVIDER_TYPE=in-memory   # in-memory | filesystem | supabase | cloudflare-r2 | cloudflare-kv | cloudflare-d1
 
 # ── Session ──────────────────────────────────────────────────────────
-# MCP_SESSION_MODE=auto             # stateful | stateless | auto (default: auto, resolves to stateful)
+MCP_SESSION_MODE=stateless          # stateful | stateless | auto. Set here, not left to the schema default
+                                    # (auto, which resolves to stateful). Stateless fits a data API:
+                                    # no session store, horizontally scalable. Use stateful when a tool
+                                    # asks the caller for input mid-handler (ctx.requestInput).
 # MCP_HTTP_RESUMABILITY=false       # SSE replay on a dropped stateful stream. Default: true.
                                     # Kill switch only — no effect on stateless serving.
 # MCP_HTTP_RESUMABILITY_MAX_EVENTS=512   # Retained per session, oldest evicted first

package/templates/AGENTS.md

@@ -174,6 +174,22 @@ await createApp({
 
 `instructions` is optional server-level orientation, sent on every `initialize` as session-level context. Use it for deployment guidance (connection aliases, regional notes, scope hints) instead of repeating the same context across tool descriptions. Client adoption is uneven, but there's no downside when set.
 
+### Session posture and shutdown
+
+Two more `createApp()` options shape how the server runs rather than how it presents itself:
+
+```ts
+await createApp({
+  sessionMode: 'stateless',          // or { default: 'stateful', require: 'stateful' }
+  setup(core) { startMyWatcher(core.config); },
+  async teardown() { await stopMyWatcher(); },
+});
+```
+
+`sessionMode` declares the HTTP session posture in `src/` instead of leaving it to a deployment's `MCP_SESSION_MODE`, which still wins whenever it carries a meaningful value (an empty string and an unsubstituted `${…}` placeholder read as unset and fall through to the option). Add `require: 'stateful'` when a tool asks the caller for input mid-handler via `ctx.requestInput`: startup then fails with a `ConfigurationError` rather than serving a mode in which a 2025-era client can never answer the prompt. Stdio is never refused.
+
+`teardown(core)` is the `setup()` counterpart — release a watcher, socket, or non-`unref()`'d timer there. It runs after the transport stops and before the logger closes, on every shutdown path, and a signal-triggered shutdown then exits the process explicitly (0, or 1 if a step never settles within the framework's 10 s ceiling).
+
 ---
 
 ## Context

package/templates/CLAUDE.md

@@ -174,6 +174,22 @@ await createApp({
 
 `instructions` is optional server-level orientation, sent on every `initialize` as session-level context. Use it for deployment guidance (connection aliases, regional notes, scope hints) instead of repeating the same context across tool descriptions. Client adoption is uneven, but there's no downside when set.
 
+### Session posture and shutdown
+
+Two more `createApp()` options shape how the server runs rather than how it presents itself:
+
+```ts
+await createApp({
+  sessionMode: 'stateless',          // or { default: 'stateful', require: 'stateful' }
+  setup(core) { startMyWatcher(core.config); },
+  async teardown() { await stopMyWatcher(); },
+});
+```
+
+`sessionMode` declares the HTTP session posture in `src/` instead of leaving it to a deployment's `MCP_SESSION_MODE`, which still wins whenever it carries a meaningful value (an empty string and an unsubstituted `${…}` placeholder read as unset and fall through to the option). Add `require: 'stateful'` when a tool asks the caller for input mid-handler via `ctx.requestInput`: startup then fails with a `ConfigurationError` rather than serving a mode in which a 2025-era client can never answer the prompt. Stdio is never refused.
+
+`teardown(core)` is the `setup()` counterpart — release a watcher, socket, or non-`unref()`'d timer there. It runs after the transport stops and before the logger closes, on every shutdown path, and a signal-triggered shutdown then exits the process explicitly (0, or 1 if a step never settles within the framework's 10 s ceiling).
+
 ---
 
 ## Context

package/templates/src/index.ts

@@ -20,4 +20,14 @@ await createApp({
   // instructions: 'Server-level orientation forwarded to the model on every initialize.\n' +
   //   '- Use shortcut `X` for the most common case\n' +
   //   '- Tools require auth via the `inventory:read` scope',
+
+  // Session posture in code rather than in a Dockerfile. MCP_SESSION_MODE still
+  // wins when it is set. Add `require: 'stateful'` — `{ default: 'stateful',
+  // require: 'stateful' }` — when a tool asks the caller for input mid-handler,
+  // so a stateless deployment fails at startup instead of losing that tool.
+  // sessionMode: 'stateless',
+
+  // Release what setup() allocated: a watcher, a socket, a timer the framework
+  // cannot see. Runs after the transport stops and before the logger closes.
+  // teardown(core) { core.logger.info('bye', { requestId: 'shutdown', timestamp: new Date().toISOString() }); },
 });