@cyanheads/mcp-ts-core 0.13.10 → 0.13.11

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/lint-packaging.ts

@@ -80,6 +80,15 @@
  *      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,
@@ -990,6 +999,82 @@ export function checkDockerfileBuildPlatform(dockerfile: string): string[] {
     );
 }
 
+/** 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 } }>(
@@ -1007,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');
@@ -1039,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));
@@ -1083,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/.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/Dockerfile

@@ -38,10 +38,10 @@ RUN bun run build
 #
 # Installs the production dependency tree for the target platform. Every step
 # here can run JavaScript — bunfig.toml's security scanner runs as a Bun
-# program, and so does the OTel script — so the stage runs on $BUILDPLATFORM
-# and cross-installs with `--os`/`--cpu`, which pick each platform-specific
-# optional dependency (native bindings such as DuckDB's) for the target. Only
-# `node_modules` leaves this stage.
+# program, and so do the OTel and musl-prune scripts — so the stage runs on
+# $BUILDPLATFORM and cross-installs with `--os`/`--cpu`, which pick each
+# platform-specific optional dependency (native bindings such as DuckDB's) for
+# the target. Only `node_modules` leaves this stage.
 #
 # A clean image rather than `FROM build`: the build stage's node_modules holds
 # devDependencies.
@@ -93,6 +93,15 @@ RUN --mount=type=cache,target=/root/.bun/install/cache \
       bun scripts/install-otel.ts --os="$TARGETOS" --cpu="$(cat .bun-cpu)"; \
     fi
 
+# `--os`/`--cpu` have no libc counterpart, so a native dependency published in
+# glibc and musl variants (DuckDB's bindings, for one) installs both. The
+# runtime image is Debian (glibc) and never loads the musl copy; the script
+# deletes every package whose own `libc` admits only musl. It follows every
+# install, since a later `bun install` restores what it removes. A server on a
+# musl (Alpine) runtime image drops these two lines.
+COPY scripts/prune-musl-packages.ts ./scripts/
+RUN bun scripts/prune-musl-packages.ts
+
 # The seeded scanner served only the installs above; keep it out of the image.
 RUN rm -rf node_modules/@socketsecurity/bun-security-scanner
 

package/templates/_.dockerignore

@@ -164,11 +164,9 @@ coverage/
 # =============================================================================
 # ENVIRONMENT & CONFIGURATION
 # =============================================================================
-.env
-.env.local
-.env.development.local
-.env.test.local
-.env.production.local
+.env*
+.mcpregistry_github_token
+.mcpregistry_registry_token
 .sample-env
 sample.*
 !sample.template.*

package/templates/_.gitignore

@@ -40,7 +40,6 @@ dist/
 # TESTING & COVERAGE
 # =============================================================================
 coverage/
-!coverage/coverage-final.json
 
 # =============================================================================
 # LOGS & DATABASES
@@ -59,9 +58,10 @@ logs/
 # =============================================================================
 # ENVIRONMENT & CONFIGURATION
 # =============================================================================
-.env
-.env.local
-.env.*.local
+.env*
+!.env.example
+!.env.template
+!.env.sample
 .wrangler
 worker-configuration.d.ts
 

package/templates/package.json

@@ -67,14 +67,14 @@
     "zod": "{{ZOD_VERSION}}"
   },
   "devDependencies": {
-    "@biomejs/biome": "2.5.14",
+    "@biomejs/biome": "2.5.15",
     "@socketsecurity/bun-security-scanner": "^1.1.3",
-    "@types/node": "26.6.2",
+    "@types/node": "26.6.3",
     "@vitest/coverage-istanbul": "4.1.11",
     "depcheck": "^1.4.7",
     "fast-check": "^4.9.0",
-    "ignore": "^7.0.9",
-    "tsc-alias": "^1.9.5",
+    "ignore": "^7.0.11",
+    "tsc-alias": "^1.9.7",
     "typescript": "^7.0.2",
     "vitest": "^4.1.11"
   }

package/templates/server.json

@@ -12,18 +12,8 @@
       "registryType": "npm",
       "registryBaseUrl": "https://registry.npmjs.org",
       "identifier": "{{PACKAGE_NAME}}",
-      "runtimeHint": "node",
+      "runtimeHint": "npx",
       "version": "0.1.0",
-      "packageArguments": [
-        {
-          "type": "positional",
-          "value": "run"
-        },
-        {
-          "type": "positional",
-          "value": "start:stdio"
-        }
-      ],
       "environmentVariables": [
         {
           "name": "MCP_LOG_LEVEL",
@@ -41,19 +31,15 @@
       "registryType": "npm",
       "registryBaseUrl": "https://registry.npmjs.org",
       "identifier": "{{PACKAGE_NAME}}",
-      "runtimeHint": "node",
+      "runtimeHint": "npx",
       "version": "0.1.0",
-      "packageArguments": [
+      "environmentVariables": [
         {
-          "type": "positional",
-          "value": "run"
+          "name": "MCP_TRANSPORT_TYPE",
+          "description": "Selects the HTTP transport.",
+          "format": "string",
+          "value": "http"
         },
-        {
-          "type": "positional",
-          "value": "start:http"
-        }
-      ],
-      "environmentVariables": [
         {
           "name": "MCP_HTTP_HOST",
           "description": "The hostname for the HTTP server.",