argsbarg 1.3.1 → 1.4.1

package/src/mcp/tools.ts

@@ -0,0 +1,254 @@
+/*
+This module maps CliCommand 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 { CliCommand, CliOption, CliOptionKind, CliPositional } from "../types.ts";
+
+/** Default URI for the CLI schema MCP resource. */
+export const MCP_SCHEMA_URI_DEFAULT = "argsbarg://schema";
+
+/** One MCP tool derived from a leaf CLI command. */
+export interface McpToolDef {
+  /** MCP tool name (underscore-separated path). */
+  name: string;
+  /** Tool description from the leaf command. */
+  description: string;
+  /** Command path segments from the program root. */
+  path: string[];
+  /** Leaf command node. */
+  leaf: CliCommand;
+  /** JSON Schema for tools/call arguments. */
+  inputSchema: Record<string, unknown>;
+}
+
+/** Builds MCP tool description: "{cli path} — {description}". */
+export function mcpToolDescription(path: string[], rootKey: string, description: string): string {
+  const prefix = path.length > 0 ? path.join(" ") : rootKey;
+  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: CliCommand, path: string[]): string {
+  if (path.length === 0) {
+    return sanitizeToolSegment(root.key);
+  }
+  return path.map(sanitizeToolSegment).join("_");
+}
+
+/** JSON Schema property for one option. */
+function optionProperty(opt: CliOption): Record<string, unknown> {
+  const base = { description: opt.description };
+  switch (opt.kind) {
+    case CliOptionKind.Presence:
+      return { type: "boolean", ...base };
+    case CliOptionKind.String:
+      return { type: "string", ...base };
+    case CliOptionKind.Number:
+      return { type: "number", ...base };
+    case CliOptionKind.Enum:
+      return { type: "string", enum: opt.choices, ...base };
+  }
+}
+
+/** JSON Schema property for one positional slot. */
+function positionalProperty(p: CliPositional): Record<string, unknown> {
+  const base = { description: p.description };
+  const { argMax = 1 } = p;
+  if (argMax === 0) {
+    return { type: "array", items: { type: "string" }, ...base };
+  }
+  return { type: "string", ...base };
+}
+
+/** Builds inputSchema for a leaf command. */
+function buildInputSchema(root: CliCommand, path: string[], leaf: CliCommand): Record<string, unknown> {
+  const properties: Record<string, unknown> = {};
+  const required: string[] = [];
+
+  for (const opt of collectOptionDefs(root, path)) {
+    properties[opt.name] = optionProperty(opt);
+    if (opt.required) {
+      required.push(opt.name);
+    }
+  }
+
+  for (const p of leaf.positionals ?? []) {
+    properties[p.name] = positionalProperty(p);
+    const { argMin = 1, argMax = 1 } = p;
+    if (argMax === 1 && argMin >= 1) {
+      required.push(p.name);
+    }
+  }
+
+  const schema: Record<string, unknown> = {
+    type: "object",
+    properties,
+    additionalProperties: false,
+  };
+  if (required.length > 0) {
+    schema.required = required;
+  }
+  return schema;
+}
+
+/** Resolves MCP tool description with optional override and requiresEnv suffix. */
+function resolveToolDescription(root: CliCommand, path: string[], leaf: CliCommand): string {
+  if (leaf.mcpTool?.description) {
+    return leaf.mcpTool.description;
+  }
+  let desc = mcpToolDescription(path, root.key, leaf.description);
+  const env = leaf.mcpTool?.requiresEnv;
+  if (env && env.length > 0) {
+    desc += ` [requires env: ${env.join(", ")}]`;
+  }
+  return desc;
+}
+
+/** One resolved MCP resource (built-in or user-defined). */
+export interface McpResourceEntry {
+  uri: string;
+  name: string;
+  description?: string;
+  mimeType: string;
+  load: () => string;
+}
+
+/** Returns built-in schema resource plus user mcpServer.resources. */
+export function allMcpResources(root: CliCommand): McpResourceEntry[] {
+  const schemaUri = resolveMcpSchemaUri(root);
+  const builtIn: McpResourceEntry = {
+    uri: schemaUri,
+    name: "cli-schema",
+    description: "Full CLI command tree (same as --schema).",
+    mimeType: "application/json",
+    load: () => cliSchemaJson(root),
+  };
+  const user = (root.mcpServer?.resources ?? []).map((r) => ({
+    uri: r.uri,
+    name: r.name,
+    description: r.description,
+    mimeType: r.mimeType ?? "text/plain",
+    load: r.load,
+  }));
+  return [builtIn, ...user];
+}
+
+/** Recursively collects MCP tool definitions from user leaf commands. */
+export function collectMcpTools(root: CliCommand): McpToolDef[] {
+  const out: McpToolDef[] = [];
+
+  /** Walks the command tree and appends leaf tools. */
+  function walk(cmd: CliCommand, path: string[]): void {
+    if ("handler" in cmd && cmd.handler) {
+      if (cmd.key === "completion" || cmd.key === "mcp") {
+        return;
+      }
+      if (cmd.mcpTool?.enabled === false) {
+        return;
+      }
+      out.push({
+        name: mcpToolName(root, path),
+        description: resolveToolDescription(root, path, cmd),
+        path,
+        leaf: cmd,
+        inputSchema: buildInputSchema(root, path, cmd),
+      });
+      return;
+    }
+    for (const ch of cmd.commands ?? []) {
+      walk(ch, [...path, ch.key]);
+    }
+  }
+
+  if ("handler" in root && root.handler) {
+    walk(root, []);
+  } else {
+    for (const ch of root.commands ?? []) {
+      walk(ch, [ch.key]);
+    }
+  }
+
+  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: CliCommand): { name: string; version: string } {
+  return {
+    name: root.mcpServer?.name ?? root.key,
+    version: root.mcpServer?.version ?? resolveMcpVersionFromPackageJson() ?? "0.0.0",
+  };
+}
+
+/** Resolves the schema resource URI for this app. */
+export function resolveMcpSchemaUri(root: CliCommand): string {
+  return root.mcpServer?.schemaResourceUri ?? MCP_SCHEMA_URI_DEFAULT;
+}
+
+/** Converts flat MCP tool arguments to argv for cliInvoke. */
+export function mcpToolCallToArgv(
+  root: CliCommand,
+  tool: McpToolDef,
+  args: Record<string, unknown>,
+): string[] | { error: string } {
+  const argv = [...tool.path];
+
+  for (const opt of collectOptionDefs(root, tool.path)) {
+    const val = args[opt.name];
+    if (val === undefined) {
+      continue;
+    }
+    if (opt.kind === CliOptionKind.Presence) {
+      if (val === true) {
+        argv.push(`--${opt.name}`);
+      }
+      continue;
+    }
+    argv.push(`--${opt.name}`, String(val));
+  }
+
+  for (const p of tool.leaf.positionals ?? []) {
+    const val = args[p.name];
+    const { argMin = 1, argMax = 1 } = p;
+
+    if (argMax === 0) {
+      if (!Array.isArray(val)) {
+        return { error: `Missing argument: ${p.name}` };
+      }
+      for (const item of val) {
+        argv.push(String(item));
+      }
+      continue;
+    }
+
+    if (val === undefined) {
+      if (argMin >= 1) {
+        return { error: `Missing argument: ${p.name}` };
+      }
+      continue;
+    }
+    argv.push(String(val));
+  }
+
+  return argv;
+}

