argsbarg 7.1.2 → 7.1.4

package/examples/mcp-plugin/justfile

@@ -7,12 +7,12 @@ export PATH := justfile_directory() + "/node_modules/.bin:" + env_var("PATH")
 _:
     @just --list
 
-# Bundle the standalone Node MCP server script
-build:
-    bun build ./src/index.ts --target=node --outfile=./scripts/mcp.mjs
+# Run schemagen, format, typecheck, and rebuild the committed Node bundle
+check: schemagen format typecheck build
 
-# Run schemagen, typecheck, and format
-check: schemagen format typecheck
+# Bundle the Node MCP server that plugins run (commit dist/mcp-plugin.mjs)
+build: schemagen
+    bun build ./src/index.ts --target=node --minify-whitespace --minify-syntax --outfile=./dist/mcp-plugin.mjs
 
 # demo the HTTP API
 demo-http:
@@ -52,16 +52,21 @@ format:
 http:
     @just run http
 
+# Lint sources without writing
+lint:
+    bun run biome check ./src ./scripts
+
+# Install the Claude Code plugin from this checkout (restart Claude Code afterwards)
+plugin-claude-install: build
+    claude plugin marketplace add "$(pwd)"
+    claude plugin install mcp-plugin@mcp-plugin
+
 # Link plugin into ~/.cursor/plugins/local/mcp-plugin for local testing
-install-plugin-cursor: build
+plugin-cursor-upsert: build
     mkdir -p ~/.cursor/plugins/local
     ln -sfn '{{justfile_directory()}}' ~/.cursor/plugins/local/mcp-plugin
     @echo "Linked MCP plugin to ~/.cursor/plugins/local/mcp-plugin"
 
-# Lint sources without writing
-lint:
-    bun run biome check ./src ./scripts
-
 # Run the CLI from source once
 run *ARGS:
     bun ./src/index.ts {{ARGS}}
@@ -73,14 +78,14 @@ schemagen:
 # Install bun/npm dependencies and generate schemas
 setup:
     bun install
-    test -f node_modules/argsbarg/bin/argsbarg && ln -sf ../argsbarg/bin/argsbarg node_modules/.bin/argsbarg
+    test -f node_modules/argsbarg/bin/argsbarg && ln -sf ../argsbarg/bin/argsbarg node_modules/.bin/argsbarg # argsbarg-dev-only: fix link for file:../.. installs
     just schemagen
 
 # Run unit tests (after check)
 test: check
     bun test .
 
-# Bump version, build, publish release
+# Bump version, rebuild the bundle, and publish a release
 release *ARGS:
     bun scripts/release.ts {{ARGS}}
 

package/examples/mcp-plugin/package.json

