argsbarg 7.1.1 → 7.1.2

package/src/mcp/tools.test.ts

@@ -0,0 +1,158 @@
+/*
+Tests for mcp/tools module: MCP tool derivation, size reporting, and per-leaf MCP-only notes.
+*/
+
+import { describe, expect, test } from "bun:test";
+import { cliPresentationRoot } from "../builtins/presentation.ts";
+import { CliOptionKind } from "../core/types.ts";
+import { cliHelpRender } from "../help.ts";
+import { testProgram } from "../test/fixtures.ts";
+import { collectMcpTools, DEFAULT_MCP_SIZE_LIMITS, mcpSizeReport } 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.");
+  });
+});

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,
@@ -107,7 +108,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)}`;
   }
@@ -272,3 +279,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();