argsbarg 7.1.1 → 7.1.2

package/src/config/validate.ts

@@ -72,15 +72,360 @@ function formatInstancePath(instanceLocation: string): string {
   return instanceLocation;
 }
 
-function formatValidationErrors(errors: { instanceLocation: string; error: string }[]): string[] {
-  return errors.map(({ instanceLocation, error }) => {
-    const path = formatInstancePath(instanceLocation);
-    return `${path}: ${error}`;
+function decodeJsonPointerSegment(segment: string): string {
+  return segment.replace(/~1/g, "/").replace(/~0/g, "~");
+}
+
+/** cfworker keywords that only wrap a deeper, more specific failure — dropped when one survives underneath. */
+const WRAPPER_KEYWORDS = new Set([
+  "$ref",
+  "$recursiveRef",
+  "properties",
+  "items",
+  "prefixItems",
+  "additionalItems",
+  "allOf",
+  "anyOf",
+  "oneOf",
+]);
+
+/** Raw cfworker validation error (the subset of `OutputUnit` this module reads). */
+interface RawError {
+  instanceLocation: string;
+  keyword: string;
+  keywordLocation: string;
+  error: string;
+}
+
+/** Walks a `keywordLocation` JSON Pointer against `root`, following `$ref` segments through `resolveJsonPointer`. */
+function schemaAtPointer(root: JsonSchema, keywordLocation: string): JsonSchema | unknown[] | undefined {
+  if (!keywordLocation.startsWith("#")) {
+    return undefined;
+  }
+  const segments = keywordLocation
+    .slice(1)
+    .split("/")
+    .filter((segment) => segment.length > 0)
+    .map(decodeJsonPointerSegment);
+  let current: unknown = root;
+  for (const segment of segments) {
+    if (segment === "$ref") {
+      if (typeof current !== "object" || current === null || Array.isArray(current)) {
+        return undefined;
+      }
+      const ref = (current as JsonSchema).$ref;
+      if (typeof ref !== "string") {
+        return undefined;
+      }
+      current = resolveJsonPointer(root, ref);
+      continue;
+    }
+    if (typeof current !== "object" || current === null) {
+      return undefined;
+    }
+    current = (current as Record<string, unknown>)[segment];
+  }
+  return current as JsonSchema | unknown[] | undefined;
+}
+
+/** Walks an `instanceLocation` JSON Pointer against the validated payload. */
+function instanceAtPointer(data: unknown, instanceLocation: string): unknown {
+  if (!instanceLocation.startsWith("#")) {
+    return undefined;
+  }
+  const segments = instanceLocation
+    .slice(1)
+    .split("/")
+    .filter((segment) => segment.length > 0)
+    .map(decodeJsonPointerSegment);
+  let current: unknown = data;
+  for (const segment of segments) {
+    if (typeof current !== "object" || current === null) {
+      return undefined;
+    }
+    current = (current as Record<string, unknown>)[segment];
+  }
+  return current;
+}
+
+/** The parent JSON Pointer of `location` (its last `/segment` removed), or `undefined` at the root. */
+function parentPointer(location: string): string | undefined {
+  const idx = location.lastIndexOf("/");
+  if (idx < 0) {
+    return undefined;
+  }
+  return location.slice(0, idx) || "#";
+}
+
+/** A discriminator property common to every branch, with each branch's set of accepted string values. */
+interface UnionDiscriminator {
+  prop: string;
+  valuesByBranch: string[][];
+}
+
+/**
+ * Finds a property present in every branch as a string `const` or all-string `enum`, whose value sets are
+ * pairwise disjoint across branches. Prefers `kind`, then `type`, then the alphabetically first eligible name.
+ * Each branch is resolved through a bare `$ref` first — a schema built with a `definitions`/`$defs` map
+ * (e.g. ts-json-schema-generator output) typically writes `anyOf: [{ $ref: "#/definitions/A" }, …]` rather
+ * than inlining each branch, so without this every branch here would otherwise look property-less.
+ */
+function unionDiscriminator(branches: unknown[], root: JsonSchema): UnionDiscriminator | undefined {
+  const resolvedBranches = branches.map((b) => {
+    if (typeof b !== "object" || b === null || Array.isArray(b)) {
+      return b;
+    }
+    const ref = (b as JsonSchema).$ref;
+    if (typeof ref !== "string") {
+      return b;
+    }
+    return resolveJsonPointer(root, ref) ?? b;
   });
+  const objectBranches = resolvedBranches.filter(
+    (b): b is JsonSchema => typeof b === "object" && b !== null && !Array.isArray(b),
+  );
+  if (objectBranches.length === 0 || objectBranches.length !== resolvedBranches.length) {
+    return undefined;
+  }
+
+  const branchValuesFor = (prop: string): string[][] | undefined => {
+    const perBranch: string[][] = [];
+    for (const branch of objectBranches) {
+      const props = branch.properties;
+      const propSchema =
+        typeof props === "object" && props !== null && !Array.isArray(props)
+          ? (props as Record<string, JsonSchema>)[prop]
+          : undefined;
+      if (!propSchema || typeof propSchema !== "object") {
+        return undefined;
+      }
+      let values: string[] | undefined;
+      if (typeof propSchema.const === "string") {
+        values = [propSchema.const];
+      } else if (Array.isArray(propSchema.enum) && propSchema.enum.every((v) => typeof v === "string")) {
+        values = propSchema.enum as string[];
+      }
+      if (!values || values.length === 0) {
+        return undefined;
+      }
+      perBranch.push(values);
+    }
+    const seen = new Set<string>();
+    for (const values of perBranch) {
+      for (const v of values) {
+        if (seen.has(v)) return undefined;
+        seen.add(v);
+      }
+    }
+    return perBranch;
+  };
+
+  const candidateProps = new Set<string>();
+  for (const branch of objectBranches) {
+    const props = branch.properties;
+    if (typeof props === "object" && props !== null && !Array.isArray(props)) {
+      for (const key of Object.keys(props)) candidateProps.add(key);
+    }
+  }
+
+  const eligible: string[] = [];
+  for (const prop of candidateProps) {
+    if (branchValuesFor(prop)) eligible.push(prop);
+  }
+  if (eligible.length === 0) {
+    return undefined;
+  }
+  const prop = eligible.includes("kind") ? "kind" : eligible.includes("type") ? "type" : [...eligible].sort()[0]!;
+  return { prop, valuesByBranch: branchValuesFor(prop)! };
 }
 
-function decodeJsonPointerSegment(segment: string): string {
-  return segment.replace(/~1/g, "/").replace(/~0/g, "~");
+/** Sorted, comma-joined, unquoted list of values for error messages. */
+function joinSorted(values: Iterable<string>): string {
+  return [...new Set(values)].sort().join(", ");
+}
+
+/** Rewrites a single surviving cfworker error message into a terser, more actionable form. */
+function rewriteErrorMessage(err: RawError, root: JsonSchema): string {
+  const additionalPropsMatch = /^Property "(.+)" does not match additional properties schema\.$/.exec(err.error);
+  if (additionalPropsMatch) {
+    const name = additionalPropsMatch[1]!;
+    const parentLoc = parentPointer(err.keywordLocation);
+    const parentSchema = parentLoc ? schemaAtPointer(root, parentLoc) : undefined;
+    const props =
+      parentSchema && typeof parentSchema === "object" && !Array.isArray(parentSchema)
+        ? (parentSchema as JsonSchema).properties
+        : undefined;
+    const keys = props && typeof props === "object" && !Array.isArray(props) ? Object.keys(props as JsonSchema) : [];
+    const allowed = keys.sort().slice(0, 20).join(", ");
+    return `unknown property "${name}"${allowed ? ` (allowed: ${allowed})` : ""}`;
+  }
+
+  const requiredMatch = /^Instance does not have required property "(.+)"\.$/.exec(err.error);
+  if (requiredMatch) {
+    return `missing required property "${requiredMatch[1]}"`;
+  }
+
+  const enumMatch = /^Instance does not match any of (\[.*\])\.$/.exec(err.error);
+  if (enumMatch) {
+    try {
+      const values = JSON.parse(enumMatch[1]!) as unknown[];
+      return `must be one of: ${values.map((v) => String(v)).join(", ")}`;
+    } catch {
+      // fall through to the raw message
+    }
+  }
+
+  const typeMatch = /^Instance type "(.+)" is invalid\. Expected "(.+)"\.$/.exec(err.error);
+  if (typeMatch) {
+    return `must be ${typeMatch[2]} (got ${typeMatch[1]})`;
+  }
+
+  return err.error;
+}
+
+/** Maximum number of narrowed errors reported before collapsing the remainder into a count. */
+const MAX_NARROWED_ERRORS = 10;
+
+/**
+ * Post-processes raw cfworker errors: for each `anyOf`/`oneOf` failure with a discriminated union, keeps only
+ * the branch matching the instance's discriminator value (or reports one synthetic error naming what a valid
+ * discriminator looks like); drops wrapper keywords once a more specific error survives under them; drops the
+ * `additionalProperties`+`false` pair cfworker emits even for properties that are legitimately declared; then
+ * rewrites the remaining messages into terser, more actionable text.
+ */
+function narrowUnionErrors(errors: RawError[], root: JsonSchema, data: unknown): string[] {
+  const dropped = new Set<RawError>();
+  const synthetic: Array<{ instanceLocation: string; message: string }> = [];
+  // Locations of anyOf/oneOf errors resolved into a synthetic message rather than a kept branch — an ancestor
+  // wrapper (e.g. the `$ref` pointing at that anyOf, for the same instance) counts as "resolved deeper" too.
+  const syntheticReplacedLocations: Array<{ instanceLocation: string; keywordLocation: string }> = [];
+
+  // Stage 1: discriminated-union narrowing.
+  for (const err of errors) {
+    if (err.keyword !== "anyOf" && err.keyword !== "oneOf") continue;
+    const branches = schemaAtPointer(root, err.keywordLocation);
+    if (!Array.isArray(branches)) continue;
+    const discriminator = unionDiscriminator(branches, root);
+    if (!discriminator) continue;
+
+    // Array items reuse one schema, so keywordLocation repeats verbatim across indices — scope by
+    // instanceLocation too, or narrowing one item would wrongly swallow every other item's errors.
+    const under = errors.filter(
+      (e) =>
+        e !== err &&
+        e.keywordLocation.startsWith(`${err.keywordLocation}/`) &&
+        (e.instanceLocation === err.instanceLocation || e.instanceLocation.startsWith(`${err.instanceLocation}/`)),
+    );
+    const validValues = discriminator.valuesByBranch.flat();
+    const instance = instanceAtPointer(data, err.instanceLocation);
+
+    if (typeof instance !== "object" || instance === null || Array.isArray(instance)) {
+      dropped.add(err);
+      for (const e of under) dropped.add(e);
+      syntheticReplacedLocations.push({ instanceLocation: err.instanceLocation, keywordLocation: err.keywordLocation });
+      synthetic.push({
+        instanceLocation: err.instanceLocation,
+        message: `expected an object with "${discriminator.prop}" (one of: ${joinSorted(validValues)})`,
+      });
+      continue;
+    }
+
+    const propValue = (instance as Record<string, unknown>)[discriminator.prop];
+    if (propValue === undefined) {
+      dropped.add(err);
+      for (const e of under) dropped.add(e);
+      syntheticReplacedLocations.push({ instanceLocation: err.instanceLocation, keywordLocation: err.keywordLocation });
+      synthetic.push({
+        instanceLocation: err.instanceLocation,
+        message: `missing "${discriminator.prop}" (expected one of: ${joinSorted(validValues)})`,
+      });
+      continue;
+    }
+
+    const branchIndex = discriminator.valuesByBranch.findIndex(
+      (values) => typeof propValue === "string" && values.includes(propValue),
+    );
+    if (branchIndex < 0) {
+      dropped.add(err);
+      for (const e of under) dropped.add(e);
+      syntheticReplacedLocations.push({ instanceLocation: err.instanceLocation, keywordLocation: err.keywordLocation });
+      synthetic.push({
+        instanceLocation: `${err.instanceLocation}/${discriminator.prop}`,
+        message: `unknown ${discriminator.prop} "${String(propValue)}" (expected one of: ${joinSorted(validValues)})`,
+      });
+      continue;
+    }
+
+    const keepPrefix = `${err.keywordLocation}/${branchIndex}`;
+    dropped.add(err);
+    for (const e of under) {
+      if (e.keywordLocation === keepPrefix || e.keywordLocation.startsWith(`${keepPrefix}/`)) continue;
+      dropped.add(e);
+    }
+  }
+
+  // Stage 2: drop wrapper keywords once a more specific error survives under them, or once a descendant anyOf/oneOf
+  // was resolved into a synthetic message instead (which leaves no raw descendant error to detect otherwise).
+  const survivingAfterStage1 = errors.filter((e) => !dropped.has(e));
+  const nestsUnder = (candidateInstance: string, wrapperInstance: string) =>
+    candidateInstance === wrapperInstance || candidateInstance.startsWith(`${wrapperInstance}/`);
+  for (const err of survivingAfterStage1) {
+    if (!WRAPPER_KEYWORDS.has(err.keyword)) continue;
+    const prefix = `${err.keywordLocation}/`;
+    // Array items reuse one schema, so a wrapper's keywordLocation repeats across indices — scope by
+    // instanceLocation too, or one index's surviving error would mask another index's real problem.
+    const hasDeeper = survivingAfterStage1.some(
+      (other) =>
+        other !== err &&
+        !dropped.has(other) &&
+        other.keywordLocation.startsWith(prefix) &&
+        nestsUnder(other.instanceLocation, err.instanceLocation),
+    );
+    const hasSyntheticDeeper = syntheticReplacedLocations.some(
+      (s) => s.keywordLocation.startsWith(prefix) && nestsUnder(s.instanceLocation, err.instanceLocation),
+    );
+    if (hasDeeper || hasSyntheticDeeper) dropped.add(err);
+  }
+
+  // Stage 3: drop the additionalProperties+false pair cfworker emits for properties actually in `properties`.
+  const additionalPropsInstanceLocations = new Set(
+    errors.filter((e) => e.keyword === "additionalProperties").map((e) => e.instanceLocation),
+  );
+  for (const err of errors) {
+    if (dropped.has(err)) continue;
+    if (err.keyword === "additionalProperties") {
+      const match = /^Property "(.+)" does not match additional properties schema\.$/.exec(err.error);
+      const parentLoc = parentPointer(err.keywordLocation);
+      const parentSchema = parentLoc ? schemaAtPointer(root, parentLoc) : undefined;
+      const props =
+        match && parentSchema && typeof parentSchema === "object" && !Array.isArray(parentSchema)
+          ? (parentSchema as JsonSchema).properties
+          : undefined;
+      const declared =
+        match && props && typeof props === "object" && !Array.isArray(props)
+          ? Object.hasOwn(props as JsonSchema, match[1]!)
+          : false;
+      if (declared) dropped.add(err);
+      continue;
+    }
+    if (err.keyword === "false") {
+      const parent = parentPointer(err.instanceLocation);
+      if (parent !== undefined && additionalPropsInstanceLocations.has(parent)) {
+        dropped.add(err);
+      }
+    }
+  }
+
+  // Stage 4: rewrite surviving messages, merge in synthetic ones, cap the total.
+  const kept = errors
+    .filter((e) => !dropped.has(e))
+    .map((e) => `${formatInstancePath(e.instanceLocation)}: ${rewriteErrorMessage(e, root)}`);
+  const syntheticFormatted = synthetic.map((s) => `${formatInstancePath(s.instanceLocation)}: ${s.message}`);
+  const all = [...syntheticFormatted, ...kept];
+  if (all.length <= MAX_NARROWED_ERRORS) {
+    return all;
+  }
+  return [...all.slice(0, MAX_NARROWED_ERRORS), `…and ${all.length - MAX_NARROWED_ERRORS} more errors`];
 }
 
 /** Map a schema `$schema` URI to the @cfworker/json-schema draft (defaults to Draft-07). */
@@ -170,7 +515,7 @@ function validateInstance(
   if (result.valid) {
     return { valid: true, errors: [] };
   }
-  return { valid: false, errors: formatValidationErrors(result.errors) };
+  return { valid: false, errors: narrowUnionErrors(result.errors as RawError[], root, payload) };
 }
 
 function validateAgainstSchema(data: unknown, rootSchema: JsonSchema, partial: boolean): ValidateResult {

package/src/core/document-leaf.test.ts

@@ -180,6 +180,59 @@ describe("kind: document leaf", () => {
     expect(result.kind).toBe("error");
     expect(result.errorMsg).toContain("Document input must be a JSON or YAML object");
   });
+
+  /** Tests that a discriminated-union inputSchema surfaces only the matching branch's narrowed error. */
+  test("invoke surfaces a narrowed discriminated-union error end to end", async () => {
+    const stepSchema = {
+      $schema: "http://json-schema.org/draft-07/schema#",
+      type: "object",
+      properties: { steps: { type: "array", items: { $ref: "#/definitions/Step" } } },
+      required: ["steps"],
+      additionalProperties: false,
+      definitions: {
+        Step: {
+          anyOf: [
+            {
+              type: "object",
+              properties: { kind: { const: "alpha" }, title: { type: "string" } },
+              required: ["kind", "title"],
+              additionalProperties: false,
+            },
+            {
+              type: "object",
+              properties: { kind: { enum: ["beta", "bravo"] }, count: { type: "number" } },
+              required: ["kind"],
+              additionalProperties: false,
+            },
+            {
+              type: "object",
+              properties: { kind: { const: "gamma" }, flag: { type: "boolean" } },
+              required: ["kind"],
+              additionalProperties: false,
+            },
+          ],
+        },
+      },
+    } as const;
+    const program = {
+      key: "steptest",
+      version: "1.0.0",
+      description: "steps test",
+      commands: [
+        {
+          key: "run",
+          description: "run",
+          kind: "document",
+          inputSchema: stepSchema,
+          handler: (ctx) => ctx.inputsAs(),
+        },
+      ],
+    } satisfies CliProgram;
+    const cli = new Cli(program);
+    const result = await cli.invoke(["run", JSON.stringify({ steps: [{ kind: "alfa" }] })], { invocation: "cli" });
+    expect(result.kind).toBe("error");
+    expect(result.errorMsg).toBe('steps.0.kind: unknown kind "alfa" (expected one of: alpha, beta, bravo, gamma)');
+  });
 });
 
 /** Tests for parseDocumentText helper function. */

package/src/core/types.ts

@@ -187,6 +187,13 @@ export interface CliMcpBundleConfig {
 export interface CliMcpServerConfig {
   /** When `true`, enables the `mcp` built-in and MCP stdio server. */
   enabled: boolean;
+  /**
+   * Returned as `initialize.result.instructions`. Claude Code adds it to the system prompt of every
+   * session; Cursor writes it to `mcps/<server>/INSTRUCTIONS.md`. Both cases cost context whether or
+   * not the agent ends up using this server, so keep it to a one- or two-line pointer (e.g. when to
+   * reach for this tool, and to read the accompanying skill first) rather than usage documentation.
+   */
+  instructions?: string;
   /** MCP error response defaults. */
   errors?: CliMcpServerErrorsConfig;
   /** Observe-only hooks for JSON-RPC messages. */
@@ -212,6 +219,25 @@ export interface CliMcpServerConfig {
   resources?: CliMcpResource[];
   /** Optional MCP Bundle (`.mcpb`) metadata for `mcp bundle`. */
   bundle?: CliMcpBundleConfig;
+  /** Overrides the default startup size warnings (see {@link CliMcpSizeLimits}). */
+  sizeLimits?: CliMcpSizeLimits;
+}
+
+/**
+ * Size limits for one MCP tool's `description` and pretty-printed definition, and for `instructions`.
+ * Set a field to `false` to disable that check. Defaults come from two client behaviors observed in the
+ * wild, not from the MCP spec itself, so they may need retuning as those clients change:
+ * Claude Code truncates a tool's `description` past `descriptionChars`; Cursor syncs each tool's full
+ * definition (`{name, description, inputSchema, outputSchema}`, pretty-printed) to a file under
+ * `mcps/<server>/tools/<tool>.json` and its agent reads that file in chunks of at most `definitionBytes`
+ * bytes or `definitionLines` lines, whichever comes first — a tool at or beyond either limit is read
+ * incompletely on the first pass.
+ */
+export interface CliMcpSizeLimits {
+  definitionBytes?: number | false;
+  definitionLines?: number | false;
+  descriptionChars?: number | false;
+  instructionsChars?: number | false;
 }
 
 /** JSON Schema for structured error responses (OpenAPI + HTTP/MCP error bodies). */
@@ -334,6 +360,13 @@ export interface CliMcpToolConfig {
    * Default: auto-generated from command path and description.
    */
   description?: string;
+  /**
+   * Overrides the leaf's `notes` in the MCP description only — CLI help always shows `notes` unchanged.
+   * `false` omits notes from the MCP description entirely; a string replaces them. Omit to use `notes` as
+   * given. Useful when a note only makes sense with `--help` in front of it (a CLI-only workflow tip), or
+   * when the full CLI notes would push a definition past a size limit (see {@link CliMcpSizeLimits}).
+   */
+  notes?: string | false;
 }
 
 /**

package/src/core/validate.ts

@@ -162,6 +162,10 @@ export function cliValidateProgram(program: CliProgram): void {
     throw new CliSchemaValidationError("mcpServer requires enabled: true; omit mcpServer to disable MCP");
   }
 
+  if (program.mcpServer?.instructions !== undefined && program.mcpServer.instructions.trim().length === 0) {
+    throw new CliSchemaValidationError("mcpServer.instructions must not be empty; omit it instead");
+  }
+
   if (program.httpServer !== undefined && program.httpServer.enabled !== true) {
     throw new CliSchemaValidationError("httpServer requires enabled: true; omit httpServer to disable HTTP API");
   }

package/src/docs/docs.test.ts

@@ -280,6 +280,13 @@ test("generateMcpGuide includes schema URI and .agents install", () => {
   expect(guide).not.toContain("OpenAI Codex");
 });
 
+test("generateMcpGuide includes a Tool sizes table", () => {
+  const guide = generateMcpGuide(docsFixture(true));
+  expect(guide).toContain("## Tool sizes");
+  expect(guide).toContain("| Tool | Description (chars) | Definition (bytes) | Definition (lines) | Status |");
+  expect(guide).toMatch(/\| `run` \| \d+ \| \d+ \| \d+ \| ok \|/);
+});
+
 test("docs --save writes topic file", async () => {
   const result = await new Cli(docsFixture()).invoke(["docs", "readme", "--save"]);
   expect(result.exitCode).toBe(0);

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/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;