argsbarg 7.1.1 → 7.1.3

package/src/mcp/tools.ts

@@ -6,6 +6,7 @@ flat JSON tool arguments into argv for Cli.invoke.
 import { cliSchemaJson } from "../core/schema.ts";
 import {
   type CliLeaf,
+  type CliMcpSizeLimits,
   type CliNode,
   type CliOption,
   CliOptionKind,
@@ -48,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}". */
@@ -107,7 +149,13 @@ function resolveToolDescription(root: CliProgram, path: string[], leaf: CliLeaf)
   } else {
     desc = mcpToolDescription(path, root.key, leaf.description);
   }
-  const notes = (leaf.notes ?? "").trim();
+  // `mcpTool.notes` overrides what CLI help shows (leaf.notes) for the MCP description only:
+  // `false` omits notes entirely; a string replaces them; omitted falls through to leaf.notes.
+  const notesOverride = leaf.mcpTool?.notes;
+  if (notesOverride === false) {
+    return desc;
+  }
+  const notes = (typeof notesOverride === "string" ? notesOverride : (leaf.notes ?? "")).trim();
   if (notes.length > 0) {
     desc += `\n\n${cliResolveNotes(notes, root.key)}`;
   }
@@ -156,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;
     }
@@ -272,3 +324,89 @@ export function mcpToolCallToArgv(
 
   return argv;
 }
+
+/** Default {@link CliMcpSizeLimits}; see that type for what each limit approximates and why. */
+export const DEFAULT_MCP_SIZE_LIMITS: Required<CliMcpSizeLimits> = {
+  definitionBytes: 51_200,
+  definitionLines: 2_000,
+  descriptionChars: 2_048,
+  instructionsChars: 2_048,
+};
+
+/** Measured size of one MCP tool's description and pretty-printed definition. */
+export interface McpToolSize {
+  /** Pretty-printed `{name, description, inputSchema, outputSchema}`, in UTF-8 bytes. */
+  definitionBytes: number;
+  /** Line count of the same pretty-printed definition. */
+  definitionLines: number;
+  /** Character length of `description` alone. */
+  descriptionChars: number;
+  /** MCP tool name. */
+  name: string;
+}
+
+/** Per-tool sizes plus any warnings past {@link CliMcpSizeLimits} (defaults or `mcpServer.sizeLimits`). */
+export interface McpSizeReport {
+  /** Character length of `mcpServer.instructions`, or 0 when unset. */
+  instructionsChars: number;
+  /** One entry per MCP tool, in `tools/list` order. */
+  tools: McpToolSize[];
+  /** Human-readable warnings for anything past its limit; empty when everything fits. */
+  warnings: string[];
+}
+
+/** Formats a definition's pretty-printed JSON exactly as Cursor's synced tool file would show it. */
+function mcpToolDefinitionJson(tool: McpToolDef): string {
+  return JSON.stringify(
+    {
+      name: tool.name,
+      description: tool.description,
+      inputSchema: tool.inputSchema,
+      ...(tool.outputSchema === undefined ? {} : { outputSchema: tool.outputSchema }),
+    },
+    null,
+    2,
+  );
+}
+
+/** Measures every MCP tool's description and definition size against {@link CliMcpSizeLimits}. */
+export function mcpSizeReport(root: CliProgram): McpSizeReport {
+  const limits = { ...DEFAULT_MCP_SIZE_LIMITS, ...root.mcpServer?.sizeLimits };
+  const warnings: string[] = [];
+
+  const tools = collectMcpTools(root).map((tool): McpToolSize => {
+    const definitionJson = mcpToolDefinitionJson(tool);
+    const definitionBytes = Buffer.byteLength(definitionJson, "utf8");
+    const definitionLines = definitionJson.split("\n").length;
+    const descriptionChars = tool.description.length;
+
+    if (limits.descriptionChars !== false && descriptionChars > limits.descriptionChars) {
+      warnings.push(
+        `MCP tool "${tool.name}" description is ${descriptionChars.toLocaleString()} chars ` +
+          `(limit ${limits.descriptionChars.toLocaleString()}; Claude Code truncates longer descriptions)`,
+      );
+    }
+    const overBytes = limits.definitionBytes !== false && definitionBytes > limits.definitionBytes;
+    const overLines = limits.definitionLines !== false && definitionLines > limits.definitionLines;
+    if (overBytes || overLines) {
+      const byteLimit = limits.definitionBytes === false ? "∞" : limits.definitionBytes.toLocaleString();
+      const lineLimit = limits.definitionLines === false ? "∞" : limits.definitionLines.toLocaleString();
+      warnings.push(
+        `MCP tool "${tool.name}" definition is ${definitionBytes.toLocaleString()} bytes / ` +
+          `${definitionLines.toLocaleString()} lines pretty-printed (limit ${byteLimit} bytes / ${lineLimit} lines; ` +
+          `Cursor reads tool definitions in chunks of at most that size)`,
+      );
+    }
+
+    return { definitionBytes, definitionLines, descriptionChars, name: tool.name };
+  });
+
+  const instructionsChars = (root.mcpServer?.instructions ?? "").length;
+  if (limits.instructionsChars !== false && instructionsChars > limits.instructionsChars) {
+    warnings.push(
+      `MCP instructions are ${instructionsChars.toLocaleString()} chars (limit ${limits.instructionsChars.toLocaleString()})`,
+    );
+  }
+
+  return { instructionsChars, tools, warnings };
+}

