@cyanheads/mcp-ts-core 0.13.6 → 0.13.8

package/scripts/check-skill-versions.ts

@@ -20,10 +20,19 @@
  *
  * A bare name (`add-tool`) and the file path (`add-tool/SKILL.md`) both match.
  *
- * Diffing against `HEAD` keeps the per-release-cycle carve-out automatic: once the
- * version line is bumped, later commits in the same cycle no longer re-trigger.
+ * In the framework repo, a skill whose version already moved since the last `v*`
+ * release tag — or that is new since it — is covered: a later body edit in the
+ * same cycle shares that bump instead of needing another.
+ *
+ * The inverse also holds: a skill moves at most one step per release. In the
+ * framework repo itself, each skill's version is compared with its version at the
+ * last `v*` release tag, and anything past the next minor (`1.4` → `1.5`) or the
+ * next major (`1.4` → `2.0`) is a violation — repeated edits in one cycle share a
+ * single bump. Consumer repos skip this: a skill sync can legitimately jump
+ * several framework releases at once.
+ *
  * Severity mirrors `check-skills-sync.ts` — exits 1, demoted to a warning by
- * devcheck. New skills (no `HEAD` version) and non-git trees are skipped.
+ * devcheck. New skills (no prior version) and non-git trees are skipped.
  *
  * Runs standalone (`bun run scripts/check-skill-versions.ts`) and as a devcheck step.
  *
@@ -36,6 +45,7 @@ import process from 'node:process';
 
 const ROOT = resolve('.');
 const SKILL_MD_RE = /^framework-skills\/[^/]+\/SKILL\.md$/;
+const FRAMEWORK_PACKAGE = '@cyanheads/mcp-ts-core';
 
 interface DevcheckConfig {
   skillVersions?: { ignore?: string[] };
@@ -60,10 +70,10 @@ function isIgnored(relPath: string, patterns: string[]): boolean {
   );
 }
 
