argsbarg 7.1.1 → 7.1.2

package/CHANGELOG.md

@@ -7,6 +7,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [7.1.2] - 2026-09-25
+
+### Added
+
+- `mcpServer.instructions` — an optional string returned as `initialize.result.instructions`. Claude Code adds it to the system prompt of every session; Cursor writes it to `mcps/<server>/INSTRUCTIONS.md`.
+- MCP protocol version negotiation: `initialize` now echoes a client's `2025-06-18` or `2024-11-05` `protocolVersion`, and answers `2025-06-18` (the newest) when the request omits it or asks for an unsupported version. Previously the server always claimed `2024-11-05` regardless of what the client sent or what fields it actually returned. `tools/list`'s `outputSchema` and `tools/call`'s `structuredContent` — both defined starting in `2025-06-18` — are now only sent for sessions that negotiated that version or later; a `2024-11-05` session no longer receives fields from a spec revision it never agreed to.
+- `mcpSizeReport(root)` and `mcpServer.sizeLimits` — measures every MCP tool's `description` length and pretty-printed definition (bytes and lines) against configurable limits approximating two real client behaviors (Claude Code truncates long tool descriptions; Cursor reads each tool's synced definition file in bounded chunks), and returns warnings for anything over. `serveMcp` runs this at startup and writes warnings to stderr before the "MCP ready" line; `docs mcp` now includes a `## Tool sizes` table. Set any limit to `false` to disable that check.
+- `mcpTool.notes` (`string | false`) — overrides a leaf's `notes` in the MCP tool description only; CLI `--help` continues to show the leaf's own `notes` unchanged. Useful for a note that only makes sense with `--help` in front of it, or to keep a tool's definition under a size limit.
+
+### Changed
+
+- Discriminated `anyOf`/`oneOf` unions (every branch has a `properties` key with a string `const` or all-string `enum`, and the value sets are disjoint) now report only the branch matching the instance's discriminator value, instead of every branch's unrelated errors at once. A missing, non-string, or unmapped discriminator value collapses to one synthetic message naming the valid choices. Non-discriminated unions are unaffected. Along the way, two cfworker `@cfworker/json-schema` quirks are also cleaned up for every validated schema (not just discriminated unions): a spurious `additionalProperties` + `"False boolean schema."` pair it emits even for a property that's genuinely declared in `properties`, and dropping now-redundant wrapper errors (`$ref`, `properties`, `items`, `anyOf`, `oneOf`, …) once a more specific error survives underneath them. Discriminator detection also resolves each branch through `$ref` before inspecting its `properties` — schema generators such as `ts-json-schema-generator` write every `anyOf` branch as a bare `{ $ref }` into `definitions` rather than inlining it, which previously made every branch look property-less and silently fell back to the noisy full-error listing.
+
 ## [7.1.1] - 2026-09-25
 
 ### Added
@@ -1048,7 +1061,8 @@ const cli = { ... } satisfies CliProgram;  // or : CliProgram
 - Migrate schemas: rename every `children` property to **`commands`**; move positional definitions to **`CliPositional`** objects on `positionals` and strip `positional` / `argMin` / `argMax` from flag definitions under `options` (flags only carry `name`, `description`, `kind`, and optional `shortName`).
 - Imports: use `CliPositional` where needed; replace `CliOptionDef` with `CliOption` or `CliPositional` as appropriate.
 
-[Unreleased]: https://github.com/bdombro/bun-argsbarg/compare/v7.1.1...HEAD
+[Unreleased]: https://github.com/bdombro/bun-argsbarg/compare/v7.1.2...HEAD
+[7.1.2]: https://github.com/bdombro/bun-argsbarg/releases/tag/v7.1.2
 [7.1.1]: https://github.com/bdombro/bun-argsbarg/releases/tag/v7.1.1
 [7.1.0]: https://github.com/bdombro/bun-argsbarg/releases/tag/v7.1.0
 [7.0.11]: https://github.com/bdombro/bun-argsbarg/releases/tag/v7.0.11

package/docs/mcp.md

