argsbarg 2.1.1 → 3.0.0

package/src/install/index.ts

@@ -1,4 +1,5 @@
 import { readSync } from "node:fs";
+import { resolveCapabilities } from "../capabilities.ts";
 import { CliProgram } from "../types.ts";
 import { cliSkillInstall } from "../skill/install.ts";
 import { checkMcpConflict, expectedMcpEntry } from "./mcp-config.ts";
@@ -130,7 +131,7 @@ export async function cliInstall(root: CliProgram, rawOpts: Record<string, strin
   }
 
   // MCP conflict checks before planning
-  if (!opts.uninstall && root.mcpServer && (opts.all || opts.mcp)) {
+  if (!opts.uninstall && resolveCapabilities(root).mcp && (opts.all || opts.mcp)) {
     const entry = expectedMcpEntry(root);
     const yes = !!opts.yes;
     for (const p of [paths.cursorMcpPath, paths.claudeMcpPath]) {

package/src/install/install.test.ts

@@ -11,8 +11,9 @@ import { parseInstallOpts } from "./index.ts";
 
 const fixture: CliProgram = {
   key: "testapp",
+  version: "0.0.0",
   description: "Test",
-  mcpServer: { name: "testapp" },
+  mcpServer: { enabled: true },
   handler: () => {},
 };
 

package/src/install/paths.ts

@@ -1,7 +1,7 @@
 import { homedir } from "node:os";
 import { join } from "node:path";
 import { CliProgram } from "../types.ts";
-import { sanitizeToolSegment } from "../mcp/tools.ts";
+import { sanitizeToolSegment, mcpServerId } from "../mcp/tools.ts";
 
 export interface InstallPaths {
   bindir: string;
@@ -63,7 +63,7 @@ export function resolveInstallPaths(root: CliProgram, opts: { prefix?: string })
     claudeMcpPath: join(home, ".claude.json"),
     bashRc: join(home, ".bashrc"),
     zshRc: join(home, ".zshrc"),
-    mcpName: root.mcpServer?.name ?? root.key,
+    mcpName: mcpServerId(root),
     skillDirName,
   };
 }

package/src/install/plan.ts

@@ -1,5 +1,6 @@
 import { existsSync } from "node:fs";
 import { join } from "node:path";
+import { resolveCapabilities } from "../capabilities.ts";
 import { CliProgram } from "../types.ts";
 import { installBinary } from "./binary.ts";
 import { installCompletions } from "./completions.ts";
@@ -46,7 +47,7 @@ function wantsSkill(opts: InstallOpts): boolean {
 }
 
 function wantsMcp(opts: InstallOpts, root: CliProgram): boolean {
-  return !!(opts.all || opts.mcp) && root.mcpServer !== undefined;
+  return !!(opts.mcp || opts.all) && resolveCapabilities(root).mcp;
 }
 
 /** Builds install actions for normal mode (--all / scoped targets). */
@@ -154,7 +155,7 @@ export function buildUpdatePlan(root: CliProgram, paths: InstallPaths, opts: Ins
     bin: true,
     completions: detected.bashCompletion || detected.zshCompletion || detected.fishCompletion,
     skill: detected.cursorSkill || detected.claudeSkill,
-    mcp: (detected.cursorMcp || detected.claudeMcp) && root.mcpServer !== undefined,
+    mcp: (detected.cursorMcp || detected.claudeMcp) && resolveCapabilities(root).mcp,
     dry: opts.dry,
   };
   const plan = buildInstallPlan(root, paths, scoped);

package/src/install/uninstall.ts

@@ -1,5 +1,6 @@
 import { existsSync, rmSync } from "node:fs";
 import { join } from "node:path";
+import { resolveCapabilities } from "../capabilities.ts";
 import { CliProgram } from "../types.ts";
 import { uninstallBinary } from "./binary.ts";
 import { uninstallCompletions } from "./completions.ts";
@@ -77,7 +78,7 @@ export function buildUninstallPlan(
     });
   }
 
