argsbarg 7.1.2 → 7.1.4

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/mcp/tools.test.ts

@@ -1,13 +1,21 @@
 /*
-Tests for mcp/tools module: MCP tool derivation, size reporting, and per-leaf MCP-only notes.
+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 { testProgram } from "../test/fixtures.ts";
-import { collectMcpTools, DEFAULT_MCP_SIZE_LIMITS, mcpSizeReport } from "./tools.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", () => {
@@ -156,3 +164,129 @@ describe("mcpTool.notes", () => {
     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();
+  });
+});

package/src/mcp/tools.ts

@@ -49,10 +49,51 @@ export interface McpToolDef {
   path: string[];
   /** Leaf command node. */
   leaf: CliLeaf;
-  /** JSON Schema for tools/call arguments. */
+  /** JSON Schema for tools/call arguments (wrapped under {@link MCP_INPUT_WRAPPER_KEY} when not object-rooted). */
   inputSchema: Record<string, unknown>;
-  /** JSON Schema for structured tool results when set on the leaf `mcpTool`. */
+  /** True when {@link inputSchema} wraps the leaf schema; tools/call arguments are unwrapped before invoke. */
+  inputWrapped: boolean;
+  /** JSON Schema for structured tool results (wrapped under {@link MCP_OUTPUT_WRAPPER_KEY} when not object-rooted). */
   outputSchema?: Record<string, unknown>;
+  /** True when {@link outputSchema} wraps the leaf schema; `structuredContent` is wrapped to match. */
+  outputWrapped: boolean;
+}
+
+/** Property holding the leaf input when an MCP `inputSchema` is wrapped to get an object root. */
+export const MCP_INPUT_WRAPPER_KEY = "input";
+
+/** Property holding the leaf result when an MCP `outputSchema` is wrapped to get an object root. */
+export const MCP_OUTPUT_WRAPPER_KEY = "result";
+
+/**
+ * MCP requires `type: "object"` at the root of tool input and output schemas. Returns object-rooted
+ * schemas unchanged; wraps anything else (e.g. a discriminated-union `anyOf` root) as a single
+ * required property, moving `$schema`, `$id`, `definitions`, and `$defs` up so `#/definitions/…`
+ * references still resolve.
+ */
+export function wrapMcpRootSchema(
+  /** Leaf input or output schema. */
+  schema: Record<string, unknown>,
+  /** Wrapper property name ({@link MCP_INPUT_WRAPPER_KEY} or {@link MCP_OUTPUT_WRAPPER_KEY}). */
+  key: string,
+): { schema: Record<string, unknown>; wrapped: boolean } {
+  if (schema.type === "object") {
+    return { schema, wrapped: false };
+  }
+  const { $schema, $id, definitions, $defs, ...inner } = schema;
+  return {
+    schema: {
+      ...($schema === undefined ? {} : { $schema }),
+      ...($id === undefined ? {} : { $id }),
+      type: "object",
+      properties: { [key]: inner },
+      required: [key],
+      additionalProperties: false,
+      ...(definitions === undefined ? {} : { definitions }),
+      ...($defs === undefined ? {} : { $defs }),
+    },
+    wrapped: true,
+  };
 }
 
 /** Builds MCP tool description: "{cli path} — {description}". */
@@ -163,14 +204,18 @@ export function collectMcpTools(root: CliProgram): McpToolDef[] {
       if (isMcpHidden(cmd)) {
         return;
       }
-      const outputSchema = leafOutputSchema(cmd);
+      const input = wrapMcpRootSchema(buildLeafInputSchema(cmd), MCP_INPUT_WRAPPER_KEY);
+      const leafOutput = leafOutputSchema(cmd);
+      const output = leafOutput === undefined ? undefined : wrapMcpRootSchema(leafOutput, MCP_OUTPUT_WRAPPER_KEY);
       out.push({
         name: mcpToolName(root, path),
         description: resolveToolDescription(root, path, cmd),
         path,
         leaf: cmd,
-        inputSchema: buildLeafInputSchema(cmd),
-        ...(outputSchema === undefined ? {} : { outputSchema }),
+        inputSchema: input.schema,
+        inputWrapped: input.wrapped,
+        ...(output === undefined ? {} : { outputSchema: output.schema }),
+        outputWrapped: output?.wrapped ?? false,
       });
       return;
     }

package/examples/mcp-plugin/.mcp.json

@@ -1,6 +0,0 @@
-{
-  "mcp-plugin": {
-    "command": "node",
-    "args": ["${CLAUDE_PLUGIN_ROOT}/scripts/mcp.mjs", "mcp"]
-  }
-}

package/examples/mcp-plugin/bunfig.toml

@@ -1,3 +0,0 @@
-[install]
-# fetch package.json deps on first `bun src/index.ts` without manual `bun install`.
-auto = "fallback"

package/examples/mcp-plugin/mcp.json

@@ -1,8 +0,0 @@
-{
-  "mcpServers": {
-    "mcp-plugin": {
-      "command": "node",
-      "args": ["${CURSOR_PLUGIN_ROOT}/scripts/mcp.mjs", "mcp"]
-    }
-  }
-}