argsbarg 7.1.1 → 7.1.3

package/examples/full-example-json/src/commands/shape-area/command.ts

@@ -0,0 +1,31 @@
+/*
+Shape-area leaf — discriminated-union JSON body demo (MCP wraps non-object roots as `{ input }`).
+*/
+
+import type { CliLeaf, CliProgram } from "argsbarg";
+import { ShapeAreaInputSchema } from "./__generated__";
+import type { ShapeAreaInput } from "./types.ts";
+
+export const shapeAreaCommand = {
+  key: "shape-area",
+  description: "Compute the area of a circle or rectangle (union-input JSON leaf demo).",
+  kind: "json",
+  inputSchema: ShapeAreaInputSchema,
+  handler: (ctx) => {
+    const shape = ctx.inputsAs<ShapeAreaInput>();
+    const area = shape.kind === "circle" ? Math.PI * shape.radius ** 2 : shape.width * shape.height;
+    if (ctx.invocation === "cli") {
+      console.log(area);
+      return;
+    }
+    return { area };
+  },
+} satisfies CliLeaf;
+
+/** Program stub for colocated tests. */
+export function shapeAreaTestProgram(base: CliProgram): CliProgram {
+  return {
+    ...base,
+    commands: [shapeAreaCommand],
+  };
+}

package/examples/full-example-json/src/commands/shape-area/types.ts

@@ -0,0 +1,28 @@
+/*
+Input types for the shape-area demo leaf (discriminated-union input).
+The union root is not `type: "object"`, so MCP clients see it wrapped as `{ input: ... }`.
+*/
+
+/** A circle, measured by radius. */
+export interface Circle {
+  /** Shape discriminator. */
+  kind: "circle";
+  /** Circle radius. */
+  radius: number;
+}
+
+/** A rectangle, measured by width and height. */
+export interface Rect {
+  /** Shape discriminator. */
+  kind: "rect";
+  /** Rectangle width. */
+  width: number;
+  /** Rectangle height. */
+  height: number;
+}
+
+/**
+ * Shape to measure: a circle or a rectangle.
+ * @sg
+ */
+export type ShapeAreaInput = Circle | Rect;

package/examples/full-example-json/src/program.ts

@@ -7,12 +7,13 @@ import readmeText from "../README.md" with { type: "text" };
 import { createIdentity } from "../scripts/create-identity.ts";
 import { echoCommand } from "./commands/echo/command.ts";
 import { renderJsonCommand } from "./commands/render-json/command.ts";
+import { shapeAreaCommand } from "./commands/shape-area/command.ts";
 import { statusCommand } from "./commands/status/command.ts";
 import { workspacesCommand } from "./commands/workspaces/command.ts";
 import { AppDb } from "./db";
 
 export const program = {
-  commands: [echoCommand, renderJsonCommand, statusCommand, workspacesCommand],
+  commands: [echoCommand, renderJsonCommand, shapeAreaCommand, statusCommand, workspacesCommand],
   description: createIdentity.desc,
   docs: {
     topics: {

package/examples/mcp-plugin/.claude-plugin/plugin.json

@@ -6,5 +6,11 @@
     "name": "Brian Dombrowski"
   },
   "homepage": "https://github.com/bdombro/bun-argsbarg",
-  "repository": "https://github.com/bdombro/bun-argsbarg"
+  "repository": "https://github.com/bdombro/bun-argsbarg",
+  "mcpServers": {
+    "mcp-plugin": {
+      "command": "bun",
+      "args": ["--cwd", "${CLAUDE_PLUGIN_ROOT}", "start"]
+    }
+  }
 }

package/examples/mcp-plugin/.cursor-plugin/plugin.json

@@ -7,5 +7,11 @@
     "name": "Brian Dombrowski"
   },
   "homepage": "https://github.com/bdombro/bun-argsbarg",
-  "repository": "https://github.com/bdombro/bun-argsbarg"
+  "repository": "https://github.com/bdombro/bun-argsbarg",
+  "mcpServers": {
+    "mcp-plugin": {
+      "command": "bun",
+      "args": ["--cwd", "${CURSOR_PLUGIN_ROOT}", "start"]
+    }
+  }
 }

package/examples/mcp-plugin/AGENTS.md

@@ -76,11 +76,24 @@ Avoid needless extraction: keep single-use helpers in the calling file by defaul
 
 ## Tooling
 
