@cyanheads/mcp-ts-core 0.13.9 → 0.13.11

package/framework-skills/setup/SKILL.md

@@ -4,7 +4,7 @@ description: >
   Post-init orientation for an MCP server built on @cyanheads/mcp-ts-core. Use after running `@cyanheads/mcp-ts-core init` to understand the project structure, conventions, and skill sync model. Also use when onboarding to an existing project for the first time.
 metadata:
   author: cyanheads
-  version: "1.11"
+  version: "1.12"
   audience: external
   type: workflow
 ---
@@ -40,7 +40,7 @@ Dockerfile                                      # Starter multi-stage image
 .vscode/                                        # Recommended extensions + editor settings
 server.json                                     # MCP Registry publishing metadata
 changelog/template.md                           # Format reference for per-version changelog files
-scripts/                                        # build, clean, devcheck, lint-mcp, list-skills, build-changelog, tree, check-docs-sync
+scripts/                                        # Framework scripts (build, devcheck and its checks, lint-mcp, lint-packaging, Docker install-otel and prune-musl-packages, release-github, …), re-synced by `maintenance`
 framework-skills/                               # External skills copied from the package (source of truth)
 src/
   index.ts                                      # createApp() entry point

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cyanheads/mcp-ts-core",
-  "version": "0.13.9",
+  "version": "0.13.11",
   "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": [
@@ -16,9 +16,11 @@
     "scripts/clean-mcpb.ts",
     "scripts/clean.ts",
     "scripts/devcheck.ts",
+    "scripts/install-otel.ts",
     "scripts/lint-mcp.ts",
     "scripts/lint-packaging.ts",
     "scripts/list-skills.ts",
+    "scripts/prune-musl-packages.ts",
     "scripts/release-github.ts",
     "scripts/tree.ts",
     "framework-skills/",
@@ -113,6 +115,11 @@
       "import": "./dist/testing/index.js",
       "default": "./dist/testing/index.js"
     },
