@cyanheads/mcp-ts-core 0.9.0 → 0.9.2

package/scripts/devcheck.ts

@@ -416,6 +416,20 @@ const ALL_CHECKS: Check[] = [
     tip: (c) =>
       `Fix definition errors above — each diagnostic links to its rule in ${c.bold('skills/api-linter/SKILL.md')}.`,
   },
+  {
+    name: 'Packaging',
+    flag: '--no-packaging',
+    canFix: false,
+    // Validates env var alignment between manifest.json (MCPB bundle) and
+    // server.json (MCP Registry). Skipped cleanly when manifest.json is absent
+    // — consumers who deleted it for an HTTP-only deploy are unaffected.
+    getCommand: () => {
+      if (!existsSync(path.join(ROOT_DIR, 'manifest.json'))) 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[]')}.`,
+  },
   {
     name: 'Framework Antipatterns',
     flag: '--no-framework-antipatterns',
@@ -591,20 +605,24 @@ const ALL_CHECKS: Check[] = [
       const output = result.stdout.trim();
       if (result.exitCode !== 0 && !output.includes('|')) return false;
 
-      // Parse the tabular output. Package lines contain '|' separators.
-      // Filter out header/separator rows and allowlisted packages.
+      // Parse the tabular output. `bun outdated` emits markdown-style rows
+      // (`| col1 | col2 | ... |`), so split('|') yields an empty leading cell —
+      // package data starts at index [1]. Strip the trailing `(dev|peer|prod|optional)`
+      // workspace-type marker so the allowlist takes the bare package name.
       const lines = output.split('\n');
+      const stripWorkspaceMarker = (cell: string): string =>
+        cell.replace(/\s*\((?:dev|peer|prod|optional)\)$/, '');
       const packageLines = lines.filter((line) => {
         if (!line.includes('|')) return false;
         // Skip table chrome: header row and separator (e.g., "---")
-        const firstCell = line.split('|')[0]?.trim() ?? '';
+        const firstCell = line.split('|')[1]?.trim() ?? '';
         if (!firstCell || firstCell === 'Package' || /^-+$/.test(firstCell)) return false;
         return true;
       });
 
       // Check if every outdated package is in the allowlist
       const unexpected = packageLines.filter((line) => {
-        const pkgName = line.split('|')[0]?.trim() ?? '';
+        const pkgName = stripWorkspaceMarker(line.split('|')[1]?.trim() ?? '');
         return !OUTDATED_ALLOWLIST.has(pkgName);
       });
 
@@ -915,6 +933,19 @@ async function runCheck(check: Check, ctx: AppContext): Promise<CommandResult> {
   const result = await Shell.exec(command, { cwd: ctx.rootDir });
   const duration = Math.round(performance.now() - startTime);
 
+  // Bun's node-shim (via `bun run`) emits "Registry URL must be" errors when
+  // depcheck encounters `cloudflare:*` virtual-module specifiers in Workers
+  // tests. depcheck.ignores already filters them from the report — strip the
+  // cosmetic stderr so the summary stays clean.
+  if (name === 'Unused Dependencies' && result.stderr) {
+    result.stderr = result.stderr
+      .replace(
+        /error: Registry URL must be http:\/\/ or https:\/\/\nReceived: "cloudflare:[^"]*"\n?/g,
+        '',
+      )
+      .trim();
+  }
+
   const finalResult: CommandResult = {
     ...baseResult,
     ...result,

package/scripts/lint-packaging.ts

@@ -0,0 +1,116 @@
+#!/usr/bin/env node
+/**
+ * @fileoverview MCPB packaging linter — validates env var alignment between
+ * `manifest.json` (MCPB bundle install UX) and `server.json` (MCP Registry
+ * discovery) for stdio packages.
+ *
+ * Used by devcheck and as a standalone script: `bun run lint:packaging` /
+ * `npm run lint:packaging`.
+ *
+ * Checks:
+ *   1. Every `${user_config.X}` reference in manifest `mcp_config.env` must
+ *      appear in server.json stdio `environmentVariables[]` (the registry
+ *      advertises the configurable knob the bundle surfaces).
+ *   2. Every required stdio env var in server.json (no default) must appear
+ *      as a key in manifest `mcp_config.env` (the bundle can receive it).
+ *
+ * Skips cleanly when `manifest.json` is absent — consumers who deleted it for
+ * an HTTP-only deploy should not fail this check.
+ *
+ * @module scripts/lint-packaging
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+
+interface ServerJsonEnvVar {
+  default?: string;
+  isRequired?: boolean;
+  name: string;
+}
+
+interface ServerJsonPackage {
+  environmentVariables?: ServerJsonEnvVar[];
+  transport?: { type?: string };
+}
+
+interface ServerJson {
+  packages?: ServerJsonPackage[];
+}
+
+interface Manifest {
+  server?: { mcp_config?: { env?: Record<string, string> } };
+  user_config?: Record<string, unknown>;
+}
+
+const USER_CONFIG_REF = /^\$\{user_config\.([\w-]+)\}$/;
+
+function tryReadJson<T>(path: string): T | undefined {
+  try {
+    if (!existsSync(path)) return;
+    return JSON.parse(readFileSync(path, 'utf-8')) as T;
+  } catch (err) {
+    console.error(`Failed to parse ${path}: ${err instanceof Error ? err.message : err}`);
+    return;
+  }
+}
+
+function main(): void {
+  const manifestPath = resolve('manifest.json');
+  if (!existsSync(manifestPath)) {
+    console.log('No manifest.json — skipping lint:packaging.');
+    process.exit(0);
+  }
+
+  const manifest = tryReadJson<Manifest>(manifestPath);
+  if (!manifest) {
+    console.error('manifest.json is unreadable or malformed.');
+    process.exit(1);
+  }
+
+  const serverJson = tryReadJson<ServerJson>(resolve('server.json'));
+  if (!serverJson) {
+    console.log('No server.json — skipping cross-validation.');
+    process.exit(0);
+  }
+
+  const manifestEnv = manifest.server?.mcp_config?.env ?? {};
+  const manifestEnvKeys = new Set(Object.keys(manifestEnv));
+
+  const manifestUserConfigKeys = new Set(
+    Object.entries(manifestEnv)
+      .filter(([, v]) => typeof v === 'string' && USER_CONFIG_REF.test(v))
+      .map(([k]) => k),
+  );
+
+  const stdioEnvVars = (serverJson.packages ?? [])
+    .filter((p) => p.transport?.type === 'stdio')
+    .flatMap((p) => p.environmentVariables ?? []);
+  const stdioEnvNames = new Set(stdioEnvVars.map((v) => v.name));
+  const requiredStdioEnvNames = new Set(
+    stdioEnvVars.filter((v) => v.isRequired === true && v.default == null).map((v) => v.name),
+  );
+
+  const missingInServerJson = [...manifestUserConfigKeys].filter((k) => !stdioEnvNames.has(k));
+  const missingInManifest = [...requiredStdioEnvNames].filter((k) => !manifestEnvKeys.has(k));
+
+  const errors: string[] = [];
+  if (missingInServerJson.length > 0) {
+    errors.push(
+      `manifest.json references user_config env var(s) not advertised in server.json stdio environmentVariables[]: ${missingInServerJson.join(', ')}`,
+    );
+  }
+  if (missingInManifest.length > 0) {
+    errors.push(
+      `server.json declares required stdio env var(s) without default missing from manifest.json mcp_config.env: ${missingInManifest.join(', ')}`,
+    );
+  }
+
+  if (errors.length === 0) {
+    console.log('Packaging alignment OK.');
+    process.exit(0);
+  }
+  for (const err of errors) console.error(`  ✗ ${err}`);
+  process.exit(1);
+}
+
+main();

package/scripts/list-skills.ts

@@ -0,0 +1,170 @@
+#!/usr/bin/env bun
+/**
+ * @fileoverview Surfaces the YAML frontmatter of all SKILL.md files in this
+ * project's `.claude/skills/` directory (falling back to `skills/`). Mirrors
+ * how the Claude Code harness lists available skills, but as plain stdout an
+ * agent can read.
+ *
+ * Sub-agents spawned via the Agent tool do NOT inherit the parent session's
+ * skill registry — they see only the parent's skills, not the project-local
+ * skills in their working directory. Running this script gives a sub-agent
+ * operating in this project a quick index of available local skills. The
+ * agent can then read any relevant SKILL.md by the printed path before
+ * following its steps.
+ *
+ * @module scripts/list-skills
+ *
+ * Usage:
+ *   bun run scripts/list-skills.ts
+ */
+
+import { existsSync } from 'node:fs';
+import { readdir, readFile } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+
+const CANDIDATE_DIRS = ['.claude/skills', 'skills'] as const;
+
+interface SkillEntry {
+  description: string;
+  name: string;
+  path: string;
+  references: string[];
+}
+
+/**
+ * Naive YAML frontmatter parser. Handles flat `key: value` pairs (with
+ * optional surrounding `"` / `'` quotes stripped) and folded (`>`) / literal
+ * (`|`) block scalars over indented continuation lines — folded joins lines
+ * with spaces, literal preserves newlines. Sufficient for SKILL.md
+ * frontmatter — do not extend to general YAML; pull in a real parser if the
+ * format outgrows this.
+ */
+function parseFrontmatter(content: string): Record<string, string> {
+  const match = content.match(/^---\n([\s\S]*?)\n---/);
+  const body = match?.[1];
+  if (!body) return {};
+  const out: Record<string, string> = {};
+  const lines = body.split('\n');
+  let i = 0;
+  while (i < lines.length) {
+    const line = lines[i];
+    if (line === undefined) break;
+    const kv = line.match(/^(\w+):\s*(.*)$/);
+    const key = kv?.[1];
+    if (!kv || !key) {
+      i++;
+      continue;
+    }
+    const val = (kv[2] ?? '').trim();
+    const block = val.match(/^([>|])[-+]?$/);
+    if (block) {
+      const buf: string[] = [];
+      i++;
+      while (i < lines.length) {
+        const next = lines[i];
+        if (next === undefined || !/^\s+\S/.test(next)) break;
+        buf.push(next.trim());
+        i++;
+      }
+      out[key] = buf.join(block[1] === '|' ? '\n' : ' ').trim();
+      continue;
+    }
+    out[key] = stripQuotes(val);
+    i++;
+  }
+  return out;
+}
+
+function stripQuotes(s: string): string {
+  if (s.length < 2) return s;
+  const first = s[0];
+  const last = s[s.length - 1];
+  if ((first === '"' && last === '"') || (first === "'" && last === "'")) {
+    return s.slice(1, -1);
+  }
+  return s;
+}
+
+async function listReferences(skillDir: string): Promise<string[]> {
+  try {
+    const entries = await readdir(join(skillDir, 'references'));
+    return entries.filter((e) => e.endsWith('.md')).sort();
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code === 'ENOENT') return [];
+    throw err;
+  }
+}
+
+function findSkillsDir(): { rel: string; abs: string } | null {
+  // Resolve candidates relative to the script's parent dir (project root),
+  // not CWD — invocation may be from a sub-agent's worktree or subdirectory.
+  const root = resolve(import.meta.dirname, '..');
+  for (const dir of CANDIDATE_DIRS) {
+    const abs = join(root, dir);
+    if (existsSync(abs)) return { rel: dir, abs };
+  }
+  return null;
+}
+
+async function main(): Promise<void> {
+  const dir = findSkillsDir();
+  const root = resolve(import.meta.dirname, '..');
+  if (!dir) {
+    console.error(
+      `No skills directory found. Expected one of: ${CANDIDATE_DIRS.join(', ')} relative to project root (${root}).`,
+    );
+    process.exit(1);
+  }
+
+  const entries = await readdir(dir.abs, { withFileTypes: true });
+  const skills = (
+    await Promise.all(
+      entries
+        .filter((e) => e.isDirectory())
+        .map(async (entry): Promise<SkillEntry | null> => {
+          const skillDir = join(dir.abs, entry.name);
+          const skillPath = join(skillDir, 'SKILL.md');
+          let content: string;
+          try {
+            content = await readFile(skillPath, 'utf-8');
+          } catch (err) {
+            if ((err as NodeJS.ErrnoException).code === 'ENOENT') return null;
+            throw err;
+          }
+          const fm = parseFrontmatter(content);
+          return {
+            name: fm.name ?? entry.name,
+            description: fm.description ?? '',
+            path: skillPath,
+            references: await listReferences(skillDir),
+          };
+        }),
+    )
+  ).filter((s): s is SkillEntry => s !== null);
+
+  skills.sort((a, b) => a.name.localeCompare(b.name));
+
+  console.log(`# Skills available in ${dir.rel}/`);
+  console.log(`# Project root: ${root}`);
+  console.log(`#`);
+  console.log(`# Sub-agents: this list mimics the parent harness's skill registry.`);
+  console.log(
+    `# Read the full SKILL.md at the listed path before following a skill's procedure.\n`,
+  );
+
+  for (const s of skills) {
+    console.log(`- ${s.name} (${s.path})`);
+    if (s.description) console.log(`  ${s.description}`);
+    if (s.references.length > 0) {
+      console.log(`  references: ${s.references.join(', ')}`);
+    }
+    console.log();
+  }
+
+  console.log(`Total: ${skills.length} skills`);
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

package/skills/api-workers/SKILL.md

@@ -4,7 +4,7 @@ description: >
   Cloudflare Workers deployment using `createWorkerHandler` from `@cyanheads/mcp-ts-core/worker`. Covers the full handler signature, binding types, CloudflareBindings extensibility, runtime compatibility guards, and wrangler.toml requirements.
 metadata:
   author: cyanheads
-  version: "1.3"
+  version: "1.4"
   audience: external
   type: reference
 ---
@@ -49,6 +49,7 @@ Fresh scaffolds register definitions directly in the entry point as shown above.
 | `resources` | `AnyResourceDefinition[]` | Resource definitions to register |
 | `prompts` | `PromptDefinition[]` | Prompt definitions to register |
 | `extensions` | `Record<string, object>` | SEP-2133 extensions to advertise in server capabilities |
+| `instructions` | `string \| (env: CloudflareBindings) => string` | Server-level orientation forwarded to the model on every `initialize`. Resolver form runs inside `initializeApp(env)` so env-derived text is available (see Workers-specific warnings). Empty string treated as unset. |
 | `setup` | `(core: CoreServices) => void \| Promise<void>` | Runs after core services are ready, during the first request (lazy init inside the fetch handler) |
 | `extraEnvBindings` | `[bindingKey: string, processEnvKey: string][]` | Maps CF string bindings to `process.env` keys |
 | `extraObjectBindings` | `[bindingKey: string, globalKey: string][]` | Maps CF object bindings (KV, R2, D1, AI) to `globalThis` keys |
@@ -156,6 +157,19 @@ bucket_name = "..."
 
 ## Workers-specific warnings
 
+**`instructions` resolver runs after env injection.** When `instructions` is a function, it runs inside `initializeApp(env)` — after `injectEnvVars()` — so env-derived text reaches the model without fighting the Workers module-load lifecycle:
+
+```ts
+export default createWorkerHandler({
+  tools: [echoTool],
+  instructions: (env) =>
+    `Region: ${env.ENVIRONMENT ?? 'production'}.` +
+    (env.MAINTENANCE_MODE ? ' Read-only mode — writes disabled.' : ''),
+});
+```
+
+Plain strings work the same as on `createApp`. Type extends `Omit<CreateAppOptions, 'instructions'>`, so this is the only option whose shape differs between Node and Worker entry points.
+
 **Lazy env parsing is mandatory.** Cloudflare injects env bindings at request time via `injectEnvVars()`, after all static module imports complete. Never parse `process.env` at module top-level in Workers:
 
 ```ts