argsbarg 3.3.13 → 3.4.0

package/.private/scratch.md

@@ -1,2 +1,4 @@
 - [x] --schema feature for ai agents
-- [x] opt-out install feature?
+- [x] opt-out install feature?
+- [x] outputSchema
+- [x] mcpb bundle

package/CHANGELOG.md

@@ -7,6 +7,22 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [3.4.0] - 2026-06-22
+
+### Added
+
+- **`hidden`** — boolean on commands and options; omitted from help listings, `docs schema` / `docs api`, shell completions, and MCP `tools/list`, but still parseable and invocable. Direct `-h` on a hidden command still works.
+- **`mcp bundle`** — built-in subcommand when `mcpServer.enabled` (macOS-only v1). Runs `myapp mcp bundle` to pack `dist/<key>.mcpb` from `dist/<key>`. Bare `myapp mcp` still starts the stdio server.
+- **`mcpServer.bundle`** — optional author, icon, and `longDescription` for MCP Bundle metadata.
+- **Leaf `outputSchema`** — optional JSON Schema for structured stdout; exported in `docs schema`, `docs api`, skill `reference.md`, and MCP `tools/list` (stdout not validated at runtime yet). Legacy `mcpTool.outputSchema` still works.
+- **MCP tool descriptions** — leaf `notes` are appended to `tools/list` descriptions (`{argsbarg:program}` resolved).
+
+## [3.3.14] - 2026-06-21
+
+### Changed
+
+- **Generated notes** — deduplicated agent, docs, MCP, and completion help; each topic owns its guidance in one place.
+
 ## [3.3.13] - 2026-06-21
 
 ### Changed
@@ -329,7 +345,9 @@ 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/v3.3.13...HEAD
+[Unreleased]: https://github.com/bdombro/bun-argsbarg/compare/v3.4.0...HEAD
+[3.4.0]: https://github.com/bdombro/bun-argsbarg/releases/tag/v3.4.0
+[3.3.14]: https://github.com/bdombro/bun-argsbarg/releases/tag/v3.3.14
 [3.3.13]: https://github.com/bdombro/bun-argsbarg/releases/tag/v3.3.13
 [3.3.12]: https://github.com/bdombro/bun-argsbarg/releases/tag/v3.3.12
 [3.3.11]: https://github.com/bdombro/bun-argsbarg/releases/tag/v3.3.11

package/docs/bundled-docs.md

@@ -35,7 +35,7 @@ myapp docs readme --save   # write ./docs/readme.md
 myapp docs schema --save   # write ./docs/schema.json
 ```
 
-When `docs` is enabled, top-level `myapp --help` includes a Notes line: `Agents: run \`myapp docs skill\` to learn how to use this app`.
+When `docs` is enabled, top-level `myapp --help` points agents at `myapp docs skill`. The `docs skill` subcommand description recommends `install --skill` for a persisted bundle.
 
 ## Configuration
 

package/docs/cli-program.md

@@ -113,6 +113,25 @@ Many "MCP problems" are schema or handler gaps. Prefer these over escape hatches
 | `requiresEnv: [...]` | Runtime secrets; appended to MCP description and enforced at `tools/call` |
 | `description: "..."` | **Irreducible** MCP limitation (e.g. live tail / `--watch` cannot be streamed on the MCP wire yet) |
 
+### Structured stdout
+
+On **leaf commands**, set `outputSchema` to a JSON Schema describing stdout when the handler emits JSON (typically with `--json`, or via MCP on the headless path):
+
+```typescript
+{
+  key: "lookup",
+  description: "Resolve owner info.",
+  outputSchema: {
+    type: "object",
+    properties: { user: { type: "string" }, path: { type: "string" } },
+    required: ["user", "path"],
+  },
+  handler: (ctx) => { /* ... */ },
+}
+```
+
+Exported in `docs schema`, `docs api`, skill `reference.md`, and MCP `tools/list`. Not validated at runtime yet. Pair with `notes` for prose examples; do not duplicate the full schema in `notes`.
+
 Do **not** use `mcpTool.description` to paper over missing `--yes`, non-standard flag names, or handlers that only work interactively — fix those instead.
 
 If help text and MCP behavior match after your fixes, **omit `mcpTool` entirely**.

package/docs/mcp.md

