argsbarg 1.3.1 → 1.4.0

package/.cursor/plans/mcp_v1.1_polish_e9656029.plan.md

@@ -0,0 +1,260 @@
+---
+name: MCP v1.1 polish
+overview: "Ship four agent-focused MCP improvements: richer tool descriptions with CLI paths, per-leaf `mcpEnabled` opt-out, stderr surfaced on successful tool calls, and `structuredContent` when handler stdout is valid JSON."
+todos:
+  - id: types-mcpEnabled
+    content: "Add mcpEnabled?: boolean to CliCommandBase; validate leaf-only in validate.ts"
+    status: completed
+  - id: tool-descriptions
+    content: Add mcpToolDescription(path, rootKey, description); enrich descriptions; filter mcpEnabled === false
+    status: completed
+  - id: result-builder
+    content: Create src/mcp/result.ts with buildToolCallSuccess (stderr blocks + JSON structuredContent)
+    status: completed
+  - id: server-wire
+    content: Wire buildToolCallSuccess into tools/call success path in server.ts
+    status: completed
+  - id: tests
+    content: Unit tests for description, mcpEnabled, result builder; subprocess tests for JSON structuredContent and stderr-on-success
+    status: completed
+  - id: docs-changelog
+    content: Update docs/mcp.md and CHANGELOG.md; run just typegen and just test
+    status: completed
+isProject: false
+---
+
+# MCP follow-up improvements plan
+
+Four targeted enhancements to the existing opt-in MCP server. No new dependencies, no protocol transport changes, no public export of internals beyond the new `mcpEnabled` schema field.
+
+```mermaid
+flowchart LR
+  subgraph toolsList [tools/list]
+    Walk[collectMcpTools]
+    Desc["path + description"]
+    Filter[mcpEnabled filter]
+  end
+  subgraph toolCall [tools/call]
+    Invoke[cliInvoke]
+    Build[buildToolCallResult]
+    Resp["content + structuredContent?"]
+  end
+  Walk --> Filter --> Desc
+  Invoke --> Build --> Resp
+```
+
+---
+
+## 1. CLI path in tool descriptions
+
+**Goal:** Agents see the human invocation path without reading the schema resource first.
+
+**Format:**
+
+| Path | Leaf description | MCP `description` |
+| --- | --- | --- |
+| `["stat","owner","lookup"]` | `Resolve owner info.` | `stat owner lookup — Resolve owner info.` |
+| `["read"]` | `Print the first line…` | `read — Print the first line…` |
+| `[]` (root leaf app) | `Tiny demo.` | `{root.key} — Tiny demo.` |
+
+Use em dash (`—`) between path and description. Path segments are raw `key` values (not sanitized tool names). Every tool description uses the `prefix — description` form — there is no bare-description fallback.
+
+**Implementation:**
+
+- Add helper in [`src/mcp/tools.ts`](src/mcp/tools.ts). The helper **must** receive `rootKey` so root-leaf apps (empty path) can use the program name as the prefix:
+
+```typescript
+/** Builds MCP tool description: "{cli path} — {description}". */
+function mcpToolDescription(path: string[], rootKey: string, description: string): string {
+  const prefix = path.length > 0 ? path.join(" ") : rootKey;
+  return `${prefix} — ${description}`;
+}
+```
+
+- Call from `collectMcpTools` when building each `McpToolDef.description`:
+
+```typescript
+description: mcpToolDescription(path, root.key, cmd.description),
+```
+
+- `tools/list` already maps `t.description` — no server change needed.
+
+**Tests:** Update [`src/index.test.ts`](src/index.test.ts):
+
+- `stat_owner_lookup` description is `stat owner lookup — Resolve owner info.`
+- If testing a root-leaf fixture, description is `{root.key} — {description}`.
+
+---
+
+## 2. Per-leaf opt-out via `mcpEnabled`
+
+**Goal:** Authors can keep CLI commands for humans while hiding them from MCP tool discovery.
+
+**Schema change** in [`src/types.ts`](src/types.ts):
+
+```typescript
+export interface CliCommandBase {
+  // ...existing fields...
+  /** Leaf-only. When `false`, omit this command from MCP tools (default: exposed). */
+  mcpEnabled?: boolean;
+}
+```
+
+**Semantics:**
+
+- Omitted or `true` → leaf is exposed (current behavior).
+- `false` → skipped in `collectMcpTools` walk.
+- Root `mcp?: CliMcpConfig` unchanged — it enables the server; `mcpEnabled` is unrelated.
+
+**Validation** in [`src/validate.ts`](src/validate.ts) `walkCommand`:
+
+- If `isRoot && cmd.mcpEnabled !== undefined` → throw `mcpEnabled is only supported on leaf commands`.
+- If routing node (has `commands`, no `handler`) and `mcpEnabled !== undefined` → same error.
+- No validation needed for `false` vs `true` beyond that.
+
+**Tool collection** in [`src/mcp/tools.ts`](src/mcp/tools.ts) `walk`:
+
+```typescript
+if ("handler" in cmd && cmd.handler) {
+  if (cmd.key === "completion" || cmd.key === "mcp") return;
+  if (cmd.mcpEnabled === false) return;
+  // push tool...
+}
+```
+
+**Schema export:** Leave [`src/schema.ts`](src/schema.ts) unchanged for v1 — `--schema` still lists all commands (CLI discovery). Only MCP `tools/list` respects `mcpEnabled`. Document this distinction in [`docs/mcp.md`](docs/mcp.md).
+
+**Example (optional):** Add a hidden leaf in `nestedMcpFixture` only (not `examples/nested.ts`) with `mcpEnabled: false` to prove filtering without cluttering the demo app.
+
+---
+
+## 3. stderr on successful tool calls
+
+**Goal:** Warnings and diagnostic output on stderr are not silently dropped when `exitCode === 0`.
+
+**Current behavior** ([`src/mcp/server.ts`](src/mcp/server.ts) ~L133–141): success returns only `invokeResult.stdout`.
+
+**New behavior:** Extract a small builder (new file [`src/mcp/result.ts`](src/mcp/result.ts) recommended to keep server readable):
+
+```typescript
+export interface McpToolCallSuccess {
+  content: { type: "text"; text: string }[];
+  structuredContent?: unknown;
+  isError: false;
+}
+
+export function buildToolCallSuccess(stdout: string, stderr: string): McpToolCallSuccess
+```
+
+**stderr formatting rules:**
+
+- If `stderr.trim()` is empty → single `content` item with stdout (or empty string if stdout empty).
+- If stderr non-empty → **two** `content` items:
+  1. `{ type: "text", text: stdout }` (may be empty string)
+  2. `{ type: "text", text: stderr.trim() }` — **raw stderr text, no `stderr:` prefix**
+
+Use multiple content blocks rather than concatenating into one string so hosts can distinguish streams; the second block’s position in the array is the signal that it came from stderr. Some MCP hosts render content blocks with their own labeling — a literal `stderr:` prefix would leak into user-visible tool output. Existing failure path (~L144–151) already prefers stderr — leave as-is.
+
+**Tests:**
+
+- Unit test `buildToolCallSuccess` with stdout-only, stderr-only, both.
+- Subprocess test: add a fixture leaf (in test fixture or temporary nested command) that `console.warn`s on stderr but exits 0; assert two content blocks and `isError: false`.
+
+---
+
+## 4. `structuredContent` when stdout is valid JSON
+
+**Goal:** When handlers emit JSON (e.g. `nested.ts` with `--json`), MCP clients get machine-readable output per [MCP tools spec](https://modelcontextprotocol.io/specification/draft/server/tools).
+
+**Parsing rules** (in `buildToolCallSuccess`):
+
+1. Let `trimmed = stdout.trim()`.
+2. If `trimmed.length === 0` → no `structuredContent`.
+3. Try `JSON.parse(trimmed)`.
+4. On success → set `structuredContent` to the parsed value (object, array, or primitive — all valid per 2025 spec).
+5. On `SyntaxError` → no `structuredContent` (plain text handlers unchanged).
+6. **Always** keep `content[0].text` as the raw stdout string when stdout is non-empty (spec: structured tools SHOULD also return serialized JSON in `content` — we already have the raw stdout which satisfies this for JSON handlers).
+
+**Primitive footgun (document, do not guard):** `JSON.parse("true")` yields `structuredContent: true`. A handler that intentionally prints the string `true` as human-readable output would get machine-typed output. This is spec-correct and rare in practice. Document in [`docs/mcp.md`](docs/mcp.md) rather than limiting to `typeof parsed === "object"` — that would reject valid JSON arrays and primitives that the 2025 spec explicitly allows.
+
+**Do not** auto-generate `outputSchema` in this release — that requires schema author input or inference and is out of scope.
+
+**Server wiring** in [`src/mcp/server.ts`](src/mcp/server.ts):
+
+```typescript
+const result = buildToolCallSuccess(invokeResult.stdout, invokeResult.stderr);
+writeResponse({ jsonrpc: "2.0", id, result });
+```
+
+Spread `structuredContent` onto result only when defined.
+
+**Tests:**
+
+- Unit: `buildToolCallSuccess('{"a":1}\n', '')` → `structuredContent: { a: 1 }`, content text preserved.
+- Unit: `buildToolCallSuccess('lookup user=x\n', '')` → no `structuredContent`.
+- Unit: `buildToolCallSuccess('true\n', '')` → `structuredContent: true` (documents primitive behavior).
+- Subprocess: extend existing `stat_owner_lookup` test or add parallel test with `json: true`:
+
+```typescript
+params: {
+  name: "stat_owner_lookup",
+  arguments: { path: readme, "user-name": "test", json: true },
+}
+```
+
+Assert `result.structuredContent` deep-equals `{ user: "test", path: readme }` and `content[0].text` is valid JSON string.
+
+---
+
+## Documentation and changelog
+
+Update [`docs/mcp.md`](docs/mcp.md):
+
+- **Tool names** section: document new description format with example (including root-leaf `{root.key} — …` case).
+- **Per-leaf visibility**: `mcpEnabled: false` on leaves; note `--schema` still includes the command.
+- **Tool results**: stderr on success as a second raw-text content block (no prefix); `structuredContent` when stdout is valid JSON (including primitives — document footgun); link to MCP spec.
+- **Short flags**: one-line note that tool args use long option names only (unchanged, but good to document while editing).
+
+Update [`CHANGELOG.md`](CHANGELOG.md) under `[Unreleased]`:
+
+- Richer MCP tool descriptions with CLI paths.
+- `mcpEnabled` leaf opt-out.
+- MCP tool success responses include stderr when present.
+- MCP tool success responses include `structuredContent` for JSON stdout.
+
+Trim [`README.md`](README.md) MCP blurb only if needed — one line pointing to docs is enough.
+
+---
+
+## Type declarations and release hygiene
+
+- Run `just typegen` after [`src/types.ts`](src/types.ts) change so [`index.d.ts`](index.d.ts) exports `mcpEnabled`.
+- Run `just test` (typecheck + lint + `bun test`).
+
+**Public API surface:** Only `mcpEnabled?: boolean` on `CliCommandBase` is new. `cliInvoke`, `buildToolCallSuccess`, and MCP runtime remain internal.
+
+---
+
+## File change summary
+
+| File | Changes |
+| --- | --- |
+| [`src/types.ts`](src/types.ts) | Add `mcpEnabled?: boolean` with JSDoc |
+| [`src/validate.ts`](src/validate.ts) | Reject `mcpEnabled` on root and routing nodes |
+| [`src/mcp/tools.ts`](src/mcp/tools.ts) | `mcpToolDescription`, filter `mcpEnabled === false` |
+| [`src/mcp/result.ts`](src/mcp/result.ts) | **New** — `buildToolCallSuccess` |
+| [`src/mcp/server.ts`](src/mcp/server.ts) | Use builder for success path |
+| [`src/index.test.ts`](src/index.test.ts) | Unit + subprocess tests for all four features |
+| [`docs/mcp.md`](docs/mcp.md) | Document behavior |
+| [`CHANGELOG.md`](CHANGELOG.md) | Unreleased entries |
+| [`index.d.ts`](index.d.ts) | Regenerated via typegen |
+
+---
+
+## Out of scope (explicitly deferred)
+
+- Tool list caching
+- `outputSchema` on tools
+- Hiding `mcpEnabled: false` commands from `--schema`
+- Group-level `mcpEnabled` inheritance
+- `mcp.json` / Cursor config changes

package/CHANGELOG.md

@@ -7,6 +7,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.4.0] - 2026-06-19
+
+### Added
+
+- **Opt-in MCP** — set `mcpServer: {}` on the program root to enable `myapp mcp`, a stdio MCP server (tools + `argsbarg://schema` resource). Hand-rolled JSON-RPC; zero new dependencies.
+- **MCP tool descriptions** — `tools/list` descriptions include the CLI path (e.g. `stat owner lookup — Resolve owner info.`).
+- **`mcpTool` leaf opt-out** — set `mcpTool: { enabled: false }` on a leaf to omit it from MCP tools while keeping it in the CLI and `--schema`.
+- **MCP stderr on success** — successful tool calls return a second content block when the handler wrote to stderr.
+- **MCP `structuredContent`** — when handler stdout is valid JSON, tool results include parsed `structuredContent` alongside text content.
+
+### Fixed
+
+- **Parent-scoped options before positionals** — nested commands accept flags from ancestor nodes when options appear before positional arguments (required for MCP tool argv layout).
+
 ## [1.3.1] - 2026-06-19
 
 ### Fixed