+    "./testing/apps": {
+      "types": "./dist/testing/apps/index.d.ts",
+      "import": "./dist/testing/apps/index.js",
+      "default": "./dist/testing/apps/index.js"
+    },
     "./testing/fuzz": {
       "types": "./dist/testing/fuzz.d.ts",
       "import": "./dist/testing/fuzz.js",
@@ -196,12 +203,13 @@
     "publish-mcp": "mcp-publisher login github -token \"$(security find-generic-password -a \"$USER\" -s mcp-publisher-github-pat -w)\" && mcp-publisher publish"
   },
   "devDependencies": {
-    "@biomejs/biome": "2.5.14",
+    "@biomejs/biome": "2.5.15",
     "@cloudflare/vitest-pool-workers": "^0.22.0",
-    "@cloudflare/workers-types": "5.20260922.1",
-    "@duckdb/node-api": "^1.5.5-r.5",
-    "@hono/otel": "^1.1.2",
-    "@modelcontextprotocol/client": "^2.1.0",
+    "@cloudflare/workers-types": "5.20260930.2",
+    "@duckdb/node-api": "^1.5.6-r.1",
+    "@hono/otel": "^1.2.0",
+    "@modelcontextprotocol/client": "^2.2.0",
+    "@modelcontextprotocol/ext-apps": "^2.0.3",
     "@opentelemetry/api-logs": "^0.222.0",
     "@opentelemetry/exporter-logs-otlp-http": "^0.222.0",
     "@opentelemetry/exporter-metrics-otlp-http": "^0.222.0",
@@ -215,11 +223,11 @@
     "@opentelemetry/sdk-trace-node": "^2.11.0",
     "@opentelemetry/semantic-conventions": "^1.43.0",
     "@socketsecurity/bun-security-scanner": "^1.1.3",
-    "@supabase/supabase-js": "^2.117.1",
+    "@supabase/supabase-js": "^2.117.2",
     "@types/bun": "^1.4.2",
-    "@types/node": "26.6.2",
+    "@types/node": "26.6.3",
     "@types/papaparse": "^5.5.2",
-    "@types/sanitize-html": "^2.16.1",
+    "@types/sanitize-html": "^2.16.2",
     "@vitest/coverage-istanbul": "4.1.11",
     "@vitest/ui": "4.1.11",
     "better-sqlite3": "^13.0.3",
@@ -230,24 +238,24 @@
     "diff": "^9.0.0",
     "execa": "^10.0.1",
     "fast-check": "^4.10.2",
-    "fast-xml-parser": "^5.11.1",
-    "ignore": "^7.0.10",
+    "fast-xml-parser": "^5.11.2",
+    "ignore": "^7.0.11",
     "js-yaml": "^5.4.2",
     "linkedom": "^0.18.13",
     "node-cron": "^4.6.0",
-    "openai": "^7.23.0",
+    "openai": "^7.25.0",
     "papaparse": "^5.7.0",
     "partial-json": "^0.1.7",
     "pdf-lib": "^1.17.1",
     "pino-pretty": "^13.1.3",
     "repomix": "^1.18.1",
-    "sanitize-html": "^2.17.7",
-    "tsc-alias": "^1.9.5",
+    "sanitize-html": "^2.18.0",
+    "tsc-alias": "^1.9.7",
     "typedoc": "^0.28.20",
     "typescript": "^7.0.2",
     "typescript-v6": "npm:typescript@^6.0.3",
     "unpdf": "^1.8.1",
-    "vite": "8.3.0",
+    "vite": "8.3.1",
     "vitest": "^4.1.11"
   },
   "keywords": [
@@ -289,17 +297,19 @@
     "access": "public"
   },
   "dependencies": {
-    "@hono/node-server": "^2.1.1",
-    "@modelcontextprotocol/server": "^2.1.0",
+    "@hono/node-server": "^2.1.3",
+    "@modelcontextprotocol/server": "^2.2.0",
     "@opentelemetry/api": "^1.9.1",
-    "hono": "^4.13.8",
+    "hono": "^4.13.12",
     "jose": "^6.2.12",
     "pino": "^10.3.1",
     "zod": "^4.6.5"
   },
   "peerDependencies": {
-    "@duckdb/node-api": "^1.5.5-r.1",
+    "@duckdb/node-api": "^1.5.5-r.1 || ^1.5.6-r.1",
     "@hono/otel": "^1.1.2",
+    "@modelcontextprotocol/client": "^2.1.0",
+    "@modelcontextprotocol/ext-apps": "^2.0.0",
     "@opentelemetry/api-logs": "^0.222.0",
     "@opentelemetry/exporter-logs-otlp-http": "^0.222.0",
     "@opentelemetry/exporter-metrics-otlp-http": "^0.222.0",
@@ -338,6 +348,12 @@
     "@hono/otel": {
       "optional": true
     },
+    "@modelcontextprotocol/client": {
+      "optional": true
+    },
+    "@modelcontextprotocol/ext-apps": {
+      "optional": true
+    },
     "@opentelemetry/api-logs": {
       "optional": true
     },
@@ -427,12 +443,12 @@
     }
   },
   "overrides": {
-    "brace-expansion": "^2.1.3",
+    "brace-expansion": "^2.1.7",
     "postcss": "^8.5.23",
     "protobufjs": "^7.6.5",
     "sharp": "^0.35.3",
-    "fast-uri": "^3.1.6",
-    "ip-address": "^10.3.1",
+    "fast-uri": "^3.1.8",
+    "ip-address": "^10.7.1",
     "nanoid": "^3.3.18"
   }
 }

package/scripts/devcheck.ts

