argsbarg 7.1.1 → 7.1.3

package/src/docs/mcp-guide.ts

@@ -3,7 +3,15 @@ import { displayAppConfigPath } from "../config/file.ts";
 import { expectedMcpEntry } from "../configure/artifacts/mcp-config.ts";
 import { resolveClaudeDesktopMcpPath, userHome } from "../configure/artifacts/paths.ts";
 import { CliOptionKind, type CliProgram } from "../core/types.ts";
-import { collectMcpTools, leafWireOptions, type McpToolDef, mcpServerId, resolveMcpSchemaUri } from "../mcp/tools.ts";
+import {
+  collectMcpTools,
+  DEFAULT_MCP_SIZE_LIMITS,
+  leafWireOptions,
+  type McpToolDef,
+  mcpServerId,
+  mcpSizeReport,
+  resolveMcpSchemaUri,
+} from "../mcp/tools.ts";
 import { resolveCapabilities } from "../runtime/capabilities.ts";
 import { resolveDocsTopicResourceUri } from "./mcp-resources.ts";
 import { docsEnabled, docsUserTopicKeys, resolveDocsConfig } from "./resolve.ts";
@@ -173,6 +181,9 @@ export function generateMcpGuide(root: CliProgram): string {
     "| `tools/call` | Runs handlers headlessly; JSON stdout becomes `structuredContent` when valid |",
     `| Schema resource | \`${schemaUri}\` — same JSON as \`${root.key} docs cli-schema\` |`,
   );