@@ -96,9 +96,11 @@ Set `mcpServer` on the **program root only** (the `CliProgram` passed to `new Cl
 | Field | Default | Purpose |
 | --- | --- | --- |
 | `enabled` | *(required)* | Must be `true` when `mcpServer` is set |
+| `instructions` | *(none)* | Returned as `initialize.result.instructions` for every negotiated protocol version. 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 (when to reach for this tool, and to read the accompanying skill first), not usage docs. Must be non-empty when set. |
 | `schemaResourceUri` | `<sanitized root key>://schema` | URI for the built-in schema resource |
 | `shellEnv` | on (opt-out with `false`) | Capture login-shell `env` at startup (`true` uses `$SHELL`, or pass a shell path) |
 | `resources` | `[]` | Custom `CliMcpResource` entries (additive; schema resource is always included) |
+| `sizeLimits` | see [Tool sizes](#tool-sizes) | Overrides the default startup size warnings for tool descriptions, definitions, and `instructions` |
 
 MCP `serverInfo.name` and the default schema URI use the sanitized program `key` (non-alphanumeric characters become `_`). Program `version` comes from `CliProgram.version` (also used by the `version` built-in).
 
@@ -158,12 +160,14 @@ Omitted or `enabled: true` exposes the command (default). `mcpTool` is only vali
 mcpTool: {
   enabled: true,
   description: "Custom tools/list text (overrides auto-generated path + help).",
+  notes: false, // omit this leaf's `notes` from the MCP description; a string replaces them
 }
 ```
 
 Set **`outputSchema` on the leaf** (not under `mcpTool`) — see [cli-program.md — Structured stdout](cli-program.md#structured-stdout).
 
 - **`description`** — when set, replaces the auto-generated `path — help` description entirely.
+- **`notes`** — overrides the leaf's `notes` in the MCP description only; CLI `--help` always shows the leaf's own `notes` unchanged. `false` omits notes from the MCP description entirely; a string replaces them; omit `notes` to use the leaf's `notes` as given. Useful when a note only makes sense with `--help` in front of it, or to keep a tool's definition under a size limit (see [Tool sizes](#tool-sizes)).
 
 ### Tool arguments
 
@@ -194,12 +198,37 @@ On success (`isError: false`):
 
 - **stdout** — first `content` text block with the handler’s captured stdout (raw, unchanged).
 - **stderr** — when non-empty, a second `content` text block with trimmed stderr (no prefix). The block’s position signals stderr; hosts may label it themselves.
-- **structuredContent** — when trimmed stdout is valid JSON, the parsed value is also returned per the [MCP tools spec](https://modelcontextprotocol.io/specification/draft/server/tools). Objects and arrays from flags like `--json` are the common case. JSON **primitives** (`true`, `42`, `"hello"`) are parsed too — a handler that prints the literal string `true` as human text would get `structuredContent: true`. Prefer objects for machine-readable output.
+- **structuredContent** — when trimmed stdout is valid JSON, the parsed value is also returned per the [MCP tools spec](https://modelcontextprotocol.io/specification/draft/server/tools) — only for `2025-06-18` sessions (see [Protocol](#protocol)); `2024-11-05` sessions get `content` only. Objects and arrays from flags like `--json` are the common case. JSON **primitives** (`true`, `42`, `"hello"`) are parsed too — a handler that prints the literal string `true` as human text would get `structuredContent: true`. Prefer objects for machine-readable output.
 
 On failure (parse error, validation error, non-zero exit, thrown error), the **full** error message is returned as text content with `isError: true` (ANSI stripped, newlines preserved). HTTP JSON `{ "error": "…" }` uses the same full text. Do not collapse headless errors to the first line.
 
 Help and `docs cli-schema` are not available through tool calls; use the schema resource or run the CLI directly for those.
 
+## Tool sizes
+
+Some hosts have their own limits on how much of a tool's `description` or full definition they'll read, independent of anything the MCP spec itself defines. `mcpSizeReport(root)` (exported from `argsbarg`) measures every tool's `description` length and pretty-printed `{name, description, inputSchema, outputSchema}` definition (bytes and lines) against configurable limits, and returns human-readable warnings for anything over. `serveMcp` runs this at startup and writes any warnings to stderr (`action: "mcp.size"`) before the "MCP ready" line; `docs mcp` includes a `## Tool sizes` table with a per-tool `ok` / `over: …` status.
+
+Default limits — observed client behaviors, not MCP spec requirements, so they may need retuning as those clients change:
+
+| Limit | Default | Approximates |
+| --- | --- | --- |
+| `descriptionChars` | `2,048` | Claude Code truncates a tool's `description` past this |
+| `definitionBytes` | `51,200` | Cursor syncs each tool's full definition to a file and reads it in chunks of at most this many bytes |
+| `definitionLines` | `2,000` | Same file, read in chunks of at most this many lines (whichever limit hits first) |
+| `instructionsChars` | `2,048` | No specific client behavior modeled yet; a general "keep it short" budget |
+
+Override with `mcpServer.sizeLimits`; set any field to `false` to disable that check entirely:
+
+```typescript
+mcpServer: {
+  enabled: true,
+  sizeLimits: {
+    definitionBytes: 100_000, // this app's tools are legitimately large
+    instructionsChars: false, // don't warn on instructions length
+  },
+}
+```
+
 ## Schema and custom resources
 
 The built-in schema resource (default URI `<sanitized-key>://schema`, e.g. `nested.ts` → `nested_ts://schema`) exposes your full CLI tree as JSON — the same output as `myapp docs cli-schema`. Override with `schemaResourceUri` if needed.
@@ -312,16 +341,16 @@ mcpServer: {
 
 - **Transport:** stdio, newline-delimited JSON (NDJSON).
 - **JSON-RPC:** version `2.0`.
-- **MCP protocol version:** `2024-11-05` (reported in `initialize`).
+- **MCP protocol version negotiation:** the server supports `2025-06-18` and `2024-11-05`. `initialize` echoes `params.protocolVersion` when it's one of those; otherwise (unsupported, or omitted) it answers `2025-06-18`, the newest. The negotiated version is fixed for the lifetime of the stdio session (one `initialize` per connection) and gates `outputSchema` (`tools/list`) and `structuredContent` (`tools/call`): both are present only for `2025-06-18` sessions, since those fields are defined starting there. `2025-03-26` is not supported (it mandates JSON-RPC batching, which this server doesn't implement).
 
 ### Supported methods
 
 | Method | Description |
 | --- | --- |
-| `initialize` | Returns capabilities (`tools`, `resources`) and `serverInfo`. |
+| `initialize` | Negotiates protocol version, returns capabilities (`tools`, `resources`), `serverInfo`, and optional `instructions`. |
 | `notifications/initialized` | Acknowledged; no response (notification). |
 | `ping` | Returns `{}`. |
-| `tools/list` | Lists all tools with `name`, `description`, `inputSchema`, and optional `outputSchema`. |
+| `tools/list` | Lists all tools with `name`, `description`, `inputSchema`, and `outputSchema` (`2025-06-18` sessions only). |
 | `tools/call` | Runs a leaf handler; params: `name`, `arguments` (object). |
 | `resources/list` | Lists schema + custom resources. |
 | `resources/read` | Returns resource body; params: `uri`. |

package/index.d.ts

@@ -342,6 +342,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. */
@@ -367,6 +374,24 @@ 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). */
 export type CliJsonSchema = Record<string, unknown>;
@@ -481,6 +506,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;
 }
 /** Context passed to {@link CliAppConfigEntry.resolve} for one config key. */
 export interface CliAppConfigResolveContext {
@@ -950,6 +982,30 @@ export interface PackMcpBundleOpts {
  * Requires the compiled binary to exist.
  */
 export declare function packMcpBundle(program: CliProgram, opts?: PackMcpBundleOpts): string;
+/** Default {@link CliMcpSizeLimits}; see that type for what each limit approximates and why. */
+export declare const DEFAULT_MCP_SIZE_LIMITS: Required<CliMcpSizeLimits>;
+/** 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[];
+}
+/** Measures every MCP tool's description and definition size against {@link CliMcpSizeLimits}. */
+export declare function mcpSizeReport(root: CliProgram): McpSizeReport;
 /**
  * Resolves the user home directory without depending on `$HOME`.
  * This is helpful for when homebrew post-install hooks run with a temporary `$HOME`.
@@ -1056,6 +1112,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;
 }
 /** Platform builtins derived from program config and runtime. */
 export interface CliCapabilities {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "argsbarg",
-  "version": "7.1.1",
+  "version": "7.1.2",
   "main": "./src/index.ts",
   "module": "./src/index.ts",
   "dependencies": {

package/src/config/validate.test.ts

@@ -51,6 +51,163 @@ describe("config/validate", () => {
     expect(result.valid).toBe(false);
   });
 
+  describe("discriminated unions", () => {
+    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,
+            },
+          ],
+        },
+      },
+    };
+
+    test("valid mix of branches passes", () => {
+      const result = validateConfigDocument(
+        {
+          steps: [
+            { kind: "alpha", title: "x" },
+            { kind: "beta", count: 3 },
+          ],
+        },
+        stepSchema,
+      );
+      expect(result.valid).toBe(true);
+      expect(result.errors).toEqual([]);
+    });
+
+    test("unknown property in the matched branch reports only that branch", () => {
+      const result = validateConfigDocument({ steps: [{ kind: "alpha", titel: "x" }] }, stepSchema);
+      expect(result.errors).toEqual([
+        'steps.0: missing required property "title"',
+        'steps.0: unknown property "titel" (allowed: kind, title)',
+      ]);
+    });
+
+    test("unmapped discriminator value reports one synthetic error", () => {
+      const result = validateConfigDocument({ steps: [{ kind: "alfa" }] }, stepSchema);
+      expect(result.errors).toEqual(['steps.0.kind: unknown kind "alfa" (expected one of: alpha, beta, bravo, gamma)']);
+    });
+
+    test("missing discriminator reports one synthetic error", () => {
+      const result = validateConfigDocument({ steps: [{ title: "x" }] }, stepSchema);
+      expect(result.errors).toEqual(['steps.0: missing "kind" (expected one of: alpha, beta, bravo, gamma)']);
+    });
+
+    test("non-object instance reports one synthetic error", () => {
+      const result = validateConfigDocument({ steps: ["alpha"] }, stepSchema);
+      expect(result.errors).toEqual(['steps.0: expected an object with "kind" (one of: alpha, beta, bravo, gamma)']);
+    });
+
+    test("type mismatch in the matched branch reports only that field", () => {
+      const result = validateConfigDocument({ steps: [{ kind: "beta", count: "x" }] }, stepSchema);
+      expect(result.errors).toEqual(["steps.0.count: must be number (got string)"]);
+    });
+
+    test("a non-discriminated union still reports errors from every branch", () => {
+      const nonDiscriminatedSchema = {
+        type: "object",
+        properties: {
+          x: {
+            anyOf: [
+              { type: "object", properties: { a: { type: "string" } }, required: ["a"], additionalProperties: false },
+              { type: "object", properties: { b: { type: "number" } }, required: ["b"], additionalProperties: false },
+            ],
+          },
+        },
+        additionalProperties: false,
+      };
+      const result = validateConfigDocument({ x: {} }, nonDiscriminatedSchema);
+      expect(result.errors).toEqual(['x: missing required property "a"', 'x: missing required property "b"']);
+    });
+
+    test("collects one error per bad step, in order, without cross-contamination between array indices", () => {
+      const result = validateConfigDocument({ steps: [{ kind: "alfa" }, { kind: "beta", count: "x" }] }, stepSchema);
+      expect(result.errors).toEqual([
+        'steps.0.kind: unknown kind "alfa" (expected one of: alpha, beta, bravo, gamma)',
+        "steps.1.count: must be number (got string)",
+      ]);
+    });
+
+    test("resolves discriminators through $ref'd branches (ts-json-schema-generator output shape)", () => {
+      // ts-json-schema-generator (and similar tools) write each anyOf branch as a bare `{ $ref }` pointing
+      // into `definitions`, rather than inlining the branch schema. This is the shape gdocsmith's real
+      // `run` tool schema uses for its 27 step kinds, and it silently defeated discriminator detection
+      // (every branch looked property-less) until unionDiscriminator started resolving branch refs.
+      const refBranchSchema = {
+        $schema: "http://json-schema.org/draft-07/schema#",
+        type: "object",
+        properties: {
+          steps: { type: "array", items: { anyOf: [{ $ref: "#/definitions/A" }, { $ref: "#/definitions/B" }] } },
+        },
+        required: ["steps"],
+        additionalProperties: false,
+        definitions: {
+          A: {
+            type: "object",
+            properties: { kind: { const: "alpha" }, title: { type: "string" } },
+            required: ["kind", "title"],
+            additionalProperties: false,
+          },
+          B: {
+            type: "object",
+            properties: { kind: { const: "beta" }, count: { type: "number" } },
+            required: ["kind"],
+            additionalProperties: false,
+          },
+        },
+      };
+      const result = validateConfigDocument({ steps: [{ kind: "alfa" }] }, refBranchSchema);
+      expect(result.errors).toEqual(['steps.0.kind: unknown kind "alfa" (expected one of: alpha, beta)']);
+    });
+
+    test("caps at 10 errors plus a count of the remainder", () => {
+      const manySchema = {
+        type: "object",
+        properties: {
+          steps: {
+            type: "array",
+            items: {
+              type: "object",
+              properties: { kind: { enum: ["a"] } },
+              required: ["kind"],
+              additionalProperties: false,
+            },
+          },
+        },
+        additionalProperties: false,
+      };
+      const result = validateConfigDocument({ steps: Array.from({ length: 12 }, () => ({})) }, manySchema);
+      expect(result.errors).toHaveLength(11);
+      expect(result.errors.slice(0, 10)).toEqual(
+        Array.from({ length: 10 }, (_, i) => `steps.${i}: missing required property "kind"`),
+      );
+      expect(result.errors[10]).toBe("…and 2 more errors");
+    });
+  });
+
   test("parseConfigSetValue coerces number and boolean", () => {
     expect(parseConfigSetValue("5", { type: "integer" }, rootSchema, false)).toBe(5);
     expect(parseConfigSetValue("true", { type: "boolean" }, rootSchema, false)).toBe(true);