-/** Skill `SKILL.md` files that differ from `HEAD` (staged + unstaged). */
-function changedSkillFiles(): string[] {
-  const result = spawnSync('git', ['diff', '--name-only', 'HEAD', '--'], { encoding: 'utf-8' });
-  if (result.status !== 0) return []; // not a git repo / no HEAD commit
+/** Skill `SKILL.md` files that differ from `ref` in the working tree (staged + unstaged). */
+function changedSkillFiles(ref: string): string[] {
+  const result = spawnSync('git', ['diff', '--name-only', ref, '--'], { encoding: 'utf-8' });
+  if (result.status !== 0) return []; // not a git repo / no such ref
   return result.stdout
     .trim()
     .split('\n')
@@ -71,18 +81,50 @@ function changedSkillFiles(): string[] {
 }
 
 /**
- * Content of a path at `HEAD`, or null when it didn't exist there (new file).
- * A tree renamed from the pre-0.13 `skills/` reads its `HEAD` copy from the old
+ * Content of a path at `ref`, or null when it didn't exist there (new file).
+ * A tree renamed from the pre-0.13 `skills/` reads its old copy from the old
  * path, so the release that carries the rename still checks every body edit.
  */
-function headContent(relPath: string): string | null {
-  const show = (p: string) => spawnSync('git', ['show', `HEAD:${p}`], { encoding: 'utf-8' });
+function contentAt(ref: string, relPath: string): string | null {
+  const show = (p: string) => spawnSync('git', ['show', `${ref}:${p}`], { encoding: 'utf-8' });
   const result = show(relPath);
   if (result.status === 0) return result.stdout;
   const legacy = show(relPath.replace(/^framework-skills\//, 'skills/'));
   return legacy.status === 0 ? legacy.stdout : null;
 }
 
+/** True when this tree is the framework itself, where skill versions are authored. */
+function isFrameworkRepo(): boolean {
+  try {
+    const pkg = JSON.parse(readFileSync(resolve(ROOT, 'package.json'), 'utf-8')) as {
+      name?: string;
+    };
+    return pkg.name === FRAMEWORK_PACKAGE;
+  } catch {
+    return false;
+  }
+}
+
+/** The latest `v*` release tag reachable from `HEAD`, or null when there is none. */
+function lastReleaseTag(): string | null {
+  const result = spawnSync('git', ['describe', '--tags', '--abbrev=0', '--match', 'v*'], {
+    encoding: 'utf-8',
+  });
+  return result.status === 0 ? result.stdout.trim() : null;
+}
+
+/** True when `to` is `from`, its next minor, or its next major at `.0`. */
+function withinOneStep(from: string, to: string): boolean {
+  const [fromMajor, fromMinor] = from.split('.').map(Number);
+  const [toMajor, toMinor] = to.split('.').map(Number);
+  if ([fromMajor, fromMinor, toMajor, toMinor].some((n) => n === undefined || Number.isNaN(n))) {
+    return true; // not `X.Y` — out of this check's scope
+  }
+  if (from === to) return true;
+  if (toMajor === fromMajor) return toMinor === (fromMinor as number) + 1;
+  return toMajor === (fromMajor as number) + 1 && toMinor === 0;
+}
+
 /** `metadata.version` from skill frontmatter, or null when absent/unparseable. */
 function extractVersion(content: string): string | null {
   const block = content.match(/^---\n([\s\S]*?)\n---/)?.[1];
@@ -108,11 +150,24 @@ if (!existsSync(resolve(ROOT, 'framework-skills'))) {
 }
 
 const ignore = loadIgnorePatterns();
-const changed = changedSkillFiles().filter((f) => !isIgnored(f, ignore));
+const tag = isFrameworkRepo() ? lastReleaseTag() : null;
 
-const violations: { file: string; version: string }[] = [];
-for (const file of changed) {
-  const oldContent = headContent(file);
+/**
+ * True when the skill's current version already differs from its version at the
+ * release tag — or the skill is new since it — so this cycle's one step is taken
+ * and a further body edit shares it rather than needing another bump.
+ */
+function bumpedThisRelease(file: string, version: string | null): boolean {
+  if (tag === null) return false;
+  const released = contentAt(tag, file);
+  if (released === null) return true;
+  const releasedVersion = extractVersion(released);
+  return releasedVersion !== null && releasedVersion !== version;
+}
+
+const missing: { file: string; version: string }[] = [];
+for (const file of changedSkillFiles('HEAD').filter((f) => !isIgnored(f, ignore))) {
+  const oldContent = contentAt('HEAD', file);
   if (oldContent === null) continue; // new skill — no prior version to compare
   if (!existsSync(resolve(ROOT, file))) continue; // deleted in worktree — no body to compare, can't violate
   const newContent = readFileSync(resolve(ROOT, file), 'utf-8');
@@ -121,25 +176,51 @@ for (const file of changed) {
 
   const oldVersion = extractVersion(oldContent);
   const newVersion = extractVersion(newContent);
-  if (oldVersion !== null && oldVersion === newVersion) {
-    violations.push({ file, version: oldVersion });
+  if (oldVersion !== null && oldVersion === newVersion && !bumpedThisRelease(file, newVersion)) {
+    missing.push({ file, version: oldVersion });
   }
 }
 
-if (violations.length === 0) {
+const overshot: { file: string; tag: string; released: string; version: string }[] = [];
+if (tag !== null) {
+  for (const file of changedSkillFiles(tag)) {
+    const released = contentAt(tag, file);
+    if (released === null || !existsSync(resolve(ROOT, file))) continue;
+    const releasedVersion = extractVersion(released);
+    const version = extractVersion(readFileSync(resolve(ROOT, file), 'utf-8'));
+    if (releasedVersion === null || version === null) continue;
+    if (!withinOneStep(releasedVersion, version)) {
+      overshot.push({ file, tag, released: releasedVersion, version });
+    }
+  }
+}
+
+const count = missing.length + overshot.length;
+if (count === 0) {
   console.log('Skill versions are in step with body changes.');
   process.exit(0);
 }
 
 const lines = [
-  `${violations.length} skill${violations.length === 1 ? '' : 's'} changed body without a metadata.version bump:`,
+  `${count} skill${count === 1 ? '' : 's'} out of step with the versioning policy:`,
   '',
 ];
-for (const v of violations) {
+for (const v of missing) {
   lines.push(`  - ${v.file} body changed but metadata.version is still "${v.version}"`);
 }
+for (const v of overshot) {
+  lines.push(
+    `  - ${v.file} is "${v.version}", more than one step past "${v.released}" at ${v.tag}`,
+  );
+}
 lines.push('');
-lines.push('Fix: bump metadata.version in the SKILL.md frontmatter, or add the skill to');
-lines.push('     devcheck.config.json `skillVersions.ignore` for the typo/whitespace carve-out.');
+if (missing.length > 0) {
+  lines.push('Fix: bump metadata.version in the SKILL.md frontmatter, or add the skill to');
+  lines.push('     devcheck.config.json `skillVersions.ignore` for the typo/whitespace carve-out.');
+}
+if (overshot.length > 0) {
+  lines.push('Fix: set metadata.version to one step past the release tag — edits in one');
+  lines.push('     release cycle share a single bump.');
+}
 console.log(lines.join('\n'));
 process.exit(1);

package/scripts/devcheck.ts

@@ -811,7 +811,8 @@ const ALL_CHECKS: Check[] = [
     flag: '--no-skill-versions',
     canFix: false,
     // Flags framework-skills/<name>/SKILL.md body changes (vs HEAD) that lack a metadata.version
-    // bump (#99). Skipped when framework-skills/ is absent. Drift is demoted to a warning via
+    // bump (#99), and, in the framework repo, a skill bumped more than one step past the last
+    // release tag. Skipped when framework-skills/ is absent. Drift is demoted to a warning via
     // isSuccess — the typo/whitespace carve-out lives in devcheck.config.json
     // `skillVersions.ignore`.
     getCommand: () => {
@@ -821,11 +822,11 @@ const ALL_CHECKS: Check[] = [
     isSuccess: (result) => {
       if (result.exitCode === 0) return true;
       const firstLine =
-        result.stdout.split('\n')[0]?.trim() || 'Skill bodies changed without a version bump.';
+        result.stdout.split('\n')[0]?.trim() || 'Skill versions are out of step with the policy.';
       return { success: true, warning: firstLine };
     },
     tip: (c) =>
-      `Bump ${c.bold('metadata.version')} in the changed ${c.bold('SKILL.md')}, or add it to ${c.bold('devcheck.config.json')} ${c.bold('skillVersions.ignore')}.`,
+      `Bump ${c.bold('metadata.version')} once per release in the changed ${c.bold('SKILL.md')}, or add it to ${c.bold('devcheck.config.json')} ${c.bold('skillVersions.ignore')}.`,
   },
   {
     name: 'Changelog Sync',

package/scripts/lint-packaging.ts

@@ -59,6 +59,12 @@
  *      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).
+ *  13. npm `files` excludes the built bundle: when `manifest.json` exists and
+ *      `package.json` `files` covers `dist/` wholesale, it must also carry
+ *      `"!dist/*.mcpb"`. The `bundle` script writes the `.mcpb` into `dist/`,
+ *      so without the entry a release that bundles before publishing ships the
+ *      server and its production dependencies inside the npm tarball
+ *      (issue #469). Skipped when `manifest.json` or `files` is absent.
  *
  * 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,
@@ -742,6 +748,33 @@ export function checkReadmeVersionBadge(readme: string, packageVersion?: string)
   ];
 }
 
+/** The `files` entry that keeps the `bundle` script's `dist/<name>.mcpb` out of the npm tarball. */
+const BUNDLE_EXCLUSION = '!dist/*.mcpb';
+
+/**
+ * Check 13: a `files` allowlist that covers `dist/` wholesale must exclude the
+ * `.mcpb` the `bundle` script writes there. npm and Bun both honor `!` entries
+ * in `files`, and both ignore `.npmignore` once `files` is set, so the entry is
+ * the only place the exclusion can live. The caller runs this only when
+ * `manifest.json` exists — a project without one never builds a bundle.
+ */
+export function checkBundleExcludedFromFiles(files: unknown): string[] {
+  if (!Array.isArray(files)) return [];
+  const entries = files.filter((entry): entry is string => typeof entry === 'string');
+
+  const coversDist = entries.some(
+    (entry) => entry.replace(/^\.\//, '').replace(/\/(?:\*\*(?:\/\*)?|\*)?$/, '') === 'dist',
+  );
+  if (!coversDist) return [];
+  if (entries.includes(BUNDLE_EXCLUSION) || entries.includes('!dist/**/*.mcpb')) return [];
+
+  return [
+    `package.json "files" covers dist/ without "${BUNDLE_EXCLUSION}" — the bundle script writes ` +
+      `dist/<name>.mcpb, so a release that bundles before publishing ships it in the npm tarball; ` +
+      `add "${BUNDLE_EXCLUSION}" to "files"`,
+  ];
+}
+
 /** Read `packaging.pluginManifests` from devcheck.config.json; default on. */
 function pluginManifestsEnabled(): boolean {
   const cfg = tryReadJson<{ packaging?: { pluginManifests?: boolean } }>(
@@ -755,7 +788,9 @@ async function main(): Promise<void> {
   const warnings: string[] = [];
   const notes: string[] = [];
 
-  const pkg = tryReadJson<{ name?: string; version?: string }>(resolve('package.json'));
+  const pkg = tryReadJson<{ files?: unknown; name?: string; version?: string }>(
+    resolve('package.json'),
+  );
   const unscopedName = pkg?.name?.split('/').pop();
 
   // ── Manifest-dependent checks (1–4 + manifest identity) ──
@@ -826,6 +861,8 @@ async function main(): Promise<void> {
     if (unscopedName) {
       errors.push(...checkManifestIdentity(manifest, unscopedName));
     }
+
+    errors.push(...checkBundleExcludedFromFiles(pkg?.files));
   } else {
     notes.push('No manifest.json — skipping manifest/server.json alignment checks.');
   }

package/templates/.env.example

@@ -31,10 +31,16 @@ MCP_SESSION_MODE=stateless          # stateful | stateless | auto. Set here, not
 # MCP_LOG_LEVEL=info                # debug | info | notice | warning | error
 # MCP_LOG_RATE_LIMIT_THRESHOLD=10   # Max emissions per level+message per window; 0 disables
 # MCP_LOG_RATE_LIMIT_WINDOW_MS=60000
+# LOG_TOOL_FAILURE_PAYLOADS=false            # Log failed tool calls' arguments + result (key-name redaction only;
+                                             # secrets in free-form values are kept). Reaches stderr, files, and OTLP
+# LOG_TOOL_FAILURE_PAYLOAD_MAX_BYTES=16384   # Per-payload cap, UTF-8 bytes
 
 # ── Telemetry ─────────────────────────────────────────────────────────
 # OTEL_ENABLED=false                          # Enable OpenTelemetry (default: false)
-# OTEL_EXPORTER_OTLP_ENDPOINT=               # OTLP endpoint URL (e.g., http://localhost:4318)
+# OTEL_EXPORTER_OTLP_ENDPOINT=               # OTLP base URL (e.g., http://localhost:4318); traces → /v1/traces, metrics → /v1/metrics
+# OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=        # Overrides the base for traces; used as-is
+# OTEL_EXPORTER_OTLP_METRICS_ENDPOINT=       # Overrides the base for metrics; used as-is
+# OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=          # Opt-in log export (e.g., http://localhost:4318/v1/logs); the base never enables it
 
 # ── Server-specific ──────────────────────────────────────────────────
 # Add your server's environment variables below

package/templates/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -10,7 +10,7 @@ body:
         **Secondary labels.** `enhancement` is applied automatically — also add one or more of the following in the sidebar if they apply:
         - `performance` — improves memory, CPU, latency, or resource usage
         - `security` — hardens the security posture
-        - `breaking-change` — will break public API; requires a major bump
+        - `breaking-change` — will break public API or an existing tool contract
         - `surplus-token-idea` — worth exploring when token budget allows
 
   - type: textarea

package/templates/AGENTS.md

@@ -67,7 +67,7 @@ export const searchItems = tool('search_items', {
   annotations: { readOnlyHint: true },
   input: z.object({
     query: z.string().describe('Search terms'),
-    limit: z.number().default(10).describe('Max results'),
+    limit: z.number().int().min(1).max(100).default(10).describe('Max results (1–100)'),
   }),
   output: z.object({
     items: z.array(z.object({
@@ -199,7 +199,7 @@ Handlers receive a unified `ctx` object. Key properties:
 | Property | Description |
 |:---------|:------------|
 | `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 serializable value. |
+| `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.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). |

package/templates/CLAUDE.md

@@ -67,7 +67,7 @@ export const searchItems = tool('search_items', {
   annotations: { readOnlyHint: true },
   input: z.object({
     query: z.string().describe('Search terms'),
-    limit: z.number().default(10).describe('Max results'),
+    limit: z.number().int().min(1).max(100).default(10).describe('Max results (1–100)'),
   }),
   output: z.object({
     items: z.array(z.object({
@@ -199,7 +199,7 @@ Handlers receive a unified `ctx` object. Key properties:
 | Property | Description |
 |:---------|:------------|
 | `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 serializable value. |
+| `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.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). |

package/templates/Dockerfile

@@ -14,7 +14,7 @@
 # output. A stage that compiles a native addon needs the target-arch toolchain
 # and cannot cross-compile this way — drop the flag there.
 # ==============================================================================
-FROM --platform=$BUILDPLATFORM oven/bun:1.4.0 AS build
+FROM --platform=$BUILDPLATFORM oven/bun:1.4.2 AS build
 
 WORKDIR /usr/src/app
 
@@ -40,7 +40,7 @@ RUN bun run build
 # application. It uses a slim base image and only includes production
 # dependencies and build artifacts.
 # ==============================================================================
-FROM oven/bun:1.4.0-slim AS production
+FROM oven/bun:1.4.2-slim AS production
 
 WORKDIR /usr/src/app
 
@@ -56,8 +56,15 @@ LABEL org.opencontainers.image.licenses="Apache-2.0"
 LABEL org.opencontainers.image.version="${APP_VERSION}"
 LABEL org.opencontainers.image.source=""
 
-# Copy dependency manifests
-COPY package.json bun.lock ./
+# 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.
+COPY --from=build /usr/src/app/node_modules/@socketsecurity/bun-security-scanner ./node_modules/@socketsecurity/bun-security-scanner
 
 # Install only production dependencies, ignoring any lifecycle scripts (like 'prepare')
 # that are not needed in the final production image.
@@ -70,21 +77,35 @@ RUN --mount=type=cache,target=/root/.bun/install/cache \
     bun install --production --omit=peer --frozen-lockfile --ignore-scripts
 
 # Conditionally install OpenTelemetry optional peer dependencies (Tier 3).
-# These are not bundled by default to keep the base image lean. Enable at build time
-# with: docker build --build-arg OTEL_ENABLED=true
+# 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.
 ARG OTEL_ENABLED=true
 RUN --mount=type=cache,target=/root/.bun/install/cache \
     if [ "$OTEL_ENABLED" = "true" ]; then \
-      bun add --omit=dev --omit=peer --ignore-scripts @hono/otel \
-        @opentelemetry/instrumentation-http \
+      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; \
+        @opentelemetry/semantic-conventions) \
+      && bun add --omit=dev --omit=peer --ignore-scripts $specs; \
     fi
 
 # Copy the compiled application code from the build stage
@@ -128,7 +149,6 @@ ENV MCP_TRANSPORT_TYPE="http"
 ENV MCP_SESSION_MODE="stateless"
 ENV MCP_LOG_LEVEL="info"
 ENV LOGS_DIR="/var/log/{{PACKAGE_NAME}}"
-ENV MCP_FORCE_CONSOLE_LOGGING="true"
 
 # Expose the port the server listens on
 EXPOSE ${MCP_HTTP_PORT}

package/templates/package.json

@@ -12,6 +12,7 @@
   "files": [
     "changelog/",
     "dist/",
+    "!dist/*.mcpb",
     "README.md",
     "LICENSE",
     "CLAUDE.md",
@@ -52,7 +53,7 @@
     "url": ""
   },
   "license": "Apache-2.0",
-  "packageManager": "bun@1.4.0",
+  "packageManager": "bun@1.4.2",
   "engines": {
     "bun": ">=1.4.0",
     "node": ">=24.0.0"
@@ -67,8 +68,8 @@
   },
   "devDependencies": {
     "@biomejs/biome": "2.5.14",
-    "@socketsecurity/bun-security-scanner": "^1.1.2",
-    "@types/node": "26.5.1",
+    "@socketsecurity/bun-security-scanner": "^1.1.3",
+    "@types/node": "26.6.2",
     "@vitest/coverage-istanbul": "4.1.11",
     "depcheck": "^1.4.7",
     "fast-check": "^4.9.0",

package/templates/src/mcp-server/prompts/definitions/echo.prompt.ts

@@ -8,11 +8,9 @@ import { prompt, z } from '@cyanheads/mcp-ts-core';
 // Prompts are pure message templates — no Context, no auth, no side effects.
 // They generate conversation messages that clients can use to start interactions.
 export const echoPrompt = prompt('template_echo_message', {
-  description: 'Generates a simple echo message. Replace this with your first real prompt.',
+  description: 'Generate a simple echo message. Replace this with your first real prompt.',
   args: z.object({
     message: z.string().describe('The message to echo.'),
   }),
-  generate: (args) => [
-    { role: 'user', content: { type: 'text', text: `Echo: ${args.message}` } },
-  ],
+  generate: (args) => [{ role: 'user', content: { type: 'text', text: `Echo: ${args.message}` } }],
 });

package/templates/src/mcp-server/resources/definitions/echo-app-ui.app-resource.ts

@@ -18,31 +18,69 @@ const APP_HTML = `<!DOCTYPE html>
   <meta name="viewport" content="width=device-width, initial-scale=1" />
   <title>Echo App</title>
   <style>
+    /*
+     * Local tokens are the pre-connect baseline: light by default, dark when the
+     * OS prefers it, and pinned by the data-theme attribute applyDocumentTheme sets.
+     * Every rule reads the host's variable first (installed by applyHostStyleVariables)
+     * and falls back to the local token until host context arrives.
+     */
+    :root {
+      color-scheme: light dark;
+      --bg: #ffffff; --surface: #f8fafc; --fg: #0f172a; --muted: #64748b;
+      --border: #e2e8f0; --accent: #2563eb; --accent-fg: #ffffff;
+    }
+    @media (prefers-color-scheme: dark) {
+      :root:not([data-theme="light"]) {
+        --bg: #0f172a; --surface: #1e293b; --fg: #e2e8f0; --muted: #94a3b8;
+        --border: #334155; --accent: #3b82f6; --accent-fg: #ffffff;
+      }
+    }
+    :root[data-theme="dark"] {
+      --bg: #0f172a; --surface: #1e293b; --fg: #e2e8f0; --muted: #94a3b8;
+      --border: #334155; --accent: #3b82f6; --accent-fg: #ffffff;
+    }
     * { margin: 0; padding: 0; box-sizing: border-box; }
     body {
-      font-family: system-ui, -apple-system, sans-serif;
-      background: #0f172a; color: #e2e8f0;
+      font-family: var(--font-sans, system-ui, -apple-system, sans-serif);
+      background: var(--color-background-primary, var(--bg));
+      color: var(--color-text-primary, var(--fg));
       padding: 1.5rem; min-height: 100vh;
       display: flex; flex-direction: column; align-items: center; gap: 1rem;
     }
-    h1 { font-size: 1.25rem; font-weight: 600; }
+    h1 {
+      font-size: var(--font-heading-sm-size, 1.25rem);
+      font-weight: var(--font-weight-semibold, 600);
+    }
     .card {
-      background: #1e293b; border: 1px solid #334155; border-radius: 0.5rem;
+      background: var(--color-background-secondary, var(--surface));
+      border: 1px solid var(--color-border-primary, var(--border));
+      border-radius: var(--border-radius-lg, 0.5rem);
       padding: 1rem 1.25rem; width: 100%; max-width: 480px;
     }
-    .label { font-size: 0.75rem; color: #94a3b8; text-transform: uppercase; letter-spacing: 0.05em; }
-    .value { font-size: 1rem; margin-top: 0.25rem; word-break: break-word; }
+    .label {
+      font-size: var(--font-text-xs-size, 0.75rem);
+      color: var(--color-text-secondary, var(--muted));
+      text-transform: uppercase; letter-spacing: 0.05em;
+    }
+    .value { font-size: var(--font-text-md-size, 1rem); margin-top: 0.25rem; word-break: break-word; }
     .controls { display: flex; gap: 0.5rem; width: 100%; max-width: 480px; }
     input[type="text"] {
-      flex: 1; padding: 0.5rem 0.75rem; background: #1e293b; border: 1px solid #334155;
-      border-radius: 0.375rem; color: #e2e8f0; font-size: 0.875rem; outline: none;
+      flex: 1; padding: 0.5rem 0.75rem;
+      background: var(--color-background-secondary, var(--surface));
+      border: 1px solid var(--color-border-primary, var(--border));
+      border-radius: var(--border-radius-md, 0.375rem);
+      color: var(--color-text-primary, var(--fg));
+      font: inherit; font-size: var(--font-text-sm-size, 0.875rem); outline: none;
     }
-    input[type="text"]:focus { border-color: #3b82f6; }
+    input[type="text"]:focus { border-color: var(--color-ring-primary, var(--accent)); }
     button {
-      padding: 0.5rem 1rem; background: #3b82f6; color: #fff; border: none;
-      border-radius: 0.375rem; font-size: 0.875rem; cursor: pointer;
+      padding: 0.5rem 1rem; border: none;
+      background: var(--color-background-inverse, var(--accent));
+      color: var(--color-text-inverse, var(--accent-fg));
+      border-radius: var(--border-radius-md, 0.375rem);
+      font: inherit; font-size: var(--font-text-sm-size, 0.875rem); cursor: pointer;
     }
-    button:hover { background: #2563eb; }
+    button:hover { opacity: 0.9; }
     button:disabled { opacity: 0.5; cursor: not-allowed; }
   </style>
 </head>
@@ -138,8 +176,7 @@ export const echoAppUiResource = appResource('ui://template-echo-app/app.html',
   name: 'echo-app-ui',
   title: 'Echo App UI',
   description:
-    'Interactive HTML app for the echo app tool. Displayed as a sandboxed iframe ' +
-    'by MCP Apps-capable hosts.',
+    'Interactive HTML app for the echo app tool. Displayed as a sandboxed iframe by MCP Apps-capable hosts.',
   params: ParamsSchema,
   auth: ['resource:echo-app-ui:read'],
   _meta: {

package/templates/src/mcp-server/resources/definitions/echo.resource.ts

@@ -9,7 +9,7 @@ import { resource, z } from '@cyanheads/mcp-ts-core';
 // Like tools, prefix names with your server name: template-echo, tasks-status, etc.
 export const echoResource = resource('echo://{message}', {
   name: 'template-echo-resource',
-  description: 'Echoes a message from the URI. Replace this with your first real resource.',
+  description: 'Echo a message from the URI. Replace this with your first real resource.',
   mimeType: 'application/json',
   params: z.object({
     message: z.string().describe('The message to echo back.'),

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

@@ -15,15 +15,14 @@ export const echoAppTool = appTool('template_echo_app', {
   resourceUri: UI_RESOURCE_URI,
   title: 'Echo App',
   description:
-    'Echoes a message with an interactive UI. Demonstrates MCP Apps — hosts that support ' +
-    'the extension render an HTML interface; others receive a text fallback.',
+    'Echo a message back with an interactive UI. Hosts that support MCP Apps render an HTML interface; other hosts receive a text fallback.',
   annotations: { readOnlyHint: true },
   input: z.object({
     message: z.string().describe('The message to echo.'),
   }),
   output: z.object({
     message: z.string().describe('The echoed message.'),
-    timestamp: z.string().describe('ISO 8601 timestamp of the echo.'),
+    timestamp: z.iso.datetime().describe('ISO 8601 timestamp of the echo.'),
   }),
 
   handler(input, ctx) {

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

@@ -9,7 +9,7 @@ import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
 // Tool names are snake_case, prefixed with your server name to avoid collisions across servers.
 // e.g. for a "tasks" server: tasks_fetch_list, tasks_create_item.
 export const echoTool = tool('template_echo_message', {
-  description: 'Echoes a message back. Replace this with your first real tool.',
+  description: 'Echo a message back. Replace this with your first real tool.',
   annotations: { readOnlyHint: true },
   input: z.object({
     message: z.string().describe('The message to echo back.'),

package/dist/utils/telemetry/index.d.ts

@@ -1,12 +0,0 @@
-/**
- * @fileoverview Barrel for telemetry utilities.
- * Provides OpenTelemetry instrumentation, MCP attribute keys, trace helpers,
- * and metrics creation utilities for observability.
- *
- * @module src/utils/telemetry
- */
-export * from './attributes.js';
-export * from './instrumentation.js';
-export * from './metrics.js';
-export * from './trace.js';
-//# sourceMappingURL=index.d.ts.map

package/dist/utils/telemetry/index.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/utils/telemetry/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,cAAc,iBAAiB,CAAC;AAChC,cAAc,sBAAsB,CAAC;AACrC,cAAc,cAAc,CAAC;AAC7B,cAAc,YAAY,CAAC"}

package/dist/utils/telemetry/index.js

@@ -1,12 +0,0 @@
-/**
- * @fileoverview Barrel for telemetry utilities.
- * Provides OpenTelemetry instrumentation, MCP attribute keys, trace helpers,
- * and metrics creation utilities for observability.
- *
- * @module src/utils/telemetry
- */
-export * from './attributes.js';
-export * from './instrumentation.js';
-export * from './metrics.js';
-export * from './trace.js';
-//# sourceMappingURL=index.js.map

package/dist/utils/telemetry/index.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/utils/telemetry/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,cAAc,iBAAiB,CAAC;AAChC,cAAc,sBAAsB,CAAC;AACrC,cAAc,cAAc,CAAC;AAC7B,cAAc,YAAY,CAAC"}