+  if (mcp.instructions) {
+    lines.push(`| \`initialize.instructions\` | ${mcp.instructions} |`);
+  }
   if (docsEnabled(root)) {
     const docs = resolveDocsConfig(root);
     for (const key of docsUserTopicKeys(docs)) {
@@ -191,6 +202,37 @@ export function generateMcpGuide(root: CliProgram): string {
     lines.push("");
   }
 
+  const sizeReport = mcpSizeReport(root);
+  if (sizeReport.tools.length > 0) {
+    const limits = { ...DEFAULT_MCP_SIZE_LIMITS, ...root.mcpServer?.sizeLimits };
+    lines.push(
+      "## Tool sizes",
+      "",
+      `Clients read tool definitions with their own limits — a definition or description past those is truncated ` +
+        `or read incompletely. Default limits here: description ${limits.descriptionChars === false ? "unchecked" : `${limits.descriptionChars.toLocaleString()} chars`}, ` +
+        `definition ${limits.definitionBytes === false ? "unchecked" : `${limits.definitionBytes.toLocaleString()} bytes`} / ` +
+        `${limits.definitionLines === false ? "unchecked" : `${limits.definitionLines.toLocaleString()} lines`} (override with \`mcpServer.sizeLimits\`).`,
+      "",
+      "| Tool | Description (chars) | Definition (bytes) | Definition (lines) | Status |",
+      "| --- | --- | --- | --- | --- |",
+    );
+    for (const t of sizeReport.tools) {
+      const over: string[] = [];
+      if (limits.descriptionChars !== false && t.descriptionChars > limits.descriptionChars) over.push("description");
+      if (
+        (limits.definitionBytes !== false && t.definitionBytes > limits.definitionBytes) ||
+        (limits.definitionLines !== false && t.definitionLines > limits.definitionLines)
+      ) {
+        over.push("definition");
+      }
+      const status = over.length === 0 ? "ok" : `over: ${over.join(", ")}`;
+      lines.push(
+        `| \`${t.name}\` | ${t.descriptionChars.toLocaleString()} | ${t.definitionBytes.toLocaleString()} | ${t.definitionLines.toLocaleString()} | ${status} |`,
+      );
+    }
+    lines.push("");
+  }
+
   lines.push(
     "## Tool arguments",
     "",

package/src/headless/tool-call.test.ts

@@ -1,7 +1,15 @@
-/* Unit tests for shared headless error text (MCP and HTTP). */
+/* Unit tests for shared headless error text (MCP and HTTP) and wrapped MCP tool calls. */
 
 import { describe, expect, test } from "bun:test";
-import { type HeadlessToolCallFailure, headlessFailureMcpMessage, headlessFailureToHttpResponse } from "./tool-call.ts";
+import { Cli, type CliContext } from "../index.ts";
+import { collectMcpTools } from "../mcp/tools.ts";
+import { requireMcpTool, testProgram } from "../test/fixtures.ts";
+import {
+  executeHeadlessToolCall,
+  type HeadlessToolCallFailure,
+  headlessFailureMcpMessage,
+  headlessFailureToHttpResponse,
+} from "./tool-call.ts";
 
 /** Builds a failed headless result with the given error message. */
 function invokeFailure(
@@ -30,3 +38,67 @@ describe("headless error text", () => {
     expect(body.error).toBe(multiline);
   });
 });
+
+describe("wrapped MCP tools", () => {
+  /** Union input leaf that echoes its inputs; output is an array so structuredContent gets wrapped too. */
+  const program = testProgram({
+    key: "wrapcall",
+    description: "Wrapped call demo.",
+    mcpServer: { enabled: true },
+    commands: [
+      {
+        key: "edit",
+        description: "Edit.",
+        kind: "document",
+        inputSchema: {
+          anyOf: [{ $ref: "#/definitions/Append" }, { $ref: "#/definitions/Replace" }],
+          definitions: {
+            Append: {
+              type: "object",
+              properties: { kind: { const: "append" }, text: { type: "string" } },
+              required: ["kind", "text"],
+              additionalProperties: false,
+            },
+            Replace: {
+              type: "object",
+              properties: { kind: { const: "replace" }, find: { type: "string" }, text: { type: "string" } },
+              required: ["kind", "find", "text"],
+              additionalProperties: false,
+            },
+          },
+        },
+        outputSchema: { type: "array" },
+        handler: (ctx: CliContext) => [ctx.inputs],
+      },
+    ],
+  });
+  const cli = new Cli(program);
+  const tool = requireMcpTool(collectMcpTools(program), "edit");
+
+  test("unwraps input and wraps structuredContent under result", async () => {
+    const result = await executeHeadlessToolCall(cli, tool, { input: { kind: "append", text: "hi" } }, "mcp");
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.mcpResult.structuredContent).toEqual({ result: [{ kind: "append", text: "hi" }] });
+    }
+  });
+
+  test("still validates the exact union after unwrapping", async () => {
+    const result = await executeHeadlessToolCall(
+      cli,
+      tool,
+      { input: { kind: "append", text: "hi", find: "x" } },
+      "mcp",
+    );
+    expect(result.ok).toBe(false);
+  });
+
+  test("rejects arguments that are not wrapped", async () => {
+    const result = await executeHeadlessToolCall(cli, tool, { kind: "append", text: "hi" }, "mcp");
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.kind).toBe("argv");
+      expect(result.message).toContain('single "input" object property');
+    }
+  });
+});

package/src/headless/tool-call.ts

@@ -10,7 +10,13 @@ import { apiErrorResponse, apiSuccessResponse, stripAnsi } from "../http/result.
 import { type HttpRouteDef, httpRequestToArgv } from "../http/routes.ts";
 import { obscureUnexpectedClientMessage } from "../log/emitter.ts";
 import { buildToolCallSuccessFromResponse } from "../mcp/result.ts";
-import { collectMcpTools, type McpToolDef, mcpToolCallToArgv } from "../mcp/tools.ts";
+import {
+  collectMcpTools,
+  MCP_INPUT_WRAPPER_KEY,
+  MCP_OUTPUT_WRAPPER_KEY,
+  type McpToolDef,
+  mcpToolCallToArgv,
+} from "../mcp/tools.ts";
 import type { Cli, CliInvokeResult } from "../runtime/cli.ts";
 
 /** Outcome of resolving a tool name against the program schema. */
@@ -86,8 +92,31 @@ function noResponseFailure(result: CliInvokeResult): HeadlessToolCallFailure {
   };
 }
 