-- Bun only (`bun`, `bunx`, `bun test`). No Node/npm/pnpm.
+- Use Bun for development and the default plugin runtime (`bun`, `bun x`, `bun test`).
+- `bun start` installs locked dependencies, generates schemas, then starts MCP. Keep setup output on stderr; stdout is the MCP protocol.
+- Ship source, `bun.lock`, and inline plugin manifests. Do not ship `node_modules`, generated schemas, or a compiled bundle.
+- Node distribution is an explicit alternative documented in `docs/node-distro.md`; do not change the default runtime implicitly.
+
+## Testing Boundaries
+
+- Use the cheapest test level that establishes the behavior. Reuse existing tests and helpers.
+- Unit/offline: deterministic parsing, validation, state changes, and request planning. Keep these tests independent of live services and paid agents.
+- Integration: contracts unit tests cannot establish, such as clean plugin installation, MCP startup/transport, or actual external persistence. Do not duplicate unit coverage with live calls.
+- Agent E2E: safe user-task completion and agent efficiency. Check outcomes and protected content, not exact tool-call sequences or exhaustive protocol details. Run explicitly, never as part of the default unit test command.
+- When E2E exposes a tool bug, reproduce and fix it in unit tests first; use integration only where necessary. Check verifier changes offline against retained or synthetic evidence before another paid run.
+- Attribute agent failures and recovery from observable evidence. A failed call alone does not establish task failure or a tool defect.
 
 ## Documentation
 
 - `README.md` — user-facing install/commands
+- `docs/node-distro.md` — optional conversion from source-only Bun plugins to a bundled Node MCP distribution
 - `docs/architecture.md` — maintainer internals (create if missing)
 - Generated: `just docgen` → `docs/cli.md`, `docs/cli-schema.json`
 - `skills/mcp-plugin/SKILL.md` — agent skill router (scaffolded from template; customize as needed)

package/examples/mcp-plugin/README.md