@@ -6,11 +6,8 @@
   "module": "src/index.ts",
   "description": "Argsbarg MCP plugin template for Cursor and Claude Code marketplaces.",
   "engines": {
-    "bun": ">=1.3"
-  },
-  "scripts": {
-    "biome": "biome",
-    "start": "bun run src/index.ts"
+    "bun": ">=1.3",
+    "node": ">=20"
   },
   "dependencies": {
     "argsbarg": "file:../.."

package/examples/mcp-plugin/scripts/release.ts

@@ -1,6 +1,6 @@
 #!/usr/bin/env bun
 /*
-Bump version, build standalone Node MCP server, and publish release tag.
+Bump version, rebuild the committed Node bundle, and publish a plugin release tag.
 */
 
 import * as fs from "node:fs";
@@ -39,10 +39,7 @@ async function main(): Promise<void> {
 
 /** Prints usage and exits. */
 function usage(): never {
-  process.stderr.write(
-    "Usage:\n" +
-      "  bun scripts/release.ts <major|minor|patch> [--yes] [--dry-run]\n",
-  );
+  process.stderr.write("Usage:\n" + "  bun scripts/release.ts <major|minor|patch> [--yes] [--dry-run]\n");
   process.exit(1);
 }
 
@@ -76,26 +73,28 @@ async function runRelease(
   /** Parsed CLI options. */
   options: ReleaseOptions,
 ): Promise<void> {
+  const currentVersion = readCurrentVersion();
+  const newVersion = applyBump(currentVersion, bump);
+  if (options.dryRun) {
+    console.log(
+      `[dry-run] Would run checks, bump ${currentVersion} to ${newVersion}, update the changelog, regenerate docs, rebuild the bundle, commit, tag v${newVersion}, push, and create a GitHub release.`,
+    );
+    return;
+  }
+
   const testResult = await $`just test`.nothrow();
   if (testResult.exitCode !== 0) process.exit(testResult.exitCode);
 
-  const currentVersion = readCurrentVersion();
-  const newVersion = applyBump(currentVersion, bump);
   console.log(`Releasing ${currentVersion} → ${newVersion}`);
 
   updateVersion(newVersion);
   updateChangelog(newVersion);
 
-  const buildResult = await $`just build`.nothrow();
-  if (buildResult.exitCode !== 0) process.exit(buildResult.exitCode);
-
   const docgenResult = await $`just docgen`.nothrow();
   if (docgenResult.exitCode !== 0) process.exit(docgenResult.exitCode);
 
-  if (options.dryRun) {
-    console.log(`[dry-run] Would commit, tag v${newVersion}, and create GitHub release.`);
-    return;
-  }
+  const buildResult = await $`just build`.nothrow();
+  if (buildResult.exitCode !== 0) process.exit(buildResult.exitCode);
 
   await commitAndTag(newVersion);
   await createGithubRelease(`v${newVersion}`);
@@ -154,31 +153,19 @@ function updateVersion(
 ): void {
   const pkgPath = "package.json";
   const pkgContent = fs.readFileSync(pkgPath, "utf-8");
-  fs.writeFileSync(
-    pkgPath,
-    pkgContent.replace(/"version":\s*"[^"]+"/, `"version": "${newVersion}"`),
-  );
+  fs.writeFileSync(pkgPath, pkgContent.replace(/"version":\s*"[^"]+"/, `"version": "${newVersion}"`));
 
   const progContent = fs.readFileSync(programPath, "utf-8");
-  fs.writeFileSync(
-    programPath,
-    progContent.replace(/version:\s*"[^"]+"/, `version: "${newVersion}"`),
-  );
+  fs.writeFileSync(programPath, progContent.replace(/version:\s*"[^"]+"/, `version: "${newVersion}"`));
 
   if (fs.existsSync(cursorManifestPath)) {
     const cursorContent = fs.readFileSync(cursorManifestPath, "utf-8");
-    fs.writeFileSync(
-      cursorManifestPath,
-      cursorContent.replace(/"version":\s*"[^"]+"/, `"version": "${newVersion}"`),
-    );
+    fs.writeFileSync(cursorManifestPath, cursorContent.replace(/"version":\s*"[^"]+"/, `"version": "${newVersion}"`));
   }
 
   if (fs.existsSync(claudeManifestPath)) {
     const claudeContent = fs.readFileSync(claudeManifestPath, "utf-8");
-    fs.writeFileSync(
-      claudeManifestPath,
-      claudeContent.replace(/"version":\s*"[^"]+"/, `"version": "${newVersion}"`),
-    );
+    fs.writeFileSync(claudeManifestPath, claudeContent.replace(/"version":\s*"[^"]+"/, `"version": "${newVersion}"`));
   }
 }
 

package/examples/mcp-plugin/src/index.ts

@@ -1,4 +1,3 @@
-#!/usr/bin/env bun
 /*
 Thin CLI entry — delegates to argsbarg runtime.
 */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "argsbarg",
-  "version": "7.1.2",
+  "version": "7.1.4",
   "main": "./src/index.ts",
   "module": "./src/index.ts",
   "dependencies": {

package/src/cli-tool/create.test.ts

@@ -10,6 +10,7 @@ import {
   applyCreate,
   type CreateOptions,
   classNameFromKey,
+  DEV_ONLY_MARKER,
   diffCreate,
   diffCreateDetails,
   renderCreateTree,
@@ -38,6 +39,19 @@ function baseOpts(overrides: Partial<CreateOptions> = {}): CreateOptions {
 
 /** Tests for argsbarg create. */
 describe("argsbarg create", () => {
+  test("in-repo example templates match their own create output", () => {
+    for (const example of ["full-example", "full-example-json", "mcp-plugin"]) {
+      const dir = join(import.meta.dir, "../../examples", example);
+      expect({ example, drift: diffCreate(dir, { check: true }) }).toEqual({ example, drift: [] });
+    }
+  });
+
+  test("drops argsbarg-dev-only lines outside the in-repo template", () => {
+    const content = `setup:\n    bun install\n    ln -sf a b ${DEV_ONLY_MARKER}: fix link\n    just schemagen\n`;
+    expect(substituteTemplateContent(content, baseOpts())).toBe("setup:\n    bun install\n    just schemagen\n");
+    expect(substituteTemplateContent(content, baseOpts({ devTemplate: true }))).toBe(content);
+  });
+
   test("substitutes {key} tokens", () => {
     const out = substituteTemplateContent(
       "key={key} class={className} env={envPrefix}_API_TOKEN tap={tap} org={tapOrg}",

package/src/cli-tool/create.ts

@@ -263,6 +263,12 @@ function tokenMap(opts: CreateOptions): Record<string, string> {
   };
 }
 
+/**
+ * Trailing comment marking a template line that only makes sense inside the argsbarg repo (e.g. the
+ * `.bin/argsbarg` symlink fix for `file:../..` installs). `create` drops these lines from new projects.
+ */
+export const DEV_ONLY_MARKER = "# argsbarg-dev-only";
+
 /** Substitute \`{key}\`-style placeholders; also replace template identity literals. */
 export function substituteTemplateContent(content: string, opts: CreateOptions): string {
   const tmpl = templateIdentity(opts.templateId);
@@ -303,6 +309,9 @@ export function substituteTemplateContent(content: string, opts: CreateOptions):
 
   if (!opts.devTemplate) {
     out = out
+      .split("\n")
+      .filter((line) => !line.includes(DEV_ONLY_MARKER))
+      .join("\n")
       .replace(/"argsbarg":\s*"workspace:\*"/, `"argsbarg": "^${argsbargVersion}"`)
       .replace(/"argsbarg":\s*"file:\.\.\/\.\."/, `"argsbarg": "^${argsbargVersion}"`);
   }

package/src/cli-tool/main.ts

@@ -1,5 +1,5 @@
 #!/usr/bin/env bun
-/** Argsbarg package CLI (`bunx argsbarg`) — bootstrap and tooling; library API is `import from "argsbarg"`. */
+/** Argsbarg package CLI (`bun x argsbarg`) — bootstrap and tooling; library API is `import from "argsbarg"`. */
 
 import { Cli } from "../index.ts";
 import { program } from "./program.ts";

package/src/cli-tool/schemagen/run.ts

@@ -5,6 +5,7 @@ Generate JSON Schema artifacts under __generated__/ and write index.ts re-export
 import { mkdirSync, writeFileSync } from "node:fs";
 import { dirname, join, relative } from "node:path";
 import { createGenerator } from "ts-json-schema-generator";
+import { resolveJsonPointer } from "../../core/json-pointer.ts";
 import { cleanStaleGenerated } from "./cleanup.ts";
 import { discoverSchemaRoots, type SchemaRoot } from "./discover-schema-roots.ts";
 import { GENERATED_DIR, schemaExportName, schemaJsonBasename, schemaJsonImportVar } from "./names.ts";
@@ -46,11 +47,49 @@ function generateJson(projectRoot: string, tsconfigPath: string, root: SchemaRoo
     jsDoc: "extended",
     additionalProperties: false,
   });
-  const schema = generator.createSchema(root.typeName) as Record<string, unknown>;
-  schema.additionalProperties = false;
+  const schema = hoistRootRef(generator.createSchema(root.typeName) as Record<string, unknown>, root.typeName);
+  // Only object roots: on a union root with no root `properties`, this would reject every property.
+  if (schema.type === "object") {
+    schema.additionalProperties = false;
+  }
   return schema;
 }
 
+/**
+ * Replaces a root `$ref` with the definition it names, following alias chains
+ * (`export type Input = Inner` emits `{ $ref: "#/definitions/Inner" }` even with `topRef: false`).
+ * Keeps `definitions` so nested and recursive references still resolve.
+ */
+function hoistRootRef(
+  /** Schema from ts-json-schema-generator. */
+  schema: Record<string, unknown>,
+  /** Root type name, for error messages. */
+  typeName: string,
+): Record<string, unknown> {
+  let target = schema;
+  const seen = new Set<string>();
+  while (typeof target.$ref === "string") {
+    const ref = target.$ref;
+    if (seen.has(ref)) {
+      throw new Error(`schemagen: ${typeName} root $ref cycle at ${ref}`);
+    }
+    seen.add(ref);
+    const next = resolveJsonPointer(schema, ref);
+    if (typeof next !== "object" || next === null || Array.isArray(next)) {
+      throw new Error(`schemagen: ${typeName} root $ref does not resolve: ${ref}`);
+    }
+    target = next as Record<string, unknown>;
+  }
+  if (target === schema) {
+    return schema;
+  }
+  return {
+    ...(schema.$schema === undefined ? {} : { $schema: schema.$schema }),
+    ...target,
+    ...(schema.definitions === undefined ? {} : { definitions: schema.definitions }),
+  };
+}
+
 function writeGeneratedIndex(generatedDir: string, roots: SchemaRoot[]): void {
   const sorted = [...roots].sort((left, right) => left.typeName.localeCompare(right.typeName));
   const lines = ["// Auto-generated by argsbarg schemagen — do not edit by hand.", ""];

package/src/cli-tool/schemagen/schemagen.test.ts

@@ -48,7 +48,12 @@ function writeSrcFile(root: string, relPath: string, body: string): void {
 describe("schemagen", () => {
   test("discovers @sg types in full-example-json", () => {
     const roots = discoverSchemaRoots(exampleRoot);
-    expect(roots.map((r) => r.typeName).sort()).toEqual(["RenderJsonInput", "StatusJsonOutput", "WorkspaceNameInput"]);
+    expect(roots.map((r) => r.typeName).sort()).toEqual([
+      "RenderJsonInput",
+      "ShapeAreaInput",
+      "StatusJsonOutput",
+      "WorkspaceNameInput",
+    ]);
   });
 
   test("maps type names to __generated__ filenames and export names", () => {
@@ -58,7 +63,7 @@ describe("schemagen", () => {
 
   test("runSchemagen writes __generated__ artifacts in full-example-json", () => {
     const counts = runSchemagen({ projectRoot: exampleRoot });
-    expect(counts).toEqual({ schemas: 3 });
+    expect(counts).toEqual({ schemas: 4 });
   });
 
   test("discovers @sg roots and writes named schema artifacts", () => {
@@ -230,4 +235,84 @@ export interface DupType {
 
     expect(() => discoverSchemaRoots(root)).toThrow("duplicate schema root type DupType");
   });
+
+  describe("root normalization", () => {
+    /** Writes one `@sg` type (plus helper types) and returns its generated schema. */
+    function generate(typeName: string, body: string): Record<string, unknown> {
+      const root = makeTempProject();
+      writeSrcFile(root, "src/commands/demo/types.ts", body);
+      runSchemagen({ projectRoot: root });
+      const path = join(root, "src/commands/demo/__generated__", schemaJsonBasename(typeName));
+      return JSON.parse(readFileSync(path, "utf8")) as Record<string, unknown>;
+    }
+
+    test("hoists an alias root $ref to an object root", () => {
+      const schema = generate(
+        "AliasInput",
+        `export interface Inner {
+  name: string;
+}
+/** @sg */
+export type AliasInput = Inner;
+`,
+      );
+      expect(schema.$ref).toBeUndefined();
+      expect(schema.type).toBe("object");
+      expect(schema.properties).toEqual({ name: { type: "string" } });
+      expect(schema.additionalProperties).toBe(false);
+    });
+
+    test("follows alias chains and percent-encoded generic refs", () => {
+      const chain = generate(
+        "ChainInput",
+        `export interface Inner {
+  name: string;
+}
+export type Mid = Inner;
+/** @sg */
+export type ChainInput = Mid;
+`,
+      );
+      expect(chain.type).toBe("object");
+      expect(chain.properties).toEqual({ name: { type: "string" } });
+
+      const generic = generate(
+        "GenericInput",
+        `export interface Box<T> {
+  value: T;
+}
+/** @sg */
+export type GenericInput = Box<string>;
+`,
+      );
+      expect(generic.type).toBe("object");
+      expect(generic.properties).toEqual({ value: { type: "string" } });
+    });
+
+    test("keeps definitions so recursive references still resolve", () => {
+      const schema = generate(
+        "TreeInput",
+        `export interface Tree {
+  name: string;
+  children?: Tree[];
+}
+/** @sg */
+export type TreeInput = Tree;
+`,
+      );
+      expect(schema.type).toBe("object");
+      expect((schema.definitions as Record<string, unknown>).Tree).toBeDefined();
+    });
+
+    test("leaves union roots without a root additionalProperties", () => {
+      const schema = generate(
+        "UnionInput",
+        `/** @sg */
+export type UnionInput = { kind: "a"; a: string } | { kind: "b"; b: number };
+`,
+      );
+      expect(Array.isArray(schema.anyOf)).toBe(true);
+      expect(schema.additionalProperties).toBeUndefined();
+    });
+  });
 });

package/src/config/validate.ts

@@ -5,6 +5,7 @@ CLI value coercion for configure set remains here (comma-separated arrays, boole
 
 import { format as jsonSchemaFormats, type Schema, type SchemaDraft, Validator } from "@cfworker/json-schema";
 import { parseCommaList, parseDate, parseDateTime, validateCommaList } from "../core/formats.ts";
+import { decodeJsonPointerSegment, resolveJsonPointer } from "../core/json-pointer.ts";
 import { isFrameworkConfigKey } from "./bindings.ts";
 
 type JsonSchema = Record<string, unknown>;
@@ -72,10 +73,6 @@ function formatInstancePath(instanceLocation: string): string {
   return instanceLocation;
 }
 
-function decodeJsonPointerSegment(segment: string): string {
-  return segment.replace(/~1/g, "/").replace(/~0/g, "~");
-}
-
 /** cfworker keywords that only wrap a deeper, more specific failure — dropped when one survives underneath. */
 const WRAPPER_KEYWORDS = new Set([
   "$ref",
@@ -235,8 +232,12 @@ function unionDiscriminator(branches: unknown[], root: JsonSchema): UnionDiscrim
   if (eligible.length === 0) {
     return undefined;
   }
-  const prop = eligible.includes("kind") ? "kind" : eligible.includes("type") ? "type" : [...eligible].sort()[0]!;
-  return { prop, valuesByBranch: branchValuesFor(prop)! };
+  const prop = eligible.includes("kind") ? "kind" : eligible.includes("type") ? "type" : [...eligible].sort()[0];
+  const valuesByBranch = prop === undefined ? undefined : branchValuesFor(prop);
+  if (prop === undefined || valuesByBranch === undefined) {
+    return undefined;
+  }
+  return { prop, valuesByBranch };
 }
 
 /** Sorted, comma-joined, unquoted list of values for error messages. */
@@ -248,7 +249,7 @@ function joinSorted(values: Iterable<string>): string {
 function rewriteErrorMessage(err: RawError, root: JsonSchema): string {
   const additionalPropsMatch = /^Property "(.+)" does not match additional properties schema\.$/.exec(err.error);
   if (additionalPropsMatch) {
-    const name = additionalPropsMatch[1]!;
+    const name = additionalPropsMatch[1] ?? "";
     const parentLoc = parentPointer(err.keywordLocation);
     const parentSchema = parentLoc ? schemaAtPointer(root, parentLoc) : undefined;
     const props =
@@ -268,7 +269,7 @@ function rewriteErrorMessage(err: RawError, root: JsonSchema): string {
   const enumMatch = /^Instance does not match any of (\[.*\])\.$/.exec(err.error);
   if (enumMatch) {
     try {
-      const values = JSON.parse(enumMatch[1]!) as unknown[];
+      const values = JSON.parse(enumMatch[1] ?? "") as unknown[];
       return `must be one of: ${values.map((v) => String(v)).join(", ")}`;
     } catch {
       // fall through to the raw message
@@ -394,16 +395,16 @@ function narrowUnionErrors(errors: RawError[], root: JsonSchema, data: unknown):
   for (const err of errors) {
     if (dropped.has(err)) continue;
     if (err.keyword === "additionalProperties") {
-      const match = /^Property "(.+)" does not match additional properties schema\.$/.exec(err.error);
+      const name = /^Property "(.+)" does not match additional properties schema\.$/.exec(err.error)?.[1];
       const parentLoc = parentPointer(err.keywordLocation);
       const parentSchema = parentLoc ? schemaAtPointer(root, parentLoc) : undefined;
       const props =
-        match && parentSchema && typeof parentSchema === "object" && !Array.isArray(parentSchema)
+        name !== undefined && parentSchema && typeof parentSchema === "object" && !Array.isArray(parentSchema)
           ? (parentSchema as JsonSchema).properties
           : undefined;
       const declared =
-        match && props && typeof props === "object" && !Array.isArray(props)
-          ? Object.hasOwn(props as JsonSchema, match[1]!)
+        name !== undefined && props && typeof props === "object" && !Array.isArray(props)
+          ? Object.hasOwn(props as JsonSchema, name)
           : false;
       if (declared) dropped.add(err);
       continue;
@@ -450,25 +451,6 @@ export function resolveSchemaDraft(schema: JsonSchema): SchemaDraft {
   return "7";
 }
 
-function resolveJsonPointer(root: JsonSchema, ref: string): unknown {
-  if (!ref.startsWith("#/")) {
-    return undefined;
-  }
-  const segments = ref
-    .slice(2)
-    .split("/")
-    .filter((segment) => segment.length > 0)
-    .map(decodeJsonPointerSegment);
-  let current: unknown = root;
-  for (const segment of segments) {
-    if (typeof current !== "object" || current === null || Array.isArray(current)) {
-      return undefined;
-    }
-    current = (current as Record<string, unknown>)[segment];
-  }
-  return current;
-}
-
 function attachRootCompanionSchemas(validator: Validator, root: JsonSchema, active: JsonSchema): void {
   if (active === root) {
     return;

package/src/core/json-pointer.ts

@@ -0,0 +1,46 @@
+/*
+Same-document JSON Pointer resolution for JSON Schema `$ref` values (`#/definitions/Foo`).
+Shared by schemagen root hoisting, MCP tool schema checks, config validation, and OpenAPI dereferencing.
+*/
+
+/**
+ * Decodes one JSON Pointer segment: URI percent-escapes first (ts-json-schema-generator writes
+ * `#/definitions/Box%3Cstring%3E`), then the `~1` → `/` and `~0` → `~` pointer escapes.
+ */
+export function decodeJsonPointerSegment(
+  /** Raw segment between `/` separators. */
+  segment: string,
+): string {
+  let decoded = segment;
+  try {
+    decoded = decodeURIComponent(segment);
+  } catch {
+    // Malformed percent-escape: fall back to the raw segment.
+  }
+  return decoded.replace(/~1/g, "/").replace(/~0/g, "~");
+}
+
+/** Resolves a same-document JSON Pointer (`#/definitions/Foo`) against `root`; `undefined` when it does not resolve. */
+export function resolveJsonPointer(
+  /** Document the pointer is resolved against (the schema root). */
+  root: unknown,
+  /** `$ref` value; only `#/…` pointers are resolved. */
+  ref: string,
+): unknown {
+  if (!ref.startsWith("#/")) {
+    return undefined;
+  }
+  const segments = ref
+    .slice(2)
+    .split("/")
+    .filter((segment) => segment.length > 0)
+    .map(decodeJsonPointerSegment);
+  let current: unknown = root;
+  for (const segment of segments) {
+    if (typeof current !== "object" || current === null || Array.isArray(current)) {
+      return undefined;
+    }
+    current = (current as Record<string, unknown>)[segment];
+  }
+  return current;
+}

package/src/core/validate.ts

@@ -5,9 +5,10 @@ This module validates CLI schemas before execution.
 import { reservedDocsTopicResourceUris } from "../docs/mcp-resources.ts";
 import { DOCS_BUILTIN_TOPIC_KEYS, docsEnabled } from "../docs/resolve.ts";
 import { HTTP_RESERVED_TOP_LEVEL_SEGMENTS } from "../http/paths.ts";
-import { resolveMcpSchemaUri } from "../mcp/tools.ts";
+import { collectMcpTools, resolveMcpSchemaUri } from "../mcp/tools.ts";
 import { reservedCommandNames, resolveCapabilities } from "../runtime/capabilities.ts";
 import { validateFormatValue } from "./formats.ts";
+import { resolveJsonPointer } from "./json-pointer.ts";
 import {
   type CliLeaf,
   type CliNode,
@@ -196,6 +197,68 @@ export function cliValidateProgram(program: CliProgram): void {
   }
 
   walkNode(program, program, true);
+
+  if (caps.mcp) {
+    validateMcpToolSchemas(program);
+  }
+}
+
+/** Keywords whose values are instance data, not subschemas; a `$ref` string inside them is not a reference. */
+const SCHEMA_DATA_KEYWORDS = new Set(["const", "default", "enum", "examples"]);
+
+/** Collects every `$ref` string in a schema (skipping instance-data keywords). */
+function collectSchemaRefs(
+  /** Schema fragment to walk. */
+  node: unknown,
+  /** Accumulator for found `$ref` values. */
+  out: string[],
+): string[] {
+  if (Array.isArray(node)) {
+    for (const item of node) {
+      collectSchemaRefs(item, out);
+    }
+  } else if (typeof node === "object" && node !== null) {
+    for (const [key, value] of Object.entries(node)) {
+      if (key === "$ref" && typeof value === "string") {
+        out.push(value);
+      } else if (!SCHEMA_DATA_KEYWORDS.has(key)) {
+        collectSchemaRefs(value, out);
+      }
+    }
+  }
+  return out;
+}
+
+/**
+ * Checks the schemas MCP clients will see (after object-root wrapping in `collectMcpTools`):
+ * every local `$ref` must resolve, and wrapped schemas cannot use `$ref: "#"` (it would point at the wrapper).
+ */
+function validateMcpToolSchemas(
+  /** Program with `mcpServer.enabled`. */
+  program: CliProgram,
+): void {
+  for (const tool of collectMcpTools(program)) {
+    const schemas = [
+      { label: "inputSchema", schema: tool.inputSchema, wrapped: tool.inputWrapped },
+      { label: "outputSchema", schema: tool.outputSchema, wrapped: tool.outputWrapped },
+    ];
+    for (const { label, schema, wrapped } of schemas) {
+      if (schema === undefined) {
+        continue;
+      }
+      for (const ref of collectSchemaRefs(schema, [])) {
+        if (ref === "#" && wrapped) {
+          throw new CliSchemaValidationError(
+            `MCP tool "${tool.name}" ${label} uses $ref "#" but its root is not type "object", so MCP wraps it; ` +
+              "reference a named definition instead",
+          );
+        }
+        if (ref.startsWith("#/") && resolveJsonPointer(schema, ref) === undefined) {
+          throw new CliSchemaValidationError(`MCP tool "${tool.name}" ${label} has an unresolved $ref: ${ref}`);
+        }
+      }
+    }
+  }
 }
 
 const PARAM_ROUTER_KEY = /^:[a-zA-Z][a-zA-Z0-9_]*$/;