+/** Pre-invoke argument failure (bad shape or argv conversion error). */
+function argvFailure(
+  /** Client-facing error message. */
+  message: string,
+): HeadlessToolCallFailure {
+  return { ok: false, kind: "argv", message, exitCode: 1, stdout: "", stderr: "", failureKind: "validation" };
+}
+
+/** Returns the leaf input from wrapped tool arguments (`{ input: {...} }`), or `undefined` when malformed. */
+function unwrapToolArgs(
+  /** Raw tools/call arguments. */
+  args: Record<string, unknown>,
+): Record<string, unknown> | undefined {
+  const inner = args[MCP_INPUT_WRAPPER_KEY];
+  const onlyWrapperKey = Object.keys(args).every((key) => key === MCP_INPUT_WRAPPER_KEY);
+  if (!onlyWrapperKey || typeof inner !== "object" || inner === null || Array.isArray(inner)) {
+    return undefined;
+  }
+  return inner as Record<string, unknown>;
+}
+
 /**
  * Converts flat tool arguments to argv and invokes the leaf handler headlessly.
+ * Wrapped tools (see `wrapMcpRootSchema`) receive `{ input: {...} }`, unwrapped here, and return
+ * `structuredContent` wrapped as `{ result: ... }` to match their `outputSchema`.
  */
 export async function executeHeadlessToolCall(
   cli: Cli,
@@ -96,20 +125,19 @@ export async function executeHeadlessToolCall(
   invocation: CliInvocation,
   mcp?: { rpcMethod: string; toolName?: string; requestId: string },
 ): Promise<HeadlessToolCallResult> {
-  const argvResult = mcpToolCallToArgv(cli.program, tool, args);
+  const leafArgs = tool.inputWrapped ? unwrapToolArgs(args) : args;
+  if (leafArgs === undefined) {
+    return argvFailure(
+      `Tool arguments must be an object with a single "${MCP_INPUT_WRAPPER_KEY}" object property (see inputSchema)`,
+    );
+  }
+
+  const argvResult = mcpToolCallToArgv(cli.program, tool, leafArgs);
   if ("error" in argvResult) {
-    return {
-      ok: false,
-      kind: "argv",
-      message: argvResult.error,
-      exitCode: 1,
-      stdout: "",
-      stderr: "",
-      failureKind: "validation",
-    };
+    return argvFailure(argvResult.error);
   }
 
-  const invokeResult = await cli.invoke(argvResult, { invocation, toolArgs: args, mcp });
+  const invokeResult = await cli.invoke(argvResult, { invocation, toolArgs: leafArgs, mcp });
   if (invokeResult.kind === "help") {
     return invokeFailure(invokeResult);
   }
@@ -119,7 +147,9 @@ export async function executeHeadlessToolCall(
     return {
       ok: true,
       response: invokeResult.response,
-      mcpResult,
+      mcpResult: tool.outputWrapped
+        ? { ...mcpResult, structuredContent: { [MCP_OUTPUT_WRAPPER_KEY]: mcpResult.structuredContent } }
+        : mcpResult,
     };
   }
 
@@ -143,15 +173,7 @@ export async function executeHttpRouteCall(
 ): Promise<HeadlessToolCallResult> {
   const argvResult = httpRequestToArgv(cli.program, route, pathParams, query, body);
   if ("error" in argvResult) {
-    return {
-      ok: false,
-      kind: "argv",
-      message: argvResult.error,
-      exitCode: 1,
-      stdout: "",
-      stderr: "",
-      failureKind: "validation",
-    };
+    return argvFailure(argvResult.error);
   }
 
   const toolArgs = { ...body, ...query, ...pathParams };

package/src/http/schema-deref.ts

@@ -2,34 +2,12 @@
 Inline JSON Schema $ref dereferencing for OpenAPI embedding.
 */
 
-function decodeJsonPointerSegment(segment: string): string {
-  return segment.replace(/~1/g, "/").replace(/~0/g, "~");
-}
+import { resolveJsonPointer } from "../core/json-pointer.ts";
 
 function isPlainObject(value: unknown): value is Record<string, unknown> {
   return value !== null && typeof value === "object" && !Array.isArray(value);
 }
 
-/** Resolves a same-document JSON Pointer (`#/definitions/Foo`). */
-function resolveJsonPointer(root: Record<string, unknown>, 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 (!isPlainObject(current)) {
-      return undefined;
-    }
-    current = current[segment];
-  }
-  return current;
-}
-
 function derefValue(value: unknown, root: Record<string, unknown>, resolving: Set<string>): unknown {
   if (Array.isArray(value)) {
     return value.map((item) => derefValue(item, root, resolving));

package/src/index.ts

@@ -44,6 +44,7 @@ export type {
   CliMcpBundleConfig,
   CliMcpResource,
   CliMcpServerConfig,
+  CliMcpSizeLimits,
   CliMcpToolConfig,
   CliMcpWireContext,
   CliMcpWireHooks,
@@ -87,6 +88,8 @@ export type { EcsLogEvent, LogEnrichContext } from "./log/ecs.ts";
 export { ECS_VERSION, formatEcsLine } from "./log/ecs.ts";
 export type { McpBundlePaths, PackMcpBundleOpts } from "./mcp/bundle.ts";
 export { defaultMcpBundlePaths, generateMcpManifest, packMcpBundle } from "./mcp/bundle.ts";
+export type { McpSizeReport, McpToolSize } from "./mcp/tools.ts";
+export { DEFAULT_MCP_SIZE_LIMITS, mcpSizeReport } from "./mcp/tools.ts";
 export { userHome } from "./paths/host.ts";
 export { Cli, type CliInvokeKind, type CliInvokeResult } from "./runtime/cli.ts";
 export { cliErrWithHelp } from "./runtime/cli-errors.ts";

package/src/mcp/server.ts

@@ -8,7 +8,11 @@ import { executeHeadlessToolCall, headlessFailureMcpMessage, lookupHeadlessTool
 import type { Cli } from "../runtime/cli.ts";
 import { allMcpResources, collectMcpTools, resolveMcpServerInfo } from "./tools.ts";
 
-const MCP_PROTOCOL_VERSION = "2024-11-05";
+/** Protocol versions this server understands, newest first. `initialize` echoes a match or answers the first. */
+export const MCP_PROTOCOL_VERSIONS = ["2025-06-18", "2024-11-05"] as const;
+
+/** The first protocol version to define `outputSchema` (tools/list) and `structuredContent` (tools/call). */
+const MCP_STRUCTURED_OUTPUT_SINCE = "2025-06-18";
 
 /** JSON-RPC request shape from stdin. */
 interface JsonRpcRequest {
@@ -35,6 +39,13 @@ function writeError(id: string | number | null | undefined, code: number, messag
   });
 }
 
+/** True when `version` is at or after {@link MCP_STRUCTURED_OUTPUT_SINCE} in {@link MCP_PROTOCOL_VERSIONS}. */
+function supportsStructuredOutput(version: string | undefined): boolean {
+  const idx = version ? (MCP_PROTOCOL_VERSIONS as readonly string[]).indexOf(version) : -1;
+  const sinceIdx = (MCP_PROTOCOL_VERSIONS as readonly string[]).indexOf(MCP_STRUCTURED_OUTPUT_SINCE);
+  return idx !== -1 && idx <= sinceIdx;
+}
+
 /** Handles one NDJSON request line. */
 async function handleRequestLine(cli: Cli, line: string): Promise<void> {
   const root = cli.program;
@@ -98,13 +109,23 @@ async function handleRequestLine(cli: Cli, line: string): Promise<void> {
   try {
     if (method === "initialize") {
       const info = resolveMcpServerInfo(root);
+      const requested = params.protocolVersion;
+      const negotiated =
+        typeof requested === "string" && (MCP_PROTOCOL_VERSIONS as readonly string[]).includes(requested)
+          ? requested
+          : MCP_PROTOCOL_VERSIONS[0];
+      if (cli.server) {
+        cli.server.mcpProtocolVersion = negotiated;
+      }
+      const instructions = root.mcpServer?.instructions;
       writeResponse({
         jsonrpc: "2.0",
         id,
         result: {
-          protocolVersion: MCP_PROTOCOL_VERSION,
+          protocolVersion: negotiated,
           capabilities: { tools: {}, resources: {} },
           serverInfo: { name: info.name, version: info.version },
+          ...(instructions ? { instructions } : {}),
         },
       });
       await finish();
@@ -118,11 +139,12 @@ async function handleRequestLine(cli: Cli, line: string): Promise<void> {
     }
 
     if (method === "tools/list") {
+      const structured = supportsStructuredOutput(cli.server?.mcpProtocolVersion);
       const tools = collectMcpTools(root).map((t) => ({
         name: t.name,
         description: t.description,
         inputSchema: t.inputSchema,
-        ...(t.outputSchema === undefined ? {} : { outputSchema: t.outputSchema }),
+        ...(structured && t.outputSchema !== undefined ? { outputSchema: t.outputSchema } : {}),
       }));
       writeResponse({ jsonrpc: "2.0", id, result: { tools } });
       await finish();
@@ -168,10 +190,12 @@ async function handleRequestLine(cli: Cli, line: string): Promise<void> {
         { rpcMethod: method, toolName: name, requestId },
       );
       if (invokeResult.ok) {
+        const structured = supportsStructuredOutput(cli.server?.mcpProtocolVersion);
+        const { structuredContent: _structuredContent, ...rest } = invokeResult.mcpResult;
         writeResponse({
           jsonrpc: "2.0",
           id,
-          result: invokeResult.mcpResult,
+          result: structured ? invokeResult.mcpResult : rest,
         });
         await finish();
         return;

package/src/mcp/tools.test.ts

@@ -0,0 +1,292 @@
+/*
+Tests for mcp/tools module: MCP tool derivation, size reporting, per-leaf MCP-only notes,
+object-root schema wrapping, and the MCP tool schema startup check.
+*/
+
+import { describe, expect, test } from "bun:test";
+import { cliPresentationRoot } from "../builtins/presentation.ts";
+import { CliOptionKind } from "../core/types.ts";
+import { cliValidateProgram } from "../core/validate.ts";
+import { cliHelpRender } from "../help.ts";
+import { requireMcpTool, testProgram } from "../test/fixtures.ts";
+import {
+  collectMcpTools,
+  DEFAULT_MCP_SIZE_LIMITS,
+  MCP_INPUT_WRAPPER_KEY,
+  mcpSizeReport,
+  wrapMcpRootSchema,
+} from "./tools.ts";
+
+describe("mcpSizeReport", () => {
+  test("measures description and pretty definition against a hand-built JSON.stringify", () => {
+    const program = testProgram({
+      key: "sizetest",
+      description: "size test",
+      mcpServer: { enabled: true },
+      commands: [{ key: "run", description: "Run it.", handler: () => {} }],
+    });
+    const report = mcpSizeReport(program);
+    const [tool] = collectMcpTools(program);
+    expect(tool).toBeDefined();
+
+    const expectedJson = JSON.stringify(
+      { name: tool?.name, description: tool?.description, inputSchema: tool?.inputSchema },
+      null,
+      2,
+    );
+    expect(report.tools).toHaveLength(1);
+    expect(report.tools[0]).toEqual({
+      name: tool?.name,
+      descriptionChars: tool?.description.length,
+      definitionBytes: Buffer.byteLength(expectedJson, "utf8"),
+      definitionLines: expectedJson.split("\n").length,
+    });
+    expect(report.warnings).toEqual([]);
+    expect(report.instructionsChars).toBe(0);
+  });
+
+  test("warns past default limits for description and definition size", () => {
+    const program = testProgram({
+      key: "sizetest2",
+      description: "size test 2",
+      mcpServer: { enabled: true },
+      commands: [
+        {
+          key: "small",
+          description: "Small tool.",
+          notes: "x".repeat(3_000),
+          handler: () => {},
+        },
+        {
+          key: "big",
+          description: "Big tool.",
+          options: [
+            {
+              name: "mode",
+              description: "Mode.",
+              kind: CliOptionKind.Enum,
+              choices: Array.from({ length: 4_000 }, (_, i) => `choice-${i}`),
+            },
+          ],
+          handler: () => {},
+        },
+      ],
+    });
+    const report = mcpSizeReport(program);
+
+    const smallWarning = report.warnings.find((w) => w.includes('"small"'));
+    expect(smallWarning).toBeDefined();
+    expect(smallWarning).toContain("description is");
+    expect(smallWarning).toContain(`limit ${DEFAULT_MCP_SIZE_LIMITS.descriptionChars.toLocaleString()}`);
+
+    const bigWarning = report.warnings.find((w) => w.includes('"big"'));
+    expect(bigWarning).toBeDefined();
+    expect(bigWarning).toContain("definition is");
+    expect(bigWarning).toContain("pretty-printed");
+  });
+
+  test("sizeLimits overrides raise or lower the threshold", () => {
+    const program = testProgram({
+      key: "sizetest3",
+      description: "size test 3",
+      mcpServer: { enabled: true, sizeLimits: { descriptionChars: 5 } },
+      commands: [
+        { key: "run", description: "Run it, with a description longer than five characters.", handler: () => {} },
+      ],
+    });
+    const report = mcpSizeReport(program);
+    expect(report.warnings.some((w) => w.includes("description is"))).toBe(true);
+  });
+
+  test("sizeLimits: false disables a check entirely", () => {
+    const program = testProgram({
+      key: "sizetest4",
+      description: "size test 4",
+      mcpServer: { enabled: true, sizeLimits: { descriptionChars: false } },
+      commands: [
+        { key: "run", description: "Run it, with a description longer than five characters.", handler: () => {} },
+      ],
+    });
+    const report = mcpSizeReport(program);
+    expect(report.warnings.some((w) => w.includes("description is"))).toBe(false);
+  });
+
+  test("warns when instructions exceed the limit", () => {
+    const program = testProgram({
+      key: "sizetest5",
+      description: "size test 5",
+      mcpServer: { enabled: true, instructions: "x".repeat(3_000) },
+      commands: [{ key: "run", description: "Run it.", handler: () => {} }],
+    });
+    const report = mcpSizeReport(program);
+    expect(report.instructionsChars).toBe(3_000);
+    expect(report.warnings.some((w) => w.startsWith("MCP instructions are"))).toBe(true);
+  });
+});
+
+describe("mcpTool.notes", () => {
+  function programWithNotesOverride(notesOverride: string | false | undefined) {
+    return testProgram({
+      key: "notestest",
+      description: "notes test",
+      mcpServer: { enabled: true },
+      commands: [
+        {
+          key: "run",
+          description: "Run it.",
+          notes: "Original CLI notes.",
+          ...(notesOverride === undefined ? {} : { mcpTool: { notes: notesOverride } }),
+          handler: () => {},
+        },
+      ],
+    });
+  }
+
+  test("false omits notes from the MCP description", () => {
+    const [tool] = collectMcpTools(programWithNotesOverride(false));
+    expect(tool?.description).not.toContain("Original CLI notes.");
+  });
+
+  test("a string replaces the leaf's notes in the MCP description", () => {
+    const [tool] = collectMcpTools(programWithNotesOverride("Custom MCP-only note."));
+    expect(tool?.description).toContain("Custom MCP-only note.");
+    expect(tool?.description).not.toContain("Original CLI notes.");
+  });
+
+  test("omitted falls through to the leaf's own notes", () => {
+    const [tool] = collectMcpTools(programWithNotesOverride(undefined));
+    expect(tool?.description).toContain("Original CLI notes.");
+  });
+
+  test("CLI help always shows the leaf's own notes regardless of mcpTool.notes", () => {
+    const program = programWithNotesOverride(false);
+    const help = cliHelpRender(cliPresentationRoot(program), ["run"], false);
+    expect(help).toContain("Original CLI notes.");
+  });
+});
+
+/** Discriminated-union input: `anyOf` root with `$ref` branches, as ts-json-schema-generator writes it. */
+const unionInputSchema: Record<string, unknown> = {
+  $schema: "http://json-schema.org/draft-07/schema#",
+  description: "Edit operation.",
+  anyOf: [{ $ref: "#/definitions/Append" }, { $ref: "#/definitions/Replace" }],
+  definitions: {
+    Append: {
+      type: "object",
+      properties: { kind: { const: "append" }, text: { type: "string" } },
+      required: ["kind", "text"],
+      additionalProperties: false,
+    },
+    Replace: {
+      type: "object",
+      properties: { kind: { const: "replace" }, find: { type: "string" }, text: { type: "string" } },
+      required: ["kind", "find", "text"],
+      additionalProperties: false,
+    },
+  },
+};
+
+describe("MCP object-root wrapping", () => {
+  test("object-rooted schemas pass through unchanged", () => {
+    const schema = { type: "object", properties: { a: { type: "string" } } };
+    expect(wrapMcpRootSchema(schema, MCP_INPUT_WRAPPER_KEY)).toEqual({ schema, wrapped: false });
+  });
+
+  test("union roots wrap under input with $schema and definitions moved to the new root", () => {
+    const { schema, wrapped } = wrapMcpRootSchema(unionInputSchema, MCP_INPUT_WRAPPER_KEY);
+    expect(wrapped).toBe(true);
+    expect(schema).toEqual({
+      $schema: unionInputSchema.$schema,
+      type: "object",
+      properties: { input: { description: "Edit operation.", anyOf: unionInputSchema.anyOf } },
+      required: ["input"],
+      additionalProperties: false,
+      definitions: unionInputSchema.definitions,
+    });
+  });
+
+  test("collectMcpTools wraps non-object input and output schemas and flags them", () => {
+    const program = testProgram({
+      key: "wrapapp",
+      description: "Wrap demo.",
+      mcpServer: { enabled: true },
+      commands: [
+        {
+          key: "edit",
+          description: "Edit.",
+          kind: "document",
+          inputSchema: unionInputSchema,
+          outputSchema: { type: "array", items: { type: "string" } },
+          handler: () => [],
+        },
+        { key: "plain", description: "Plain.", handler: () => {} },
+      ],
+    });
+    const tools = collectMcpTools(program);
+    const edit = requireMcpTool(tools, "edit");
+    expect(edit.inputWrapped).toBe(true);
+    expect(edit.inputSchema.type).toBe("object");
+    expect(edit.outputWrapped).toBe(true);
+    expect(edit.outputSchema).toEqual({
+      type: "object",
+      properties: { result: { type: "array", items: { type: "string" } } },
+      required: ["result"],
+      additionalProperties: false,
+    });
+    const plain = requireMcpTool(tools, "plain");
+    expect(plain.inputWrapped).toBe(false);
+    expect(plain.outputWrapped).toBe(false);
+  });
+});
+
+describe("MCP tool schema startup check", () => {
+  /** Program with one document leaf using `inputSchema`, MCP on or off. */
+  function schemaProgram(inputSchema: Record<string, unknown>, mcpEnabled: boolean) {
+    return testProgram({
+      key: "checkapp",
+      description: "Check demo.",
+      ...(mcpEnabled ? { mcpServer: { enabled: true } } : {}),
+      commands: [{ key: "run", description: "Run.", kind: "document", inputSchema, handler: () => {} }],
+    });
+  }
+
+  test("accepts wrapped schemas whose definitions still resolve", () => {
+    expect(() => cliValidateProgram(schemaProgram(unionInputSchema, true))).not.toThrow();
+  });
+
+  test("rejects an unresolved local $ref when MCP is enabled", () => {
+    const dangling = { $ref: "#/definitions/Missing", definitions: {} };
+    expect(() => cliValidateProgram(schemaProgram(dangling, true))).toThrow(
+      'MCP tool "run" inputSchema has an unresolved $ref: #/definitions/Missing',
+    );
+  });
+
+  test('rejects $ref "#" in a wrapped schema', () => {
+    const recursive = { anyOf: [{ type: "object" }, { type: "array", items: { $ref: "#" } }] };
+    expect(() => cliValidateProgram(schemaProgram(recursive, true))).toThrow('uses $ref "#"');
+  });
+
+  test("skips the check when MCP is disabled", () => {
+    const dangling = { $ref: "#/definitions/Missing", definitions: {} };
+    expect(() => cliValidateProgram(schemaProgram(dangling, false))).not.toThrow();
+  });
+
+  test("skips MCP-hidden leaves", () => {
+    const program = testProgram({
+      key: "checkapp",
+      description: "Check demo.",
+      mcpServer: { enabled: true },
+      commands: [
+        {
+          key: "run",
+          description: "Run.",
+          kind: "document",
+          inputSchema: { $ref: "#/definitions/Missing", definitions: {} },
+          mcpTool: { hidden: true },
+          handler: () => {},
+        },
+      ],
+    });
+    expect(() => cliValidateProgram(program)).not.toThrow();
+  });
+});