-  if ((all || opts.mcp) && root.mcpServer !== undefined) {
+  if ((all || opts.mcp) && resolveCapabilities(root).mcp) {
     if (detected.cursorMcp) {
       actions.push({
         summary: `cursor mcp: ${paths.cursorMcpPath}`,

package/src/invoke.ts

@@ -82,7 +82,7 @@ export async function cliInvoke(root: CliProgram, argv: string[]): Promise<CliIn
     };
   }
 
-  let current: CliProgram = root;
+  let current: CliNode = root;
   for (const seg of pr.path) {
     if (!isCliRouter(current)) {
       return {

package/src/mcp/tools.ts

@@ -3,14 +3,24 @@ This module maps CliProgram leaf nodes to MCP tool definitions and converts
 flat JSON tool arguments into argv for cliInvoke.
 */
 
-import { readFileSync } from "node:fs";
-import { join } from "node:path";
 import { collectOptionDefs } from "../parse.ts";
 import { cliSchemaJson } from "../schema.ts";
 import { CliProgram, CliLeaf, CliNode, CliOption, CliOptionKind, CliPositional, isCliLeaf, isCliRouter } from "../types.ts";
 
-/** Default URI for the CLI schema MCP resource. */
-export const MCP_SCHEMA_URI_DEFAULT = "argsbarg://schema";
+/** Default URI pattern for the CLI schema MCP resource (`<mcpId>://schema`). */
+export function defaultMcpSchemaUri(mcpId: string): string {
+  return `${mcpId}://schema`;
+}
+
+/** Sanitizes a command key segment for MCP tool names and server identity. */
+export function sanitizeToolSegment(key: string): string {
+  return key.replace(/[^a-zA-Z0-9]/g, "_");
+}
+
+/** MCP server id derived from the program root key (sanitized). */
+export function mcpServerId(root: CliProgram): string {
+  return sanitizeToolSegment(root.key);
+}
 
 /** One MCP tool derived from a leaf CLI command. */
 export interface McpToolDef {
@@ -32,11 +42,6 @@ export function mcpToolDescription(path: string[], rootKey: string, description:
   return `${prefix} — ${description}`;
 }
 
-/** Sanitizes a command key segment for MCP tool names. */
-export function sanitizeToolSegment(key: string): string {
-  return key.replace(/[^a-zA-Z0-9]/g, "_");
-}
-
 /** Builds the MCP tool name for a leaf at the given path. */
 export function mcpToolName(root: CliProgram, path: string[]): string {
   if (path.length === 0) {
@@ -150,7 +155,7 @@ export function collectMcpTools(root: CliProgram): McpToolDef[] {
   /** Walks the command tree and appends leaf tools. */
   function walk(cmd: CliNode, path: string[]): void {
     if (isCliLeaf(cmd)) {
-      if (cmd.key === "completion" || cmd.key === "install" || cmd.key === "mcp") {
+      if (cmd.key === "completion" || cmd.key === "install" || cmd.key === "mcp" || cmd.key === "version") {
         return;
       }
       if (cmd.mcpTool?.enabled === false) {
@@ -181,28 +186,20 @@ export function collectMcpTools(root: CliProgram): McpToolDef[] {
   return out;
 }
 
-/** Reads package.json version from cwd synchronously. */
-function resolveMcpVersionFromPackageJson(): string | undefined {
-  try {
-    const text = readFileSync(join(process.cwd(), "package.json"), "utf8");
-    const version = (JSON.parse(text) as { version?: string }).version;
-    return typeof version === "string" ? version : undefined;
-  } catch {
-    return undefined;
-  }
-}
-
 /** Resolves MCP server name and version for initialize. */
 export function resolveMcpServerInfo(root: CliProgram): { name: string; version: string } {
   return {
-    name: root.mcpServer?.name ?? root.key,
-    version: root.mcpServer?.version ?? resolveMcpVersionFromPackageJson() ?? "0.0.0",
+    name: mcpServerId(root),
+    version: root.version,
   };
 }
 
 /** Resolves the schema resource URI for this app. */
 export function resolveMcpSchemaUri(root: CliProgram): string {
-  return root.mcpServer?.schemaResourceUri ?? MCP_SCHEMA_URI_DEFAULT;
+  if (root.mcpServer?.schemaResourceUri) {
+    return root.mcpServer.schemaResourceUri;
+  }
+  return defaultMcpSchemaUri(mcpServerId(root));
 }
 
 /** Converts flat MCP tool arguments to argv for cliInvoke. */

package/src/runtime.ts

@@ -32,7 +32,7 @@ export async function cliRun(program: CliProgram, argv: string[] = process.argv.
   const caps = resolveCapabilities(program);
 
   if (argv.length >= 1 && argv[0] === "mcp" && !caps.mcp) {
-    process.stderr.write("MCP is not enabled. Set mcpServer on the program root.\n");
+    process.stderr.write("MCP is not enabled. Set mcpServer: { enabled: true } on the program root.\n");
     process.exit(1);
   }
 

package/src/skill/generate.ts

@@ -4,7 +4,7 @@ This module generates Agent Skills content (SKILL.md + reference.md) from a CLI
 
 import { collectOptionDefs } from "../parse.ts";
 import { cliSchemaJson } from "../schema.ts";
-import { collectMcpTools, sanitizeToolSegment } from "../mcp/tools.ts";
+import { collectMcpTools, mcpServerId, sanitizeToolSegment } from "../mcp/tools.ts";
 import { CliProgram, CliOptionKind } from "../types.ts";
 
 export type SkillTarget = "cursor" | "claude";
@@ -75,7 +75,7 @@ function buildSkillMd(root: CliProgram, target: SkillTarget, dirName: string): s
     "",
   ];
 
-  if (root.mcpServer !== undefined) {
+  if (root.mcpServer?.enabled === true) {
     lines.push(
       "**Prefer MCP** when a host has the server connected:",
       "",
@@ -89,7 +89,7 @@ function buildSkillMd(root: CliProgram, target: SkillTarget, dirName: string): s
       JSON.stringify(
         {
           mcpServers: {
-            [root.mcpServer.name ?? root.key]: {
+            [mcpServerId(root)]: {
               command: root.key,
               args: ["mcp"],
             },

package/src/types.test.ts

@@ -18,8 +18,9 @@ const _leafOnly: CliLeaf = {
 
 const _program: CliProgram = {
   key: "app",
+  version: "0.0.0",
   description: "",
-  mcpServer: {},
+  mcpServer: { enabled: true },
   commands: [],
 };
 
@@ -27,7 +28,7 @@ const _badMcpOnNode = {
   key: "x",
   description: "",
   // @ts-expect-error mcpServer is program-root only
-  mcpServer: {},
+  mcpServer: { enabled: true },
   commands: [],
 } satisfies CliNode;
 

package/src/types.ts

@@ -89,13 +89,12 @@ export interface CliPositional {
 
 /**
  * Enables `myapp mcp` and MCP stdio server metadata (program root only).
+ * Must include `enabled: true`; omit `mcpServer` entirely to disable MCP.
  */
 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"`). */
+  /** When `true`, enables the `mcp` built-in and MCP stdio server. */
+  enabled: boolean;
+  /** Resource URI for schema export (default: `<sanitized root key>://schema`). */
   schemaResourceUri?: string;
   /**
    * Capture the user's login shell environment at MCP server start and merge it
@@ -110,7 +109,7 @@ export interface CliMcpServerConfig {
    */
   envFile?: string;
   /**
-   * Custom MCP resources exposed alongside the built-in argsbarg://schema resource.
+   * Custom MCP resources exposed alongside the built-in schema resource.
    * URIs must be unique and must not equal schemaResourceUri.
    */
   resources?: CliMcpResource[];
@@ -209,7 +208,9 @@ export type CliNode = CliLeaf | CliRouter;
  * May be a leaf or router, plus optional program-level MCP and install config.
  */
 export type CliProgram = CliNode & {
-  /** When set, enables the `mcp` built-in subcommand. */
+  /** Program version (printed by the `version` built-in and MCP serverInfo). */
+  version: string;
+  /** When set with `enabled: true`, enables the `mcp` built-in subcommand. */
   mcpServer?: CliMcpServerConfig;
   /** Opt-out and defaults for `install`. */
   install?: CliInstallConfig;

package/src/validate.ts

@@ -12,10 +12,20 @@ import {
   isCliLeaf,
   isCliRouter,
 } from "./types.ts";
-import { MCP_SCHEMA_URI_DEFAULT } from "./mcp/tools.ts";
+import { resolveMcpSchemaUri } from "./mcp/tools.ts";
 
 /** Validates a program schema. */
 export function cliValidateProgram(program: CliProgram): void {
+  if (!program.version || program.version.trim().length === 0) {
+    throw new CliSchemaValidationError("CliProgram.version is required");
+  }
+
+  if (program.mcpServer !== undefined && program.mcpServer.enabled !== true) {
+    throw new CliSchemaValidationError(
+      "mcpServer requires enabled: true; omit mcpServer to disable MCP",
+    );
+  }
+
   const caps = resolveCapabilities(program);
   const reserved = reservedCommandNames(caps);
 
@@ -58,8 +68,8 @@ function walkNode(node: CliNode, program: CliProgram, isRoot: boolean): void {
     }
   }
 
-  if (isRoot && program.mcpServer?.resources) {
-    const schemaUri = program.mcpServer.schemaResourceUri ?? MCP_SCHEMA_URI_DEFAULT;
+  if (isRoot && program.mcpServer?.enabled === true && program.mcpServer.resources) {
+    const schemaUri = resolveMcpSchemaUri(program);
     const uris = program.mcpServer.resources.map((r) => r.uri);
     if (uris.includes(schemaUri)) {
       throw new CliSchemaValidationError(