@@ -103,7 +103,7 @@ Tool names are derived from the command path, with each segment sanitized (non-a
 
 ### Tool descriptions
 
-Each tool’s `description` includes the human CLI path and the leaf’s help text, separated by an em dash. Tool arguments are defined in `inputSchema` (options and positionals with their descriptions). `mcpTool.requiresEnv` is appended as `[requires env: …]`.
+Each tool’s `description` includes the human CLI path and the leaf’s help text, separated by an em dash. Leaf **`notes`** are appended after a blank line (with `{argsbarg:program}` resolved). Tool arguments are defined in `inputSchema` (options and positionals with their descriptions). `mcpTool.requiresEnv` is appended as `[requires env: …]` on auto-generated descriptions.
 
 | CLI path | MCP `description` (example) |
 | --- | --- |
@@ -138,6 +138,8 @@ mcpTool: {
 }
 ```
 
+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 (no automatic `requiresEnv` suffix; mention vars in your text if needed).
 - **`requiresEnv`** — on auto-generated descriptions, appended as `[requires env: …]`. Enforced at `tools/call` time before the handler runs. Empty or unset env values count as missing.
 
@@ -276,7 +278,7 @@ mcpServer: {
 | `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/list` | Lists all tools with `name`, `description`, `inputSchema`, and optional `outputSchema`. |
 | `tools/call` | Runs a leaf handler; params: `name`, `arguments` (object). |
 | `resources/list` | Lists schema + custom resources. |
 | `resources/read` | Returns resource body; params: `uri`. |
@@ -291,11 +293,29 @@ printf '%s\n' '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' | bun
 
 You should get one JSON line on stdout with `result.capabilities` and `result.serverInfo`.
 
+## MCP Bundle (`mcp bundle`)
+
+When `mcpServer.enabled` is true, **`mcp bundle`** packs a Claude Desktop **`.mcpb`** bundle (macOS-only v1):
+
+```bash
+just build
+./dist/myapp mcp bundle
+# → dist/myapp.mcpb
+```
+
+Expects the compiled binary at **`dist/<program.key>`** and writes **`dist/<program.key>.mcpb`**. Manifest metadata is generated from your schema (`mcpServerId`, tools, `requiresEnv`). Optional pack-time fields live under **`mcpServer.bundle`** (`author`, `icon`, `longDescription`).
+
+Bare **`myapp mcp`** still runs the stdio MCP server (unchanged for `install --mcp` and MCP hosts). Use **`install --mcp`** for Cursor / Claude Code JSON config.
+
+## Hidden commands and options
+
+Set **`hidden: true`** on a command or option to omit it from help listings, `docs schema` / `docs api`, shell completions, and MCP `tools/list` / tool `inputSchema`. Hidden commands remain invocable; **`myapp hidden-cmd -h`** still works.
+
 ## Reserved names
 
 When MCP is enabled:
 
-- Do not declare a top-level command named **`completion`** — reserved for shell completions.
+- Do not declare top-level commands named **`completion`** or **`mcp`** — reserved for platform builtins.
 
 Running `myapp mcp` without `mcpServer` on the root fails with an error (exit 1).
 

package/index.d.ts

@@ -69,6 +69,8 @@ export declare enum CliFallbackMode {
 export interface CliOption {
 	/** Option name (e.g., "name", "verbose"). */
 	name: string;
+	/** When `true`, omit from help, schema, completions, and MCP tool inputSchema (still parseable). */
+	hidden?: boolean;
 	/** Description shown in help. */
 	description: string;
 	/** Option kind: presence flag, string value, or number value. */
@@ -104,6 +106,18 @@ export interface CliPositional {
 	 */
 	argMax?: number;
 }
+/** Optional metadata for `mcp bundle` MCP Bundle output (program root `mcpServer.bundle` only). */
+export interface CliMcpBundleConfig {
+	author?: {
+		name: string;
+		email?: string;
+		url?: string;
+	};
+	/** Repo-relative path to a PNG icon copied into the bundle. */
+	icon?: string;
+	/** Manifest `long_description` (defaults to program description). */
+	longDescription?: string;
+}
 /**
  * Enables `myapp mcp` and MCP stdio server metadata (program root only).
  * Must include `enabled: true`; omit `mcpServer` entirely to disable MCP.
@@ -130,6 +144,8 @@ export interface CliMcpServerConfig {
 	 * URIs must be unique and must not equal schemaResourceUri.
 	 */
 	resources?: CliMcpResource[];
+	/** Optional MCP Bundle (`.mcpb`) metadata for `mcp bundle`. */
+	bundle?: CliMcpBundleConfig;
 }
 /**
  * A custom MCP resource exposed under resources/list and resources/read.
@@ -163,6 +179,10 @@ export interface CliMcpToolConfig {
 	 * Empty string counts as absent.
 	 */
 	requiresEnv?: string[];
+	/**
+	 * @deprecated Set `outputSchema` on the leaf command instead.
+	 */
+	outputSchema?: Record<string, unknown>;
 }
 /**
  * Opt-out and defaults for the `install` built-in (program root only).
@@ -222,6 +242,8 @@ export interface CliDocsConfig {
 export interface CliNodeBase {
 	/** Program or command key (e.g., "myapp", "stat", "owner"). */
 	key: string;
+	/** When `true`, omit from help listings, schema, completions, and MCP tools (still invocable). */
+	hidden?: boolean;
 	/** Short description shown in help. */
 	description: string;
 	/** Additional notes shown in help (`{argsbarg:program}` → program key). */
@@ -237,6 +259,11 @@ export type CliLeaf = CliNodeBase & {
 	handler: CliHandler;
 	/** Positional argument definitions. */
 	positionals?: CliPositional[];
+	/**
+	 * JSON Schema for structured stdout (e.g. with `--json` or MCP when the handler emits JSON).
+	 * Exported in `docs schema`, `docs api`, and MCP `tools/list`; not validated at runtime yet.
+	 */
+	outputSchema?: Record<string, unknown>;
 	/** Per-tool MCP exposure and metadata. */
 	mcpTool?: CliMcpToolConfig;
 };
@@ -378,5 +405,25 @@ export declare function createGhVersionCheck(config: GhVersionCheckConfig): {
 };
 /** Shared `gh release view` fetcher for hooks and version-check refresh. */
 export declare function createGhFetchLatest(config: Pick<GhReleaseUpdateConfig, "repo" | "repoEnvHint">): () => Promise<string>;
+/** Resolved paths for `mcp bundle`. */
+export interface McpBundlePaths {
+	binaryPath: string;
+	outPath: string;
+	binaryName: string;
+}
+/** Default `dist/<key>` binary and `dist/<key>.mcpb` output under cwd. */
+export declare function defaultMcpBundlePaths(program: CliProgram, cwd?: string): McpBundlePaths;
+/** Generates MCPB `manifest.json` object from program schema and MCP tools. */
+export declare function generateMcpManifest(program: CliProgram, binaryName: string): Record<string, unknown>;
+export interface PackMcpBundleOpts {
+	cwd?: string;
+	binaryPath?: string;
+	outPath?: string;
+}
+/**
+ * Stages manifest + binary (+ optional icon) and writes a `.mcpb` ZIP.
+ * macOS-only v1; requires the compiled binary to exist.
+ */
+export declare function packMcpBundle(program: CliProgram, opts?: PackMcpBundleOpts): string;
 
 export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "argsbarg",
-  "version": "3.3.13",
+  "version": "3.4.0",
   "type": "module",
   "engines": {
     "bun": ">=1.3"

package/src/builtins/builtins.test.ts

@@ -57,9 +57,14 @@ describe("builtins help copy", () => {
   });
 
   test("mcp builtin description is user-facing", () => {
-    const mcp = cliBuiltinMcpCommand();
+    const withDocs: CliProgram = {
+      ...fixture,
+      docs: { enabled: true, topics: { readme: { text: "# r\n" } } },
+    };
+    const mcp = cliBuiltinMcpCommand(withDocs);
     expect(mcp.description).toContain("MCP server");
-    expect(mcp.notes).toContain('["mcp"]');
+    expect(mcp.notes).toContain("install --mcp --yes");
+    expect(mcp.notes).toContain("docs mcp");
   });
 });
 
@@ -87,7 +92,8 @@ describe("presentation root", () => {
       docs: { enabled: true, topics: { readme: { text: "# r\n" } } },
     };
     const root = cliPresentationRoot(withDocs);
-    expect(root.notes).toContain("Agents: run `myapp docs skill` to learn how to use this app");
+    expect(root.notes).toContain("For AI agents: `myapp docs skill`.");
+    expect(root.notes).not.toContain("install --skill");
   });
 });
 

package/src/builtins/completion-group.ts

@@ -1,10 +1,13 @@
-import { type CliLeaf, type CliNode, type CliRouter } from "../types.ts";
+import { resolveCapabilities } from "../capabilities.ts";
+import { type CliLeaf, type CliProgram, type CliRouter } from "../types.ts";
 
 /**
  * Builds the static `completion` / `bash` / `zsh` / `fish` command subtree (merged into the program root at runtime).
  */
-export function cliBuiltinCompletionGroup(appName: string): CliRouter {
-  return {
+export function cliBuiltinCompletionGroup(program: CliProgram): CliRouter {
+  const appName = program.key;
+  const caps = resolveCapabilities(program);
+  const router: CliRouter = {
     key: "completion",
     description: "Generate the autocompletion script for shells.",
     commands: [
@@ -12,15 +15,10 @@ export function cliBuiltinCompletionGroup(appName: string): CliRouter {
         key: "bash",
         description: "Print a bash tab-completion script.",
         notes:
-          "Output is the whole script.\n" +
-          "Pipe it to a file, or feed it straight into your shell.\n\n" +
-          "To keep it across restarts, save it and source that file from ~/.bashrc.\n\n" +
-          "For example:\n\n" +
-          `echo 'eval \"$(${appName} completion bash)\"' >> ~/.bashrc\n` +
-          `\nor\n` +
+          "Manual install:\n\n" +
           `  ${appName} completion bash > ~/.bash_completion.d/${appName}\n` +
           `  echo 'source ~/.bash_completion.d/${appName}' >> ~/.bashrc\n\n` +
-          "To try it only in this session (nothing written to disk):\n" +
+          "Try this session only:\n\n" +
           `  source <(${appName} completion bash)`,
         handler: () => {},
       },
@@ -28,23 +26,26 @@ export function cliBuiltinCompletionGroup(appName: string): CliRouter {
         key: "zsh",
         description: "Print a zsh tab-completion script.",
         notes:
-          "Output is the whole script.\n\n" +
-          `fpath setup: ${appName} completion zsh > ~/.zsh/completions/_${appName}\n\n` +
-          `source setup: echo 'eval \"$(${appName} completion zsh)\"' >> ~/.zshrc\n\n` +
-          "To try it only in this session (nothing written to disk):\n" +
-          `  eval \"$(${appName} completion zsh)\"`,
+          "Manual install:\n\n" +
+          `  ${appName} completion zsh > ~/.zsh/completions/_${appName}\n\n` +
+          "Ensure ~/.zsh/completions is on your fpath, then restart zsh.\n\n" +
+          "Try this session only:\n\n" +
+          `  eval "$(${appName} completion zsh)"`,
         handler: () => {},
       },
       {
         key: "fish",
         description: "Print a fish tab-completion script.",
         notes:
-          "Output is the whole script.\n\n" +
-          "Install:\n" +
+          "Manual install:\n\n" +
           `  ${appName} completion fish > ~/.config/fish/completions/${appName}.fish\n\n` +
           "Fish loads completions from that directory automatically.",
         handler: () => {},
       },
     ],
   };