@@ -639,15 +639,25 @@ const ALL_CHECKS: Check[] = [
     canFix: false,
     getCommand: (ctx) => {
       if (!isGitRepo()) return null; // no repo to grep — fresh scaffold before `git init`
-      // git grep -n (line number) -E (extended regex) -i (case-insensitive)
-      const baseCmd = ['git', 'grep', '-nEi', '\\b(TODO|FIXME)\\b'];
-      // Exclude files where TODO/FIXME appears as prose or intentional stubs
+      // -w is git's own whole-word test: macOS's regex library reads `\b` in an
+      // extended regex as a literal `b`. Case-sensitive, so a lowercase `todo`
+      // variable or stop word is not a marker.
+      const baseCmd = ['git', 'grep', '-nwE', '(TODO|FIXME)'];
+      // Exclude files where TODO/FIXME appears as prose or intentional stubs:
+      // changelogs, tests, this script, and the framework's skill prose wherever
+      // the maintenance sync copies it.
       const excludes = [
         ':!CHANGELOG.md',
         ':!changelog/',
         ':!*.lock',
         ':!scripts/devcheck.ts',
         ':!tests/',
+        ':!framework-skills/',
+        ':!.claude/skills/',
+        ':!.agents/skills/',
+        ':!.codex/skills/',
+        ':!.cursor/skills/',
+        ':!.windsurf/skills/',
       ];
       if (ctx.isHuskyHook && ctx.stagedFiles.length > 0) {
         // Check only staged files in the working tree
@@ -670,28 +680,38 @@ const ALL_CHECKS: Check[] = [
     name: 'Tracked Secrets',
     flag: '--no-secrets',
     canFix: false,
-    // Check if common sensitive files are tracked by git.
+    // Check if common sensitive files are tracked by git. `:(glob)` makes `**/`
+    // match zero or more directories, so each shape is caught at the repository
+    // root too; under it `*` stops at `/`, so the two name-prefix shapes carry a
+    // `/**` twin for the files inside a directory of that name (`secrets/`,
+    // `.env.d/`).
     getCommand: () => {
       if (!isGitRepo()) return null; // no repo — `git ls-files` would exit 128, not a finding
       return [
         'git',
         'ls-files',
-        '*.env*',
-        '**/.npmrc',
-        '**/.netrc',
-        '**/credentials.json',
-        '**/*.pem',
-        '**/*.key',
-        '**/secret*',
-        '**/.htpasswd',
+        ':(glob)**/*.env*',
+        ':(glob)**/*.env*/**',
+        ':(glob)**/.npmrc',
+        ':(glob)**/.netrc',
+        ':(glob)**/credentials.json',
+        ':(glob)**/*.pem',
+        ':(glob)**/*.key',
+        ':(glob)**/secret*',
+        ':(glob)**/secret*/**',
+        ':(glob)**/.htpasswd',
       ];
     },
-    // Success if output is empty OR only contains safe patterns.
+    // Success if output is empty OR only contains safe files: `.env` templates
+    // anywhere, and GitHub's secret scanning config at the one path it reads.
     isSuccess: (result, _mode) => {
       if (result.exitCode !== 0) return false;
-      const SAFE_PATTERNS = ['.env.example', '.env.template', '.env.sample'];
+      const SAFE_SUFFIXES = ['.env.example', '.env.template', '.env.sample'];
+      const SAFE_PATHS = ['.github/secret_scanning.yml'];
       const files = result.stdout.trim().split('\n').filter(Boolean);
-      const dangerous = files.filter((f) => !SAFE_PATTERNS.some((safe) => f.endsWith(safe)));
+      const dangerous = files.filter(
+        (f) => !SAFE_PATHS.includes(f) && !SAFE_SUFFIXES.some((safe) => f.endsWith(safe)),
+      );
       return dangerous.length === 0;
     },
     tip: (c) =>
@@ -712,11 +732,12 @@ const ALL_CHECKS: Check[] = [
     // Validates env var alignment between manifest.json (MCPB bundle) and
     // server.json (MCP Registry), plus plugin marketplace manifests (#240), the
     // bundle-content guards on .mcpbignore (#343), the README version badge
-    // (#418), and the Dockerfile build platform. Runs when any of those inputs
-    // is present; skipped cleanly when none exist — consumers on an HTTP-only
-    // deploy are unaffected. README.md and Dockerfile are triggers in their own
-    // right: each check must gate a project that carries no bundle or plugin
-    // metadata at all, which the other inputs only covered incidentally.
+    // (#418), the Dockerfile build platform, and the launch shape of server.json
+    // npm entries (#622). Runs when any of those inputs is present; skipped
+    // cleanly when none exist — consumers on an HTTP-only deploy are unaffected.
+    // README.md, Dockerfile, and server.json are triggers in their own right:
+    // each check must gate a project that carries no bundle or plugin metadata
+    // at all, which the other inputs only covered incidentally.
     getCommand: () => {
       const inputs = [
         'manifest.json',
@@ -726,12 +747,13 @@ const ALL_CHECKS: Check[] = [
         '.mcpbignore',
         'README.md',
         'Dockerfile',
+        'server.json',
       ];
       if (!inputs.some((input) => existsSync(path.join(ROOT_DIR, input)))) return null;
       return ['bun', 'run', 'scripts/lint-packaging.ts'];
     },
     tip: (c) =>
-      `Align env var names between ${c.bold('manifest.json')} ${c.bold('mcp_config.env')} and ${c.bold('server.json')} stdio package ${c.bold('environmentVariables[]')}.`,
+      `Each ${c.bold('✗')} line above names the file and the change that fixes it; ${c.bold('scripts/lint-packaging.ts')} documents every check.`,
   },
   {
     name: 'Framework Antipatterns',

package/scripts/install-otel.ts

@@ -0,0 +1,84 @@
+#!/usr/bin/env bun
+/**
+ * @fileoverview Installs the OpenTelemetry packages the framework loads at
+ * runtime into a production dependency tree — the Dockerfile's OTel step.
+ *
+ * The list is every `peerDependencies` entry named `@opentelemetry/*`, plus
+ * `@hono/otel`, in `@cyanheads/mcp-ts-core/package.json` resolved from the
+ * project root: the installed framework in a server, the package itself (by
+ * self-reference) in the framework. Each package moves into the project's
+ * `dependencies` at its declared peer range, out of `peerDependencies`,
+ * `peerDependenciesMeta`, and `devDependencies`, so `--omit=peer` keeps it
+ * while every other optional peer stays out. Then `bun install --omit=dev
+ * --omit=peer --ignore-scripts` runs with every argument given to this script
+ * appended, under the project's `bunfig.toml`, and its exit code is this
+ * script's. Not `--production`: it implies `--frozen-lockfile`, which fails
+ * once the manifest gains packages the lockfile lacks.
+ *
+ * @example
+ * // In a Dockerfile stage on $BUILDPLATFORM, cross-installing for the target:
+ * // bun scripts/install-otel.ts --os=linux --cpu=x64
+ * @module scripts/install-otel
+ */
+import { spawnSync } from 'node:child_process';
+import { readFileSync, writeFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+interface Manifest {
+  dependencies?: Record<string, string>;
+  devDependencies?: Record<string, string>;
+  peerDependencies?: Record<string, string>;
+  peerDependenciesMeta?: Record<string, unknown>;
+}
+
+/** The OTel optional peers a framework manifest declares, keyed by name, at their declared ranges. */
+export function otelPeers(framework: Manifest): Record<string, string> {
+  return Object.fromEntries(
+    Object.entries(framework.peerDependencies ?? {}).filter(
+      ([name]) => name.startsWith('@opentelemetry/') || name === '@hono/otel',
+    ),
+  );
+}
+
+function main(args: string[]): number {
+  const manifestPath = join(process.cwd(), 'package.json');
+  const frameworkPath = createRequire(manifestPath).resolve('@cyanheads/mcp-ts-core/package.json');
+  const peers = otelPeers(JSON.parse(readFileSync(frameworkPath, 'utf8')) as Manifest);
+  const names = Object.keys(peers);
+  if (names.length === 0) {
+    console.error(
+      `install-otel: ${frameworkPath} declares no @opentelemetry/* or @hono/otel peerDependencies — nothing to install.`,
+    );
+    return 1;
+  }
+
+  const manifest = JSON.parse(readFileSync(manifestPath, 'utf8')) as Manifest;
+  manifest.dependencies = { ...manifest.dependencies, ...peers };
+  for (const name of names) {
+    delete manifest.peerDependencies?.[name];
+    delete manifest.peerDependenciesMeta?.[name];
+    delete manifest.devDependencies?.[name];
+  }
+  writeFileSync(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`);
+  console.log(
+    `install-otel: ${names.length} OpenTelemetry packages from ${frameworkPath}: ` +
+      names.map((name) => `${name}@${peers[name]}`).join(' '),
+  );
+
+  const install = spawnSync(
+    'bun',
+    ['install', '--omit=dev', '--omit=peer', '--ignore-scripts', ...args],
+    { stdio: 'inherit' },
+  );
+  if (install.error) {
+    console.error(`install-otel: could not run bun install: ${install.error.message}`);
+    return 1;
+  }
+  return install.status ?? 1;
+}
+
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  process.exit(main(process.argv.slice(2)));
+}