@@ -84,7 +98,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - 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/v1.3.1...HEAD
+[Unreleased]: https://github.com/bdombro/bun-argsbarg/compare/v1.4.0...HEAD
+[1.4.0]: https://github.com/bdombro/bun-argsbarg/releases/tag/v1.4.0
 [1.3.1]: https://github.com/bdombro/bun-argsbarg/releases/tag/v1.3.1
 [1.3.0]: https://github.com/bdombro/bun-argsbarg/releases/tag/v1.3.0
 [1.2.1]: https://github.com/bdombro/bun-argsbarg/releases/tag/v1.2.1

package/README.md

@@ -10,9 +10,15 @@ Build beautiful, well-behaved CLI apps with Bun — **no third-party runtime dep
 
 Why another CLI parser?
 
-*Schema-first* -- define your entire CLI’s structure, commands, options, and help in a single, explicit data model, making the command-line interface centralized, clear, and self-describing upfront.
+*Schema-first* — define your entire CLI’s structure, commands, options, and help in a single, explicit data model, making the command-line interface centralized, clear, and self-describing upfront.
 
-*Bun-optimized* -- built from the ground up for Bun and TypeScript, leveraging Bun’s performance and modern JavaScript features without any extra dependencies.
+*Beautiful `-h` screens* — scoped help at any routing depth, rendered in rounded UTF-8 boxes with tables, terminal-width wrapping, and color when stdout is a TTY. Errors print in red with contextual help on stderr.
+
+*Shell completions* — `completion bash` and `completion zsh` built-ins generate installable scripts from your schema so users get tab completion for commands, flags, and positionals without extra tooling.
+
+*Optional MCP server* — set `mcpServer: {}` on the program root to expose leaf commands as MCP tools and the full CLI tree as a schema resource (`myapp mcp` over stdio). See [docs/mcp.md](docs/mcp.md).
+
+*Bun-optimized* — built from the ground up for Bun and TypeScript, leveraging Bun’s performance and modern JavaScript features without any extra dependencies.
 
 Also checkout ArgsBarg for [cpp](https://github.com/bdombro/cpp-argsbarg), [nim](https://github.com/bdombro/nim-argsbarg), and [swift](https://github.com/bdombro/swift-argsbarg)!
 
@@ -90,11 +96,20 @@ Every app gets:
 - `-h` / `--help` at any routing depth (scoped help).
 - **`--schema`** at the program root — print the full command tree as JSON (for tooling and agents).
 - **`completion bash` / `completion zsh`** — print shell completion scripts to stdout (injected by `cliRun`).
+- **`mcp`** — when `mcpServer: {}` is set on the program root, run an MCP server over stdio (`myapp mcp`).
 
 Do not declare a top-level command named **`completion`** — it is reserved for this built-in.
+Do not declare a top-level command named **`mcp`** — it is reserved when MCP is enabled.
 Do not declare an option named **`schema`** — it is reserved for `--schema`.
 
 
+### MCP (AI agents)
+
+Opt in on the program root with `mcpServer: {}` (or `{ name, version, … }`), then run `myapp mcp` for a stdio MCP server. Each leaf command becomes a tool; the CLI tree is available as resource `argsbarg://schema`.
+
+See **[docs/mcp.md](docs/mcp.md)** for configuration, Cursor setup, tool naming, argument mapping, and protocol details.
+
+
 ### Shell completions
 
 ```bash

package/docs/mcp.md

@@ -0,0 +1,211 @@
+# MCP server
+
+ArgsBarg can expose your CLI to AI agents through the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/). Each **leaf command** becomes an MCP tool; the full command tree is available as a schema resource. The server speaks JSON-RPC over stdio — one JSON object per line on stdin and stdout.
+
+MCP is **opt-in**. Apps that do not set `mcpServer` on the program root behave exactly as before.
+
+## Quick start
+
+1. Add `mcpServer` to your program root:
+
+```typescript
+const cli: CliCommand = {
+  key: "myapp",
+  description: "My app.",
+  mcpServer: { name: "myapp", version: "1.0.0" },
+  commands: [/* ... */],
+};
+```
+
+`mcpServer: {}` is enough to enable the server. Optional fields override defaults (see [Configuration](#configuration)).
+
+2. Run the MCP server:
+
+```bash
+myapp mcp
+```
+
+The process reads NDJSON requests from stdin and writes NDJSON responses to stdout. It stays alive until stdin closes.
+
+3. Point your MCP client at that command. See [Client setup](#client-setup).
+
+The `examples/nested.ts` demo enables MCP — try:
+
+```bash
+bun run examples/nested.ts mcp
+```
+
+## Client setup
+
+### Cursor
+
+Add a server entry under `mcpServers` in your Cursor MCP config:
+
+```json
+{
+  "mcpServers": {
+    "myapp": {
+      "command": "bun",
+      "args": ["run", "myapp.ts", "mcp"]
+    }
+  }
+}
+```
+
+Use your real binary or script path. For a compiled CLI, `command` can be the installed binary and `args` can be `["mcp"]` only.
+
+### Other MCP hosts
+
+Any host that spawns a subprocess and wires stdin/stdout works the same way: the **command** is your app, and **`mcp`** is the subcommand that starts the server.
+
+## Configuration
+
+Set `mcpServer` on the **program root only** (the `CliCommand` passed to `cliRun`). Validation rejects `mcpServer` on nested nodes.
+
+| Field | Default | Purpose |
+| --- | --- | --- |
+| `name` | root `key` | `serverInfo.name` in the `initialize` response |
+| `version` | `package.json` `version` in cwd, else `"0.0.0"` | `serverInfo.version` |
+| `schemaResourceUri` | `"argsbarg://schema"` | URI for the schema resource |
+
+Example with all fields:
+
+```typescript
+mcpServer: {
+  name: "nested-demo",
+  version: "1.0.0",
+  schemaResourceUri: "argsbarg://schema",
+}
+```
+
+## Tools
+
+Every **user-defined leaf command** in your schema becomes one MCP tool. Built-ins (`completion`, `mcp`) are not exposed as tools.
+
+### Tool names
+
+Tool names are derived from the command path, with each segment sanitized (non-alphanumeric characters become `_`) and joined with `_`.
+
+| CLI invocation | Tool name |
+| --- | --- |
+| `myapp deploy` | `deploy` |
+| `myapp stat owner lookup` | `stat_owner_lookup` |
+| `nested.ts read` | `read` |
+
+### Tool descriptions
+
+Each tool’s `description` includes the human CLI path and the leaf’s help text, separated by an em dash:
+
+| CLI path | MCP `description` |
+| --- | --- |
+| `stat owner lookup` | `stat owner lookup — Resolve owner info.` |
+| `read` | `read — Print the first line of each file.` |
+| (root leaf app) | `{root.key} — Tiny demo.` |
+
+### Per-leaf visibility
+
+Set `mcpTool: { enabled: false }` on a **leaf command** to hide it from `tools/list` while keeping it in the CLI and in `--schema` output:
+
+```typescript
+{
+  key: "debug",
+  description: "Internal diagnostics.",
+  mcpTool: { enabled: false },
+  handler: () => { /* ... */ },
+}
+```
+
+Omitted or `enabled: true` exposes the command (default). `mcpTool` is only valid on leaves — not on the program root or routing groups.
+
+### Tool arguments
+
+Each tool’s `inputSchema` is a JSON Schema object built from your CLI definition:
+
+- **Options** — parent-scoped flags are included (e.g. `stat`’s `--json` appears on `stat_owner_lookup`). Presence options are `boolean`; string and number options match their `CliOptionKind`. Required options are listed in `required`.
+- **Positionals** — one property per `CliPositional` on the leaf. Single-slot positionals are `string`; varargs tails (`argMax: 0`) are `string[]`. Required positionals are listed in `required`.
+
+Arguments are a **flat JSON object** keyed by option and positional names (same names as in your schema, including hyphenated option names like `"user-name"`).
+
+Example for `nested.ts stat owner lookup`:
+
+```json
+{
+  "path": "/path/to/file",
+  "user-name": "alice",
+  "json": true
+}
+```
+
+This maps to argv: `stat owner lookup --json --user-name alice /path/to/file`.
+
+Tool arguments use **long option names** only (`user-name`, not `-u`). Short aliases from your schema are not accepted in MCP tool calls.
+
+### Tool results
+
+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.
+
+On failure (parse error, validation error, non-zero exit, thrown error), the message is returned as text content with `isError: true`. Handler stderr is included when present.
+
+Help and `--schema` are not available through tool calls; use the schema resource or run the CLI directly for those.
+
+## Schema resource
+
+The server advertises one MCP resource: your full CLI tree as JSON — the same output as `myapp --schema`.
+
+| Property | Value |
+| --- | --- |
+| Default URI | `argsbarg://schema` |
+| MIME type | `application/json` |
+| Contents | `cliSchemaJson(root)` — handlers omitted, built-ins excluded |
+
+Agents can read this resource to discover commands, options, and positionals without guessing tool shapes.
+
+## Protocol
+
+- **Transport:** stdio, newline-delimited JSON (NDJSON).
+- **JSON-RPC:** version `2.0`.
+- **MCP protocol version:** `2024-11-05` (reported in `initialize`).
+
+### Supported methods
+
+| Method | Description |
+| --- | --- |
+| `initialize` | Returns capabilities (`tools`, `resources`) and `serverInfo`. |
+| `notifications/initialized` | Acknowledged; no response (notification). |
+| `ping` | Returns `{}`. |
+| `tools/list` | Lists all tools with `name`, `description`, `inputSchema`. |
+| `tools/call` | Runs a leaf handler; params: `name`, `arguments` (object). |
+| `resources/list` | Lists the schema resource. |
+| `resources/read` | Returns schema JSON; params: `uri`. |
+
+Requests without an `id` are treated as notifications and do not receive a response (except `notifications/initialized`, which is ignored after parsing).
+
+### Manual smoke test
+
+```bash
+printf '%s\n' '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' | bun run examples/nested.ts mcp
+```
+
+You should get one JSON line on stdout with `result.capabilities` and `result.serverInfo`.
+
+## Reserved names
+
+When MCP is enabled:
+
+- Do not declare a top-level command named **`mcp`** — it is reserved for the built-in subcommand.
+- Do not declare a top-level command named **`completion`** — reserved for shell completions.
+- Do not declare an option named **`schema`** — reserved for `--schema`.
+
+Running `myapp mcp` without `mcpServer` on the root fails with an error (exit 1).
+
+## Design notes
+
+- **Zero extra dependencies** — hand-rolled NDJSON JSON-RPC on top of ArgsBarg’s existing parser and schema.
+- **Same handlers** — tool calls run your real leaf handlers via an internal invoke path that captures stdout/stderr and does not exit the process, so the MCP server can handle many requests in one process.
+- **User schema only** — tool dispatch uses your program root, not merged presentation builtins.
+
+For the `--schema` export used by the resource, see the main README built-ins section.

package/examples/nested.ts

@@ -12,6 +12,7 @@ import { cliRun, CliCommand, CliOptionKind, CliFallbackMode } from "../src/index
 const cli: CliCommand = {
   key: "nested.ts",
   description: "Nested groups demo.",
+  mcpServer: { name: "nested-demo", version: "1.0.0" },
   commands: [
     {
       key: "stat",

package/index.d.ts

@@ -66,6 +66,24 @@ export interface CliPositional {
 	 */
 	argMax?: number;
 }
+/**
+ * Root-only. Enables `myapp mcp` and MCP stdio server metadata.
+ */
+export interface CliMcpServerConfig {
+	/** `initialize` serverInfo.name (default: root `key`). */
+	name?: string;
+	/** `initialize` serverInfo.version (default: see resolveMcpVersion). */
+	version?: string;
+	/** Resource URI for schema export (default: `"argsbarg://schema"`). */
+	schemaResourceUri?: string;
+}
+/**
+ * Leaf-only. Controls how this command appears as an MCP tool.
+ */
+export interface CliMcpToolConfig {
+	/** When `false`, omit from `tools/list` (default: exposed). */
+	enabled?: boolean;
+}
 /**
  * Base properties shared by all command nodes.
  */
@@ -78,6 +96,10 @@ export interface CliCommandBase {
 	notes?: string;
 	/** Global or command-level flags/options. */
 	options?: CliOption[];
+	/** Root-only. When set, enables the `mcp` built-in subcommand. */
+	mcpServer?: CliMcpServerConfig;
+	/** Leaf-only. Per-tool MCP exposure and metadata. */
+	mcpTool?: CliMcpToolConfig;
 }
 /**
  * A command node: either a routing group (has commands) or a leaf (has handler).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "argsbarg",
-  "version": "1.3.1",
+  "version": "1.4.0",
   "type": "module",
   "scripts": {
     "//just": "echo this app uses justfile for development tasks"

package/src/completion.ts

@@ -522,7 +522,7 @@ export function completionZshScript(schema: CliCommand): string {
 }
 
 /**
- * Returns a schema suitable for help display, including the reserved `completion` subtree.
+ * Returns a schema suitable for help display, including reserved built-in subtrees.
  * Routing roots get `completion` merged; leaf roots are wrapped as a tiny router.
  */
 export function cliPresentationRoot(root: CliCommand): CliCommand {
@@ -534,15 +534,33 @@ export function cliPresentationRoot(root: CliCommand): CliCommand {
       key: root.key,
       description: root.description,
       options: root.options,
-      commands: [cliBuiltinCompletionGroup(root.key)],
+      commands: presentationBuiltins(root),
     } as CliCommand;
   }
   return {
     ...root,
-    commands: [...(root.commands ?? []), cliBuiltinCompletionGroup(root.key)],
+    commands: [...(root.commands ?? []), ...presentationBuiltins(root)],
   } as CliCommand;
 }
 
+/** Built-in commands shown in help and merged for routing CLIs. */
+function presentationBuiltins(root: CliCommand): CliCommand[] {
+  const cmds: CliCommand[] = [cliBuiltinCompletionGroup(root.key)];
+  if (root.mcpServer !== undefined) {
+    cmds.push(cliBuiltinMcpCommand());
+  }
+  return cmds;
+}
+
+/** Builds the static `mcp` leaf command (merged when `root.mcpServer` is set). */
+export function cliBuiltinMcpCommand(): CliCommand {
+  return {
+    key: "mcp",
+    description: "Run as an MCP server over stdio (for AI agents).",
+    handler: () => {},
+  };
+}
+
 /**
  * Builds the static `completion` / `bash` / `zsh` command subtree (merged into the program root at runtime).
  */