argsbarg 7.1.2 → 7.1.3

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/mcp.json

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