+  if (caps.install) {
+    router.notes = `Install for all shells:\n\n  ${appName} install --completions --yes`;
+  }
+  return router;
 }

package/src/builtins/dispatch.ts

@@ -9,6 +9,7 @@ import { cliBuiltinMcpCommand } from "./mcp.ts";
 import { cliBuiltinVersionCommand } from "./version.ts";
 import { cliBuiltinCompletionGroup as completionGroup } from "./completion-group.ts";
 import { cliPresentationRoot } from "./presentation.ts";
+import { runMcpBundle } from "../mcp/bundle.ts";
 import { cliBuiltinDocsGroupIfEnabled } from "../docs/builtin.ts";
 import { cliMcpServeStdio } from "../mcp.ts";
 import { cliInstall } from "../install/index.ts";
@@ -72,12 +73,22 @@ export async function dispatchBuiltin(
       process.stderr.write("MCP is not enabled. Set mcpServer: { enabled: true } on the program root.\n");
       process.exit(1);
     }
-    if (pr.path.length !== 1) {
-      process.stderr.write("Unknown subcommand: mcp " + pr.path.slice(1).join(" ") + "\n");
-      process.exit(1);
+    const sub = pr.path[1];
+    if (pr.path.length === 1 || sub === "serve") {
+      await cliMcpServeStdio(program);
+      process.exit(0);
     }
-    await cliMcpServeStdio(program);
-    process.exit(0);
+    if (pr.path.length === 2 && sub === "bundle") {
+      try {
+        runMcpBundle(program);
+      } catch (err) {
+        process.stderr.write(err instanceof Error ? err.message + "\n" : "mcp bundle failed.\n");
+        process.exit(1);
+      }
+      process.exit(0);
+    }
+    process.stderr.write("Unknown subcommand: mcp " + pr.path.slice(1).join(" ") + "\n");
+    process.exit(1);
   }
 
   if (pr.path[0] === "install") {
@@ -110,7 +121,7 @@ export function builtinInterceptRoot(
       parseRoot: {
         key: program.key,
         description: program.description,
-        commands: [completionGroup(program.key)],
+        commands: [completionGroup(program)],
       },
       isLeafCompletionIntercept: true,
     };
@@ -132,7 +143,7 @@ export function builtinInterceptRoot(
       parseRoot: {
         key: program.key,
         description: program.description,
-        commands: [cliBuiltinMcpCommand()],
+        commands: [cliBuiltinMcpCommand(program)],
       },
       isLeafCompletionIntercept: false,
     };

package/src/builtins/export.ts

@@ -1,5 +1,7 @@
 import { type CliCapabilities, resolveCapabilities } from "../capabilities.ts";
-import type { CliFallbackMode, CliOption, CliPositional, CliProgram } from "../types.ts";
+import type { CliFallbackMode, CliNode, CliOption, CliPositional, CliProgram } from "../types.ts";
+import { isCliRouter } from "../types.ts";
+import { visibleOptions } from "../hidden.ts";
 import { cliBuiltinCompletionGroup } from "./completion-group.ts";
 import { cliBuiltinInstallCommand } from "./install.ts";
 import { cliBuiltinMcpCommand } from "./mcp.ts";
@@ -11,6 +13,8 @@ export interface CliSchemaExport {
   key: string;
   description: string;
   notes?: string;
+  /** JSON Schema for structured stdout when set on the leaf `mcpTool`. */
+  outputSchema?: Record<string, unknown>;
   options?: CliOption[];
   fallbackCommand?: string;
   fallbackMode?: CliFallbackMode;
@@ -18,13 +22,11 @@ export interface CliSchemaExport {
   positionals?: CliPositional[];
 }
 
-function exportBuiltinNode(cmd: {
-  key: string;
-  description: string;
-  notes?: string;
-  options?: CliOption[];
-  commands?: CliSchemaExport[];
-}): CliSchemaExport {
+function exportBuiltinNode(cmd: CliNode): CliSchemaExport | null {
+  if (cmd.hidden) {
+    return null;
+  }
+
   const out: CliSchemaExport = {
     key: cmd.key,
     description: cmd.description,
@@ -32,11 +34,23 @@ function exportBuiltinNode(cmd: {
   if ((cmd.notes ?? "").length > 0) {
     out.notes = cmd.notes;
   }
-  if ((cmd.options ?? []).length > 0) {
-    out.options = cmd.options;
+  const options = visibleOptions(cmd.options);
+  if (options.length > 0) {
+    out.options = options;
   }
-  if ((cmd.commands ?? []).length > 0) {
-    out.commands = (cmd.commands ?? []).map((ch) => exportBuiltinNode(ch));
+  if (isCliRouter(cmd)) {
+    if (cmd.fallbackCommand !== undefined) {
+      out.fallbackCommand = cmd.fallbackCommand;
+    }
+    if (cmd.fallbackMode !== undefined) {
+      out.fallbackMode = cmd.fallbackMode;
+    }
+    const children = cmd.commands
+      .map((ch) => exportBuiltinNode(ch))
+      .filter((ch): ch is CliSchemaExport => ch !== null);
+    if (children.length > 0) {
+      out.commands = children;
+    }
   }
   return out;
 }
@@ -45,18 +59,18 @@ function exportBuiltinNode(cmd: {
 export function exportPresentationBuiltins(program: CliProgram, caps?: CliCapabilities): CliSchemaExport[] {
   const resolved = caps ?? resolveCapabilities(program);
   const builtins: CliSchemaExport[] = [
-    exportBuiltinNode(cliBuiltinCompletionGroup(program.key)),
-    exportBuiltinNode(cliBuiltinVersionCommand()),
+    exportBuiltinNode(cliBuiltinCompletionGroup(program))!,
+    exportBuiltinNode(cliBuiltinVersionCommand())!,
   ];
   if (resolved.install) {
-    builtins.push(exportBuiltinNode(cliBuiltinInstallCommand(program)));
+    builtins.push(exportBuiltinNode(cliBuiltinInstallCommand(program))!);
   }
   const docsGroup = cliBuiltinDocsGroupIfEnabled(program);
   if (docsGroup) {
-    builtins.push(exportBuiltinNode(docsGroup));
+    builtins.push(exportBuiltinNode(docsGroup)!);
   }
   if (resolved.mcp) {
-    builtins.push(exportBuiltinNode(cliBuiltinMcpCommand()));
+    builtins.push(exportBuiltinNode(cliBuiltinMcpCommand(program))!);
   }
   return builtins;
 }

package/src/builtins/index.ts

@@ -4,7 +4,7 @@ export { completionFishScript } from "./completion-fish.ts";
 export { cliBuiltinCompletionGroup } from "./completion-group.ts";
 export { cliBuiltinInstallCommand, installBuiltinOptions } from "./install.ts";
 export { cliBuiltinMcpCommand } from "./mcp.ts";
-export { cliPresentationRoot, presentationBuiltins } from "./presentation.ts";
+export { cliParseRoot, cliPresentationRoot, parseBuiltins, presentationBuiltins } from "./presentation.ts";
 export { exportPresentationBuiltins, type CliSchemaExport } from "./export.ts";
 export { dispatchBuiltin, builtinInterceptRoot } from "./dispatch.ts";
 export { collectScopes, type ScopeRec } from "./scopes.ts";

package/src/builtins/install.ts

@@ -117,7 +117,8 @@ export function cliBuiltinInstallCommand(root: CliProgram): CliLeaf {
     "Remove everything installed with --all:",
     `  ${app} install --uninstall --all --yes`,
     "",
-    "Use --dry to preview changes, --json for machine-readable output.",
+    "Use --dry to preview changes without writing files.",
+    "Use --json for machine-readable output.",
   );
   return {
     key: "install",

package/src/builtins/mcp.ts

@@ -1,13 +1,43 @@
-import { type CliLeaf } from "../types.ts";
+import { resolveCapabilities } from "../capabilities.ts";
+import { docsEnabled } from "../docs/resolve.ts";
+import { type CliLeaf, type CliProgram, type CliRouter, CliFallbackMode } from "../types.ts";
 
-/** Presence options for the top-level `mcp` built-in (leaf). */
-export function cliBuiltinMcpCommand(): CliLeaf {
-  return {
-    key: "mcp",
+/** Built-in `mcp` router: bare `myapp mcp` runs stdio (via hidden `serve` fallback); `mcp bundle` packs `.mcpb`. */
+export function cliBuiltinMcpCommand(program: CliProgram): CliRouter {
+  const caps = resolveCapabilities(program);
+  const lines = [
+    "Stdio MCP server. Add to Cursor or Claude:",
+    "",
+    "  command: {argsbarg:program}",
+    "  args: mcp",
+    "",
+  ];
+  if (caps.install) {
+    lines.push("Or:", "", "  {argsbarg:program} install --mcp --yes", "");
+  }
+  if (docsEnabled(program)) {
+    lines.push("Full setup guide: {argsbarg:program} docs mcp");
+  }
+
+  const serve: CliLeaf = {
+    key: "serve",
+    hidden: true,
     description: "Run as an MCP server over stdio for AI agents.",
-    notes:
-      "Configure MCP clients with `command` set to this program name and `args` set to `[\"mcp\"]`.\n\n" +
-      "See docs/mcp.md for setup details.",
     handler: () => {},
   };
+
+  const bundle: CliLeaf = {
+    key: "bundle",
+    description: "Pack a Claude Desktop MCP Bundle (.mcpb) from dist/<key> (macOS-only v1).",
+    handler: () => {},
+  };
+
+  return {
+    key: "mcp",
+    description: "MCP server and bundle tools.",
+    notes: lines.join("\n"),
+    fallbackCommand: "serve",
+    fallbackMode: CliFallbackMode.MissingOnly,
+    commands: [serve, bundle],
+  };
 }