package/src/runtime/cli.ts

@@ -33,7 +33,8 @@ import { buildInvokeHookContext, classifyFailureKind, runErrorPipeline, runHook
 import { httpServeHttp } from "../http/server.ts";
 import { LogEmitter } from "../log/emitter.ts";
 import { bootstrapMcpEnv } from "../mcp/env.ts";
-import { mcpServeStdioLoop } from "../mcp/server.ts";
+import { MCP_PROTOCOL_VERSIONS, mcpServeStdioLoop } from "../mcp/server.ts";
+import { mcpSizeReport } from "../mcp/tools.ts";
 import { createServerRuntime, type ServerHandleContext } from "../server/context.ts";
 import { resolveHttpServeConfig, resolveMcpServeConfig, type ServeOverrides } from "../server/overrides.ts";
 import {
@@ -414,6 +415,7 @@ export class Cli {
         emitter,
         mcp: resolved,
         mcpHooks: this.program.mcpServer?.hooks,
+        mcpProtocolVersion: MCP_PROTOCOL_VERSIONS[0],
       };
       bootstrapAppConfig(this.program, { validateFile: "soft", runtime, emitter });
       const shutdown = () => {
@@ -422,6 +424,9 @@ export class Cli {
       };
       process.once("SIGINT", shutdown);
       process.once("SIGTERM", shutdown);
+      for (const message of mcpSizeReport(this.program).warnings) {
+        emitter.emit({ level: "warn", message, action: "mcp.size" });
+      }
       emitter.emitLifecycle(`${this.program.key} ${this.program.version} — MCP ready (stdio)`, "mcp.server.ready");
       await mcpServeStdioLoop(this);
       process.exit(0);

package/src/server/context.ts

@@ -14,6 +14,12 @@ export interface ServerHandleContext {
   mcp?: ResolvedMcpServeConfig;
   httpHooks?: CliHttpWireHooks;
   mcpHooks?: CliMcpWireHooks;
+  /**
+   * The MCP protocol version negotiated with `initialize`, or the newest supported version before
+   * `initialize` has been handled. Later requests (`tools/list`, `tools/call`) gate version-specific
+   * response fields (e.g. `outputSchema`, `structuredContent`) on this.
+   */
+  mcpProtocolVersion?: string;
 }
 
 /** Creates a fresh {@link ServerRuntime} for HTTP or MCP. */

package/src/test/integration/mcp.test.ts

@@ -353,6 +353,79 @@ test("MCP initialize returns tools and resources capabilities", async () => {
   expect(res.result.capabilities.resources).toBeDefined();
 });
 
+test("MCP initialize echoes a supported protocol version", async () => {
+  for (const version of ["2024-11-05", "2025-06-18"]) {
+    const responses = await mcpRequest([
+      { jsonrpc: "2.0", id: 1, method: "initialize", params: { protocolVersion: version } },
+    ]);
+    const res = responses.get(1) as { result: { protocolVersion: string } };
+    expect(res.result.protocolVersion).toBe(version);
+  }
+});
+
+test("MCP initialize answers unsupported or missing versions with the newest", async () => {
+  for (const params of [{ protocolVersion: "2099-01-01" }, {}]) {
+    const responses = await mcpRequest([{ jsonrpc: "2.0", id: 1, method: "initialize", params }]);
+    const res = responses.get(1) as { result: { protocolVersion: string } };
+    expect(res.result.protocolVersion).toBe("2025-06-18");
+  }
+});
+
+test("2024-11-05 sessions omit outputSchema and structuredContent", async () => {
+  const readme = join(import.meta.dir, "..", "..", "..", "README.md");
+  const responses = await mcpRequest([
+    { jsonrpc: "2.0", id: 1, method: "initialize", params: { protocolVersion: "2024-11-05" } },
+    { jsonrpc: "2.0", id: 2, method: "tools/list", params: {} },
+    {
+      jsonrpc: "2.0",
+      id: 3,
+      method: "tools/call",
+      params: { name: "stat_owner_lookup", arguments: { path: readme, "user-name": "test" } },
+    },
+  ]);
+  const listRes = responses.get(2) as { result: { tools: { name: string; outputSchema?: unknown }[] } };
+  const lookup = listRes.result.tools.find((t) => t.name === "stat_owner_lookup");
+  expect(lookup).toBeDefined();
+  expect(lookup?.outputSchema).toBeUndefined();
+
+  const callRes = responses.get(3) as { result: { structuredContent?: unknown; isError: boolean } };
+  expect(callRes.result.isError).toBe(false);
+  expect(callRes.result.structuredContent).toBeUndefined();
+});
+
+test("MCP initialize includes configured instructions", async () => {
+  const responses = await mcpRequest([{ jsonrpc: "2.0", id: 1, method: "initialize", params: {} }], {
+    script: "src/test/mcp-integration-fixture.ts",
+  });
+  const res = responses.get(1) as { result: { instructions?: string } };
+  expect(res.result.instructions).toBe("Read the fixture skill.");
+});
+
+test("MCP startup warns about oversized tools on stderr", async () => {
+  const proc = Bun.spawn(["bun", "run", "src/test/mcp-size-fixture.ts", "mcp"], {
+    stdin: "pipe",
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+  proc.stdin.write(`${JSON.stringify({ jsonrpc: "2.0", id: 1, method: "initialize", params: {} })}\n`);
+  proc.stdin.end();
+  const timeout = setTimeout(() => proc.kill(), 10_000);
+  const [stdout, stderr] = await Promise.all([new Response(proc.stdout).text(), new Response(proc.stderr).text()]);
+  await proc.exited;
+  clearTimeout(timeout);
+
+  expect(stderr).toContain("description is 3,");
+
+  const lines = stdout
+    .split("\n")
+    .map((l) => l.trim())
+    .filter(Boolean);
+  expect(lines.length).toBeGreaterThan(0);
+  for (const line of lines) {
+    expect(() => JSON.parse(line)).not.toThrow();
+  }
+});
+
 test("MCP tools/list includes stat_owner_lookup", async () => {
   const responses = await mcpRequest([{ jsonrpc: "2.0", id: 2, method: "tools/list", params: {} }]);
   const res = responses.get(2) as {

package/src/test/mcp-integration-fixture.ts

@@ -68,6 +68,7 @@ const program = {
   key: "mcp-test",
   mcpServer: {
     enabled: true,
+    instructions: "Read the fixture skill.",
     resources: [
       {
         uri: "test://hello",

package/src/test/mcp-size-fixture.ts

@@ -0,0 +1,31 @@
+#!/usr/bin/env bun
+/*
+MCP size-warning integration test fixture (not a public example). One leaf with oversized notes,
+triggering the "description" startup size warning on stderr.
+*/
+
+import { Cli, type CliProgram } from "../index.ts";
+
+const program = {
+  commands: [
+    {
+      key: "run",
+      description: "Run it.",
+      notes: "x".repeat(3_000),
+      handler: (ctx) => {
+        if (ctx.invocation === "cli") {
+          console.log("ran");
+          return;
+        }
+        return "ran";
+      },
+    },
+  ],
+  description: "MCP size-warning test fixture.",
+  key: "mcp-size-test",
+  mcpServer: { enabled: true },
+  version: "0.0.0-test",
+} satisfies CliProgram;
+
+const cli = new Cli(program);
+await cli.run();

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"]
-    }
-  }
-}