@@ -6,13 +6,17 @@ Argsbarg MCP plugin template for Cursor and Claude Code marketplaces (@sg schema
 
 `mcp-plugin` packages an MCP server and agent skills directly for Cursor and Claude Code marketplaces:
 
-- **Cursor Plugin**: `.cursor-plugin/plugin.json` and `mcp.json` running `${CURSOR_PLUGIN_ROOT}/scripts/mcp.mjs` via `node`.
-- **Claude Code Plugin**: `.claude-plugin/plugin.json` and `.mcp.json` running `${CLAUDE_PLUGIN_ROOT}/scripts/mcp.mjs` via `node`.
+- **Cursor Plugin**: inline MCP configuration in `.cursor-plugin/plugin.json` runs `bun --cwd ${CURSOR_PLUGIN_ROOT} start`.
+- **Claude Code Plugin**: inline MCP configuration in `.claude-plugin/plugin.json` runs `bun --cwd ${CLAUDE_PLUGIN_ROOT} start`.
 - **In-repo skills**: `skills/mcp-plugin/SKILL.md` discovered and loaded by agent platforms.
-- **Standalone runner**: `bun build --target=node src/index.ts --outfile scripts/mcp.mjs` creates an inlined, zero-npm-install script.
+- **Source-only distribution**: TypeScript and `bun.lock` are shipped; dependencies and generated schemas are prepared locally. No compiled bundle is shipped.
 
 ## Installation
 
+Requires Bun >=1.3 on the host's PATH, a writable plugin directory, and network access for uncached dependencies. `bun start` installs locked dependencies and generates schemas before starting MCP. Setup output goes to stderr; stdout contains only MCP messages. Startup stops if preparation fails.
+
+The in-repo example retains its `argsbarg: file:../..` development dependency. Before distributing a standalone copy, resolve that dependency for the destination repository and regenerate its lockfile; the parent-checkout path is not portable.
+
 ### Cursor
 
 Recommended: import directly from GitHub — Cursor Dashboard → **Settings → Plugins → Team Marketplaces → Import**, then enter `https://github.com/bdombro/bun-argsbarg` (subdirectory `examples/mcp-plugin` once copied to its own repo). Once published to the [official marketplace](https://cursor.com/marketplace/publish), install via `/add-plugin mcp-plugin` or the Customize sidebar.
@@ -23,9 +27,11 @@ Recommended: add the GitHub repo as a marketplace, then install:
 
 ```bash
 /plugin marketplace add <owner>/<repo>
-/plugin install mcp-plugin@<repo>
+/plugin install mcp-plugin@mcp-plugin
 ```
 
+The marketplace name comes from `.claude-plugin/marketplace.json`, not the repository name.
+
 Once merged into [anthropics/claude-plugins-official](https://github.com/anthropics/claude-plugins-official), install via `/plugin install mcp-plugin@claude-plugins-official`.
 
 ## Commands
@@ -52,16 +58,18 @@ cd bun-argsbarg/examples/mcp-plugin
 # Install dependencies and generate schemas
 just setup
 
-# Build standalone MCP bundle
-just build
-
-# Test MCP server directly with node
-node ./scripts/mcp.mjs mcp
+# Run the source-only MCP server
+bun start
 
 # Link into local Cursor plugins for live testing
-just install-plugin-cursor
+just plugin-cursor-upsert
+
+# Register this checkout as a marketplace and install in Claude Code
+just plugin-claude-install
 ```
 
+Restart Claude Code after installing. Use `bun src/index.ts <command>` for CLI commands; `bun start` is specifically the MCP entry point. In-repo development uses `just setup` to repair the local dependency's CLI executable link.
+
 ## Documentation
 
 | Need | Resource |
@@ -70,3 +78,4 @@ just install-plugin-cursor
 | MCP tools | [docs/mcp.md](docs/mcp.md) or `mcp-plugin docs mcp` |
 | HTTP API | [docs/http.md](docs/http.md) or `mcp-plugin docs http` |
 | OpenAPI 3.1 | [docs/openapi.json](docs/openapi.json) |
+| Optional Node distribution | [docs/node-distro.md](docs/node-distro.md) |

package/examples/mcp-plugin/bun.lock

@@ -33,16 +33,98 @@
 
     "@biomejs/cli-win32-x64": ["@biomejs/cli-win32-x64@2.5.1", "", { "os": "win32", "cpu": "x64" }, "sha512-6uxpR9hvaglANkZemeSiN/FhYgkGasrEGn267eXIWvjrjJ2LhDlk251IhjVJq6MXzkV2/bcXwLwSroLyPtqRZg=="],
 
+    "@cfworker/json-schema": ["@cfworker/json-schema@4.1.1", "", {}, "sha512-gAmrUZSGtKc3AiBL71iNWxDsyUC5uMaKKGdvzYsBoTW/xi42JQHl7eKV2OYzCUqvc+D2RCcf7EXY2iCyFIk6og=="],
+
     "@types/bun": ["@types/bun@1.3.14", "", { "dependencies": { "bun-types": "1.3.14" } }, "sha512-h1hFqFVcvAvD9j9K7ZW7vd82aSA+rTdznZa+5bwvCwqSB1jmmfLcbIWhOLx1/+boy/xmjgCs/OMUL8hRJSmnPw=="],
 
+    "@types/json-schema": ["@types/json-schema@7.0.15", "", {}, "sha512-5+fP8P8MFNC+AyZCDxrB2pkZFPGzqQWUzpSeuuVLvm8VMcorNYavBqoFcxK8bQz4Qsbn4oUEEem4wDLfcysGHA=="],
+
     "@types/node": ["@types/node@26.0.0", "", { "dependencies": { "undici-types": "~8.3.0" } }, "sha512-vf2YFi1iY9lHGwNJMs01biZFbKJkrZR1T6/MlzjhJLPdntOHLhTrDSnSVcdtvjihi4VQNlrFRIxLsDBlQpAipA=="],
 
-    "argsbarg": ["argsbarg@file:../..", { "devDependencies": { "@biomejs/biome": "^2.5.0", "@types/bun": "^1.3.12", "typescript": "^5.9.3" }, "bin": { "argsbarg": "src/index.ts" } }],
+    "ansi-regex": ["ansi-regex@5.0.1", "", {}, "sha512-quJQXlTSUGL2LH9SUXo8VwsY4soanhgo6LNSm84E1LBcE8s3O0wpdiRzyR9z/ZZJMlMWv37qOOb9pdJlMUEKFQ=="],
+
+    "ansi-styles": ["ansi-styles@4.3.0", "", { "dependencies": { "color-convert": "^2.0.1" } }, "sha512-zbB9rCJAT1rbjiVDb2hqKFHNYLxgtk8NURxZ3IZwD3F6NtxbXZQCnnSi1Lkx+IDohdPlFp222wVALIheZJQSEg=="],
+
+    "argsbarg": ["argsbarg@file:../..", { "dependencies": { "@cfworker/json-schema": "^4", "ts-json-schema-generator": "^2.3.0" }, "devDependencies": { "@biomejs/biome": "^2.5.5", "@types/bun": "^1.3.12", "dts-bundle-generator": "^9.5.1", "typescript": "^5.9.3" }, "bin": { "argsbarg": "bin/argsbarg" } }],
+
+    "balanced-match": ["balanced-match@4.0.4", "", {}, "sha512-BLrgEcRTwX2o6gGxGOCNyMvGSp35YofuYzw9h1IMTRmKqttAZZVU67bdb9Pr2vUHA8+j3i2tJfjO6C6+4myGTA=="],
+
+    "brace-expansion": ["brace-expansion@5.0.12", "", { "dependencies": { "balanced-match": "^4.0.2" } }, "sha512-YovQ3rzhaLMIrDjNDMkNS01tea93qhEhG5xy8f6+R0l+dw3Ki+5sCoIoI942iuLZTHWogWktgwVDhU09iNEimQ=="],
 
     "bun-types": ["bun-types@1.3.14", "", { "dependencies": { "@types/node": "*" } }, "sha512-4N0ig0fEomHt5R0KCFWjovxow98rIoRwKolrYdCcknNwMekCXRnWEUvgu5soYV8QXtVsrUD8B95MBOZGPvr6KQ=="],
 
+    "cliui": ["cliui@8.0.1", "", { "dependencies": { "string-width": "^4.2.0", "strip-ansi": "^6.0.1", "wrap-ansi": "^7.0.0" } }, "sha512-BSeNnyus75C4//NQ9gQt1/csTXyo/8Sb+afLAkzAptFuMsod9HFokGNudZpi/oQV73hnVK+sR+5PVRMd+Dr7YQ=="],
+
+    "color-convert": ["color-convert@2.0.1", "", { "dependencies": { "color-name": "~1.1.4" } }, "sha512-RRECPsj7iu/xb5oKYcsFHSppFNnsj/52OVTRKb4zP5onXwVF3zVmmToNcOfGC+CRDpfK/U584fMg38ZHCaElKQ=="],
+
+    "color-name": ["color-name@1.1.4", "", {}, "sha512-dOy+3AuW3a2wNbZHIuMZpTcgjGuLU/uBL/ubcZF9OXbDo8ff4O8yVp5Bf0efS8uEoYo5q4Fx7dY9OgQGXgAsQA=="],
+
+    "commander": ["commander@14.0.3", "", {}, "sha512-H+y0Jo/T1RZ9qPP4Eh1pkcQcLRglraJaSLoyOtHxu6AapkjWVCy2Sit1QQ4x3Dng8qDlSsZEet7g5Pq06MvTgw=="],
+
+    "dts-bundle-generator": ["dts-bundle-generator@9.5.1", "", { "dependencies": { "typescript": ">=5.0.2", "yargs": "^17.6.0" }, "bin": { "dts-bundle-generator": "dist/bin/dts-bundle-generator.js" } }, "sha512-DxpJOb2FNnEyOzMkG11sxO2dmxPjthoVWxfKqWYJ/bI/rT1rvTMktF5EKjAYrRZu6Z6t3NhOUZ0sZ5ZXevOfbA=="],
+
+    "emoji-regex": ["emoji-regex@8.0.0", "", {}, "sha512-MSjYzcWNOA0ewAHpz0MxpYFvwg6yjy1NG3xteoqz644VCo/RPgnr1/GGt+ic3iJTzQ8Eu3TdM14SawnVUmGE6A=="],
+
+    "escalade": ["escalade@3.2.0", "", {}, "sha512-WUj2qlxaQtO4g6Pq5c29GTcWGDyd8itL8zTlipgECz3JesAiiOKotd8JU6otB3PACgG6xkJUyVhboMS+bje/jA=="],
+
+    "get-caller-file": ["get-caller-file@2.0.5", "", {}, "sha512-DyFP3BM/3YHTQOCUL/w0OZHR0lpKeGrxotcHWcqNEdnltqFwXVfhEBQ94eIo34AfQpo0rGki4cyIiftY06h2Fg=="],
+
+    "glob": ["glob@13.0.6", "", { "dependencies": { "minimatch": "^10.2.2", "minipass": "^7.1.3", "path-scurry": "^2.0.2" } }, "sha512-Wjlyrolmm8uDpm/ogGyXZXb1Z+Ca2B8NbJwqBVg0axK9GbBeoS7yGV6vjXnYdGm6X53iehEuxxbyiKp8QmN4Vw=="],
+
+    "is-fullwidth-code-point": ["is-fullwidth-code-point@3.0.0", "", {}, "sha512-zymm5+u+sCsSWyD9qNaejV3DFvhCKclKdizYaJUuHA83RLjb7nSuGnddCHGv0hk+KY7BMAlsWeK4Ueg6EV6XQg=="],
+
+    "json5": ["json5@2.2.3", "", { "bin": { "json5": "lib/cli.js" } }, "sha512-XmOWe7eyHYH14cLdVPoyg+GOH3rYX++KpzrylJwSW98t3Nk+U8XOl8FWKOgwtzdb8lXGf6zYwDUzeHMWfxasyg=="],
+
+    "lru-cache": ["lru-cache@11.5.3", "", {}, "sha512-U4N8FgzmWxc8k1VH8Kr6lQg18U7Fjvby6wXHVRX/ZZ7IwWbRMgrRbP0Wrb5q5NVinryp4SQampHKdvtecItxUg=="],
+
+    "minimatch": ["minimatch@10.2.6", "", { "dependencies": { "brace-expansion": "^5.0.8" } }, "sha512-vpLQEs+VLCr1nU0BXS07maYoFwlDAH0gngQuuttxIwutDFEMHq2blX+8vpgxDdK3J1PwjCJiep77OitTZ4Ll1A=="],
+
+    "minipass": ["minipass@7.1.3", "", {}, "sha512-tEBHqDnIoM/1rXME1zgka9g6Q2lcoCkxHLuc7ODJ5BxbP5d4c2Z5cGgtXAku59200Cx7diuHTOYfSBD8n6mm8A=="],
+
+    "normalize-path": ["normalize-path@3.0.0", "", {}, "sha512-6eZs5Ls3WtCisHWp9S2GUy8dqkpGi4BVSz3GaqiE6ezub0512ESztXUwUB6C6IKbQkY2Pnb/mD4WYojCRwcwLA=="],
+
+    "path-scurry": ["path-scurry@2.0.2", "", { "dependencies": { "lru-cache": "^11.0.0", "minipass": "^7.1.2" } }, "sha512-3O/iVVsJAPsOnpwWIeD+d6z/7PmqApyQePUtCndjatj/9I5LylHvt5qluFaBT3I5h3r1ejfR056c+FCv+NnNXg=="],
+
+    "require-directory": ["require-directory@2.1.1", "", {}, "sha512-fGxEI7+wsG9xrvdjsrlmL22OMTTiHRwAMroiEeMgq8gzoLC/PQr7RsRDSTLUg/bZAZtF+TVIkHc6/4RIKrui+Q=="],
+
+    "safe-stable-stringify": ["safe-stable-stringify@2.5.0", "", {}, "sha512-b3rppTKm9T+PsVCBEOUR46GWI7fdOs00VKZ1+9c1EWDaDMvjQc6tUwuFyIprgGgTcWoVHSKrU8H31ZHA2e0RHA=="],
+
+    "string-width": ["string-width@4.2.3", "", { "dependencies": { "emoji-regex": "^8.0.0", "is-fullwidth-code-point": "^3.0.0", "strip-ansi": "^6.0.1" } }, "sha512-wKyQRQpjJ0sIp62ErSZdGsjMJWsap5oRNihHhu6G7JVO/9jIB6UyevL+tXuOqrng8j/cxKTWyWUwvSTriiZz/g=="],
+
+    "strip-ansi": ["strip-ansi@6.0.1", "", { "dependencies": { "ansi-regex": "^5.0.1" } }, "sha512-Y38VPSHcqkFrCpFnQ9vuSXmquuv5oXOKpGeT6aGrr3o3Gc9AlVa6JBfUSOCnbxGGZF+/0ooI7KrPuUSztUdU5A=="],
+
+    "ts-json-schema-generator": ["ts-json-schema-generator@2.9.0", "", { "dependencies": { "@types/json-schema": "^7.0.15", "commander": "^14.0.3", "glob": "^13.0.6", "json5": "^2.2.3", "normalize-path": "^3.0.0", "safe-stable-stringify": "^2.5.0", "tslib": "^2.8.1", "typescript": "^5.9.3" }, "bin": { "ts-json-schema-generator": "bin/ts-json-schema-generator.js" } }, "sha512-NR5ZE108uiPtBHBJNGnhwoUaUx5vWTDJzDFG9YlRoqxPU76n+5FClRh92dcGgysbe1smRmYalM9Saj97GW1J4Q=="],
+
+    "tslib": ["tslib@2.8.1", "", {}, "sha512-oJFu94HQb+KVduSUQL7wnpmqnfmLsOA/nAh6b6EH0wCEoK0/mPeXU6c3wKDV83MkOuHPRHtSXKKU99IBazS/2w=="],
+
     "typescript": ["typescript@5.9.3", "", { "bin": { "tsc": "bin/tsc", "tsserver": "bin/tsserver" } }, "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw=="],
 
     "undici-types": ["undici-types@8.3.0", "", {}, "sha512-j375ScV60dom+YkPFIfTLcOiPxkN/buHz5GobjLhixFuANaNs3C9l4GmrWqejgXWJ7BbJcFYpTEUkS1Ge8bpZQ=="],
+
+    "wrap-ansi": ["wrap-ansi@7.0.0", "", { "dependencies": { "ansi-styles": "^4.0.0", "string-width": "^4.1.0", "strip-ansi": "^6.0.0" } }, "sha512-YVGIj2kamLSTxw6NsZjoBxfSwsn0ycdesmc4p+Q21c5zPuZ1pl+NfxVdxPtdHvmNVOQ6XSYG4AUtyt/Fi7D16Q=="],
+
+    "y18n": ["y18n@5.0.8", "", {}, "sha512-0pfFzegeDWJHJIAmTLRP2DwHjdF5s7jo9tuztdQxAhINCdvS+3nGINqPd00AphqJR/0LhANUS6/+7SCb98YOfA=="],
+
+    "yargs": ["yargs@17.7.3", "", { "dependencies": { "cliui": "^8.0.1", "escalade": "^3.1.1", "get-caller-file": "^2.0.5", "require-directory": "^2.1.1", "string-width": "^4.2.3", "y18n": "^5.0.5", "yargs-parser": "^21.1.1" } }, "sha512-GZtjxm/J/4TSxuL3FNYjCmLktBTnIw/rVmKSIyKeYAZpmJB2ig9VauCC5xsa82GNKVKDAqpOn3KVzNt0zmrU0g=="],
+
+    "yargs-parser": ["yargs-parser@21.1.1", "", {}, "sha512-tVpsJW7DdjecAiFpbIB1e3qxIQsE6NoPc5/eTdrbbIC4h0LVsWhnoa3g+m2HclBIujHzsxZ4VJVA+GUuc2/LBw=="],
+
+    "argsbarg/@biomejs/biome": ["@biomejs/biome@2.5.14", "", { "optionalDependencies": { "@biomejs/cli-darwin-arm64": "2.5.14", "@biomejs/cli-darwin-x64": "2.5.14", "@biomejs/cli-linux-arm64": "2.5.14", "@biomejs/cli-linux-arm64-musl": "2.5.14", "@biomejs/cli-linux-x64": "2.5.14", "@biomejs/cli-linux-x64-musl": "2.5.14", "@biomejs/cli-win32-arm64": "2.5.14", "@biomejs/cli-win32-x64": "2.5.14" }, "bin": { "biome": "bin/biome" } }, "sha512-0FabLIjd4M/dm8VFI86RMaLLdgepzbdfiAL2R8cr7V81OYYrP1w7Z73KfAwPK5h9SrEBXTzNG2y+mBwPo9xRnw=="],
+
+    "argsbarg/@biomejs/biome/@biomejs/cli-darwin-arm64": ["@biomejs/cli-darwin-arm64@2.5.14", "", { "os": "darwin", "cpu": "arm64" }, "sha512-UnzaXO65L4tsZimFITFP2M121GyhDcWFrT3pL5ZJ5U4XcS/0L5VHYytVohdCf/gnDUFHgl2I9xnt5bV/J1kxHQ=="],
+
+    "argsbarg/@biomejs/biome/@biomejs/cli-darwin-x64": ["@biomejs/cli-darwin-x64@2.5.14", "", { "os": "darwin", "cpu": "x64" }, "sha512-kiy8qA16K93J7uvFfWi4LgjqDpnRKyePAna6A0Y4jxyUga35SYpIZ2cNWlhy0lsfgqRenCpfymnJWEZ6mgpRgA=="],
+
+    "argsbarg/@biomejs/biome/@biomejs/cli-linux-arm64": ["@biomejs/cli-linux-arm64@2.5.14", "", { "os": "linux", "cpu": "arm64" }, "sha512-vO/9BaU1n30CiFNLx49gMTMtbCAAqlo/EqFoG0BU3deQInTbJrmXSmTQ9e3FoDZIKQnvSLDVNL4lx1ci7y1T1Q=="],
+
+    "argsbarg/@biomejs/biome/@biomejs/cli-linux-arm64-musl": ["@biomejs/cli-linux-arm64-musl@2.5.14", "", { "os": "linux", "cpu": "arm64" }, "sha512-SJ9PrZkBnnH9dHJDnxk34vKs0GB2dbsioaft6/hPhWJ7AHpwYH83Isnhj0FSRpFkGgpVfJ1lds23ApB2czUDLQ=="],
+
+    "argsbarg/@biomejs/biome/@biomejs/cli-linux-x64": ["@biomejs/cli-linux-x64@2.5.14", "", { "os": "linux", "cpu": "x64" }, "sha512-VHZRa7CCQBUWKxNwUvHJeuW03WFRgN5NWO//SDGOitc9QIeNyfA42V9zlKm+x82xFSG9Bzi5fi+hbhm9anO8yA=="],
+
+    "argsbarg/@biomejs/biome/@biomejs/cli-linux-x64-musl": ["@biomejs/cli-linux-x64-musl@2.5.14", "", { "os": "linux", "cpu": "x64" }, "sha512-2kI5PrMgW5dcEZYrstLPmUmCwkUwZY39rP4BN93Vxbwcs2O57LDQOktUZZYPvvspN5i0mhGr3TJtF5sU26NUWg=="],
+
+    "argsbarg/@biomejs/biome/@biomejs/cli-win32-arm64": ["@biomejs/cli-win32-arm64@2.5.14", "", { "os": "win32", "cpu": "arm64" }, "sha512-pHgAFffmZtaYoxavEsWEYNvcA7NwOIjLyqw2HXyLbt16xYryX0L4fMV2u0G9ag6LNYPIoqWaWqzUcnc6rLGGXg=="],
+
+    "argsbarg/@biomejs/biome/@biomejs/cli-win32-x64": ["@biomejs/cli-win32-x64@2.5.14", "", { "os": "win32", "cpu": "x64" }, "sha512-oJWmBhoHsnhUKIke+0gXDX0mltJrWHA1UyHsrTlXwX0TL64ilVZAo+TYZm97baecV0esBdpzy3k96q+09JaZUQ=="],
   }
 }

package/examples/mcp-plugin/bunfig.toml

@@ -1,3 +1,7 @@
 [install]
 # fetch package.json deps on first `bun src/index.ts` without manual `bun install`.
 auto = "fallback"
+
+[run]
+shell = "bun"
+silent = true

package/examples/mcp-plugin/docs/node-distro.md

@@ -0,0 +1,97 @@
+# Node Distribution
+
+The default plugin ships TypeScript and starts with Bun. To ship a standalone
+Node MCP server instead, follow the bundle-based distribution described below.
+Bun remains the development/build tool; plugin users need Node but do not need
+Bun, dependency installation, or schema generation at startup.
+ Note: bundle distrobutions mean committing large bundled js files to the repo.
+## 1. Build The Bundle
+
+Add this recipe to `justfile`:
+
+```just
+# Generate schemas and bundle the standalone Node MCP server
+build: schemagen
+    bun build ./src/index.ts --target=node --outfile=./scripts/mcp.mjs
+```
+
+Run `just setup` and `just build` from the project root. Schemas must exist before
+bundling so their static imports are included in the output.
+
+Keep the MCP runtime compatible with Node. Bundling does not implement Bun-only
+APIs such as `Bun.serve` or `bun:sqlite`; port or exclude any such runtime paths.
+The HTTP server capability is separate from this Node MCP distribution.
+
+## 2. Change Startup
+
+Remove `prestart` from `package.json` and change `start` to:
+
+```json
+"start": "node scripts/mcp.mjs mcp"
+```
+
+Declare the supported Node version range under `engines.node` and document it in
+the README. Bun is still needed by maintainers for schema generation, tests, and
+bundling. The Bun shell settings in `bunfig.toml` can remain for development.
+
+## 3. Update Inline Plugin Configs
+
+Keep MCP configuration inside the plugin manifests; do not reintroduce separate
+root MCP config files. Replace the `mcpServers` field in
+`.claude-plugin/plugin.json` with:
+
+```json
+"mcpServers": {
+  "mcp-plugin": {
+    "command": "node",
+    "args": ["${CLAUDE_PLUGIN_ROOT}/scripts/mcp.mjs", "mcp"]
+  }
+}
+```
+
+Use the corresponding field in `.cursor-plugin/plugin.json`:
+
+```json
+"mcpServers": {
+  "mcp-plugin": {
+    "command": "node",
+    "args": ["${CURSOR_PLUGIN_ROOT}/scripts/mcp.mjs", "mcp"]
+  }
+}
+```
+
+Launching Node directly avoids relying on a package manager on the user's
+machine. Keep each path as one argument so plugin roots containing spaces work.
+
+## 4. Package And Release
+
+- Add `build` as a dependency of `plugin-cursor-upsert` and
+  `plugin-claude-install` so local installs have a fresh bundle.
+- Restore `just build` in `scripts/release.ts` after version/documentation
+  updates and before committing or publishing. Fail the release if it fails.
+- Include `scripts/mcp.mjs` in the released plugin. For repository-based
+  installation, commit the generated bundle so a fresh clone is runnable.
+- Do not ship `node_modules` or generated schemas separately. Their runtime
+  contents should be bundled; inspect external imports and package any required
+  runtime assets explicitly.
+- Update the README and the project-specific tooling section of `AGENTS.md`
+  to describe Node as the plugin runtime and Bun as the development tool.
+
+## 5. Verify The Node Distribution
+
+After building, a basic stdio check is:
+
+```bash
+printf '%s\n' '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' \
+  | node scripts/mcp.mjs mcp
+```
+
+Only JSON-RPC responses should appear on stdout. Exercise `tools/list` and a
+representative tool call as well: successful initialization alone does not prove
+that every command's runtime dependencies are Node-compatible.
+
+Check both manifest commands from an unrelated working directory with the
+plugin-root placeholders expanded to the installed path. Verify a clean copy
+with no `node_modules` or generated schemas, using the declared minimum Node
+version and a current supported Node version. Keep transport/package checks at
+the integration level; agent E2E should measure real user-task outcomes.

package/examples/mcp-plugin/justfile

@@ -7,10 +7,6 @@ export PATH := justfile_directory() + "/node_modules/.bin:" + env_var("PATH")
 _:
     @just --list
 
-# Bundle the standalone Node MCP server script
-build:
-    bun build ./src/index.ts --target=node --outfile=./scripts/mcp.mjs
-
 # Run schemagen, typecheck, and format
 check: schemagen format typecheck
 
@@ -52,16 +48,21 @@ format:
 http:
     @just run http
 
+# Lint sources without writing
+lint:
+    bun run biome check ./src ./scripts
+
+# Install the Claude Code plugin from this checkout (restart Claude Code afterwards)
+plugin-claude-install:
+    claude plugin marketplace add "$(pwd)"
+    claude plugin install mcp-plugin@mcp-plugin
+
 # Link plugin into ~/.cursor/plugins/local/mcp-plugin for local testing
-install-plugin-cursor: build
+plugin-cursor-upsert:
     mkdir -p ~/.cursor/plugins/local
     ln -sfn '{{justfile_directory()}}' ~/.cursor/plugins/local/mcp-plugin
     @echo "Linked MCP plugin to ~/.cursor/plugins/local/mcp-plugin"
 
-# Lint sources without writing
-lint:
-    bun run biome check ./src ./scripts
-
 # Run the CLI from source once
 run *ARGS:
     bun ./src/index.ts {{ARGS}}
@@ -73,14 +74,14 @@ schemagen:
 # Install bun/npm dependencies and generate schemas
 setup:
     bun install
-    test -f node_modules/argsbarg/bin/argsbarg && ln -sf ../argsbarg/bin/argsbarg node_modules/.bin/argsbarg
+    test -f node_modules/argsbarg/bin/argsbarg && ln -sf ../argsbarg/bin/argsbarg node_modules/.bin/argsbarg # argsbarg-dev-only: fix link for file:../.. installs
     just schemagen
 
 # Run unit tests (after check)
 test: check
     bun test .
 
-# Bump version, build, publish release
+# Bump version and publish a source-only release
 release *ARGS:
     bun scripts/release.ts {{ARGS}}
 

package/examples/mcp-plugin/package.json

@@ -10,7 +10,8 @@
   },
   "scripts": {
     "biome": "biome",
-    "start": "bun run src/index.ts"
+    "prestart": "bun install --frozen-lockfile 1>&2 && bun run argsbarg schemagen 1>&2",
+    "start": "bun src/index.ts mcp"
   },
   "dependencies": {
     "argsbarg": "file:../.."

package/examples/mcp-plugin/scripts/release.ts

@@ -1,6 +1,6 @@
 #!/usr/bin/env bun
 /*
-Bump version, build standalone Node MCP server, and publish release tag.
+Bump version and publish a source-only Bun plugin release tag.
 */
 
 import * as fs from "node:fs";
@@ -76,27 +76,26 @@ async function runRelease(
   /** Parsed CLI options. */
   options: ReleaseOptions,
 ): Promise<void> {
+  const currentVersion = readCurrentVersion();
+  const newVersion = applyBump(currentVersion, bump);
+  if (options.dryRun) {
+    console.log(
+      `[dry-run] Would run checks, bump ${currentVersion} to ${newVersion}, update the changelog, regenerate docs, commit, tag v${newVersion}, push, and create a GitHub release.`,
+    );
+    return;
+  }
+
   const testResult = await $`just test`.nothrow();
   if (testResult.exitCode !== 0) process.exit(testResult.exitCode);
 
-  const currentVersion = readCurrentVersion();
-  const newVersion = applyBump(currentVersion, bump);
   console.log(`Releasing ${currentVersion} → ${newVersion}`);
 
   updateVersion(newVersion);
   updateChangelog(newVersion);
 
-  const buildResult = await $`just build`.nothrow();
-  if (buildResult.exitCode !== 0) process.exit(buildResult.exitCode);
-
   const docgenResult = await $`just docgen`.nothrow();
   if (docgenResult.exitCode !== 0) process.exit(docgenResult.exitCode);
 
-  if (options.dryRun) {
-    console.log(`[dry-run] Would commit, tag v${newVersion}, and create GitHub release.`);
-    return;
-  }
-
   await commitAndTag(newVersion);
   await createGithubRelease(`v${newVersion}`);
 

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.3",
   "main": "./src/index.ts",
   "module": "./src/index.ts",
   "dependencies": {