package/src/mcp.ts

@@ -0,0 +1,28 @@
+/*
+This module starts the ArgsBarg MCP stdio server for opt-in program roots.
+*/
+
+import { mcpServeStdioLoop } from "./mcp/server.ts";
+import { bootstrapMcpEnv } from "./mcp/env.ts";
+import { CliCommand } from "./types.ts";
+
+/**
+ * Runs the MCP JSON-RPC server on stdin/stdout until stdin closes, then exits.
+ * Caller must ensure `root.mcpServer` is set.
+ */
+export async function cliMcpServeStdio(root: CliCommand): Promise<never> {
+  try {
+    if (root.mcpServer) {
+      bootstrapMcpEnv(root.mcpServer);
+    }
+    await mcpServeStdioLoop(root);
+    process.exit(0);
+  } catch (err) {
+    if (err instanceof Error) {
+      process.stderr.write(err.message + "\n");
+    } else {
+      process.stderr.write("MCP server error.\n");
+    }
+    process.exit(1);
+  }
+}

package/src/parse.ts

@@ -217,7 +217,7 @@ function consumeOptions(
 // ── Positional Collection ─────────────────────────────────────────────────────
 
 /** Merges option defs from the program root along the routed command path. */
-function collectOptionDefs(root: CliCommand, path: string[]): CliOption[] {
+export function collectOptionDefs(root: CliCommand, path: string[]): CliOption[] {
   let defs = [...(root.options ?? [])];
   let cmds = root.commands ?? [];
 
@@ -458,7 +458,7 @@ export function parse(root: CliCommand, argv: string[]): ParseResult {
   // Walk the command tree
   while (true) {
     if (!forcePositionals) {
-      const orep = consumeOptions(current.options ?? [], false, argv, i, opts);
+      const orep = consumeOptions(collectOptionDefs(root, path), false, argv, i, opts);
       if (orep.report.err) {
         return {
           kind: ParseKind.Error,
@@ -601,6 +601,21 @@ export function postParseValidate(root: CliCommand, pr: ParseResult): ParseResul
         };
       }
     }
+    if (d.kind === CliOptionKind.Enum) {
+      const choices = d.choices ?? [];
+      if (!choices.includes(v)) {
+        return {
+          kind: ParseKind.Error,
+          path: pr.path,
+          opts: {},
+          args: [],
+          helpExplicit: false,
+          helpPath: [],
+          errorMsg: `Option --${k}: '${v}' is not one of: ${choices.join(", ")}`,
+          errorHelpPath: pr.path,
+        };
+      }
+    }
   }
 
   return pr;

package/src/runtime.ts

@@ -7,9 +7,10 @@ It keeps execution flow out of the public barrel so the exported API stays small
 the runtime responsibilities remain easy to reason about.
 */
 
-import { cliBuiltinCompletionGroup, cliPresentationRoot, completionBashScript, completionZshScript } from "./completion.ts";
+import { cliBuiltinCompletionGroup, cliBuiltinMcpCommand, cliPresentationRoot, completionBashScript, completionZshScript } from "./completion.ts";
 import { CliContext } from "./context.ts";
 import { cliHelpRender } from "./help.ts";
+import { cliMcpServeStdio } from "./mcp.ts";
 import { parse, postParseValidate, ParseKind } from "./parse.ts";
 import { cliSchemaJson } from "./schema.ts";
 import { CliCommand } from "./types.ts";
@@ -46,6 +47,11 @@ export async function cliRun(root: CliCommand, argv: string[] = process.argv.sli
   let parseRoot = root;
   let isLeafCompletionIntercept = false;
 
+  if (root.handler && argv.length >= 1 && argv[0] === "mcp" && !root.mcpServer) {
+    process.stderr.write("Unknown command: mcp\n");
+    process.exit(1);
+  }
+
   // Intercept completion for Leaf roots (since they can't natively have a completion subcommand)
   // but wrap them in a dummy router so that the parser handles `-h` and errors correctly.
   if (root.handler && argv.length >= 1 && argv[0] === "completion") {
@@ -55,6 +61,12 @@ export async function cliRun(root: CliCommand, argv: string[] = process.argv.sli
       description: root.description,
       commands: [cliBuiltinCompletionGroup(root.key)],
     } as any;
+  } else if (root.handler && argv.length >= 1 && argv[0] === "mcp" && root.mcpServer) {
+    parseRoot = {
+      key: root.key,
+      description: root.description,
+      commands: [cliBuiltinMcpCommand()],
+    } as CliCommand;
   } else {
     parseRoot = cliRootMergedWithBuiltins(root);
   }
@@ -97,6 +109,18 @@ export async function cliRun(root: CliCommand, argv: string[] = process.argv.sli
     }
   }
 
+  if (pr.path[0] === "mcp") {
+    if (!root.mcpServer) {
+      process.stderr.write("Internal error: mcp not enabled.\n");
+      process.exit(1);
+    }
+    if (pr.path.length !== 1) {
+      process.stderr.write("Unknown subcommand: mcp " + pr.path.slice(1).join(" ") + "\n");
+      process.exit(1);
+    }
+    await cliMcpServeStdio(root);
+  }
+
   let current = parseRoot;
   for (const seg of pr.path) {
     const ch = (current.commands ?? []).find((candidate: CliCommand) => candidate.key === seg);
@@ -112,7 +136,7 @@ export async function cliRun(root: CliCommand, argv: string[] = process.argv.sli
     process.exit(1);
   }
 
-  const ctx = new CliContext(parseRoot.key, pr.path, pr.args, pr.opts, parseRoot);
+  const ctx = new CliContext(parseRoot.key, pr.path, pr.args, pr.opts, parseRoot, "cli");
   try {
     await Promise.resolve(current.handler(ctx));
     process.exit(0);

package/src/types.ts

@@ -9,7 +9,12 @@ It gives the package one shared model for both library users and internal module
 import type { CliContext } from "./context.ts";
 
 /**
- * Option kinds: presence (boolean flag), string (free-form text), or number (strict double).
+ * How a leaf handler was dispatched.
+ */
+export type CliInvocation = "cli" | "mcp";
+
+/**
+ * Option kinds: presence (boolean flag), string (free-form text), number (strict double), or enum (fixed choices).
  */
 export enum CliOptionKind {
   /** Boolean flag: no value token (may be implicit `"1"` when set). */
@@ -18,6 +23,8 @@ export enum CliOptionKind {
   String = "string",
   /** Strict floating-point value (parsed at validation time). */
   Number = "number",
+  /** Fixed set of allowed string values. Requires non-empty `choices` on the option. */
+  Enum = "enum",
 }
 
 /**
@@ -54,6 +61,11 @@ export interface CliOption {
   shortName?: string;
   /** Whether this option must be provided. Cannot be used with Presence kind. */
   required?: boolean;
+  /**
+   * Allowed values. Required when kind === Enum; ignored otherwise.
+   * Must be a non-empty array of distinct non-empty strings.
+   */
+  choices?: string[];
 }
 
 /**
@@ -78,6 +90,70 @@ 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;
+  /**
+   * Capture the user's login shell environment at MCP server start and merge it
+   * into process.env. Solves missing PATH, nvm/rbenv shims, Homebrew binaries,
+   * and shell exports that MCP hosts (e.g. Cursor) don't inherit.
+   */
+  shellEnv?: boolean | string;
+  /**
+   * Path to a .env file loaded into process.env at MCP server start, after shellEnv.
+   * Supports `~` expansion. Warns on stderr if the file does not exist.
+   * Always overwrites — envFile is authoritative for its keys.
+   */
+  envFile?: string;
+  /**
+   * Custom MCP resources exposed alongside the built-in argsbarg://schema resource.
+   * URIs must be unique and must not equal schemaResourceUri.
+   */
+  resources?: CliMcpResource[];
+}
+
+/**
+ * A custom MCP resource exposed under resources/list and resources/read.
+ */
+export interface CliMcpResource {
+  /** Resource URI (must be unique; must not equal schemaResourceUri). */
+  uri: string;
+  /** Short display name for resources/list. */
+  name: string;
+  /** Optional human description for resources/list. */
+  description?: string;
+  /** MIME type (default: "text/plain"). */
+  mimeType?: string;
+  /** Called at resources/read time; must return the resource body. */
+  load: () => 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;
+  /**
+   * Override the generated MCP tool description.
+   * Default: auto-generated from command path and description.
+   */
+  description?: string;
+  /**
+   * Environment variable names required at runtime.
+   * Appended to auto-generated MCP tool descriptions; enforced at tools/call time.
+   * Empty string counts as absent.
+   */
+  requiresEnv?: string[];
+}
+
 /**
  * Base properties shared by all command nodes.
  */
@@ -90,6 +166,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;
 }
 
 /**

package/src/validate.ts

@@ -12,8 +12,9 @@ import {
   CliOptionKind,
   CliSchemaValidationError,
 } from "./types.ts";
+import { MCP_SCHEMA_URI_DEFAULT } from "./mcp/tools.ts";
 
-const reservedCommandNames = ["completion"];
+const reservedCommandNames = ["completion", "mcp"];
 
 /**
  * Validates the static CliCommand tree against ArgBarg rules.
@@ -50,6 +51,34 @@ function walkCommand(cmd: CliCommand, isRoot: boolean = false): void {
     );
   }
 
+  if (!isRoot && cmd.mcpServer !== undefined) {
+    throw new CliSchemaValidationError(
+      "mcpServer is only supported on the program root (not on " + cmd.key + ")",
+    );
+  }
+
+  const isLeaf = "handler" in cmd && !!cmd.handler;
+  if (!isLeaf && cmd.mcpTool !== undefined) {
+    throw new CliSchemaValidationError(
+      "mcpTool is only supported on leaf commands (not on " + cmd.key + ")",
+    );
+  }
+  if (isRoot && cmd.mcpTool !== undefined) {
+    throw new CliSchemaValidationError("mcpTool is only supported on leaf commands");
+  }
+
+  if (isRoot && cmd.mcpServer?.resources) {
+    const schemaUri = cmd.mcpServer.schemaResourceUri ?? MCP_SCHEMA_URI_DEFAULT;
+    const uris = cmd.mcpServer.resources.map((r) => r.uri);
+    if (uris.includes(schemaUri)) {
+      throw new CliSchemaValidationError(
+        `mcpServer.resources URI '${schemaUri}' conflicts with the built-in schema resource`,
+      );
+    }
+    if (new Set(uris).size !== uris.length) {
+      throw new CliSchemaValidationError("mcpServer.resources URIs must be unique");
+    }
+  }
 
   // Check for duplicate child names
   const seenNames = new Set<string>();
@@ -88,6 +117,30 @@ function walkCommand(cmd: CliCommand, isRoot: boolean = false): void {
       }
       seenShorts.add(opt.shortName);
     }
+
+    if (opt.kind === CliOptionKind.Enum) {
+      if (!opt.choices || opt.choices.length === 0) {
+        throw new CliSchemaValidationError(
+          `Option '${opt.name}' on '${cmd.key}': Enum kind requires non-empty choices`,
+        );
+      }
+      if (new Set(opt.choices).size !== opt.choices.length) {
+        throw new CliSchemaValidationError(
+          `Option '${opt.name}' on '${cmd.key}': Enum choices must be distinct`,
+        );
+      }
+      for (const choice of opt.choices) {
+        if (choice.length === 0) {
+          throw new CliSchemaValidationError(
+            `Option '${opt.name}' on '${cmd.key}': Enum choices must be non-empty strings`,
+          );
+        }
+      }
+    } else if (opt.choices !== undefined) {
+      throw new CliSchemaValidationError(
+        `Option '${opt.name}' on '${cmd.key}': choices is only valid for Enum kind`,
+      );
+    }
   }
 
   // Validate positionals