argsbarg 1.3.1 → 1.4.0

package/src/mcp/server.ts

@@ -0,0 +1,226 @@
+/*
+This module implements the MCP JSON-RPC server over stdio: initialize, tools,
+resources, and ping. Responses are newline-delimited JSON on stdout only.
+*/
+
+import { cliInvoke } from "../invoke.ts";
+import { cliSchemaJson } from "../schema.ts";
+import { CliCommand } from "../types.ts";
+import { buildToolCallSuccess } from "./result.ts";
+import {
+  collectMcpTools,
+  mcpToolCallToArgv,
+  resolveMcpSchemaUri,
+  resolveMcpServerInfo,
+} from "./tools.ts";
+
+const MCP_PROTOCOL_VERSION = "2024-11-05";
+
+/** JSON-RPC request shape from stdin. */
+interface JsonRpcRequest {
+  jsonrpc?: string;
+  id?: string | number | null;
+  method?: string;
+  params?: unknown;
+}
+
+/** Writes a JSON-RPC response line to stdout. */
+function writeResponse(msg: Record<string, unknown>): void {
+  process.stdout.write(JSON.stringify(msg) + "\n");
+}
+
+/** Writes a JSON-RPC error response. */
+function writeError(id: string | number | null | undefined, code: number, message: string): void {
+  if (id === undefined) {
+    return;
+  }
+  writeResponse({
+    jsonrpc: "2.0",
+    id,
+    error: { code, message },
+  });
+}
+
+/** Handles one NDJSON request line. */
+async function handleRequestLine(root: CliCommand, line: string): Promise<void> {
+  let req: JsonRpcRequest;
+  try {
+    req = JSON.parse(line) as JsonRpcRequest;
+  } catch {
+    return;
+  }
+
+  const id = req.id;
+  const hasId = id !== undefined;
+
+  if (req.jsonrpc !== "2.0") {
+    if (hasId) {
+      writeError(id, -32600, "Invalid Request");
+    }
+    return;
+  }
+
+  const method = req.method ?? "";
+  const params = (req.params ?? {}) as Record<string, unknown>;
+
+  if (method === "notifications/initialized") {
+    return;
+  }
+
+  if (!hasId) {
+    return;
+  }
+
+  try {
+    if (method === "initialize") {
+      const info = resolveMcpServerInfo(root);
+      writeResponse({
+        jsonrpc: "2.0",
+        id,
+        result: {
+          protocolVersion: MCP_PROTOCOL_VERSION,
+          capabilities: { tools: {}, resources: {} },
+          serverInfo: { name: info.name, version: info.version },
+        },
+      });
+      return;
+    }
+
+    if (method === "ping") {
+      writeResponse({ jsonrpc: "2.0", id, result: {} });
+      return;
+    }
+
+    if (method === "tools/list") {
+      const tools = collectMcpTools(root).map((t) => ({
+        name: t.name,
+        description: t.description,
+        inputSchema: t.inputSchema,
+      }));
+      writeResponse({ jsonrpc: "2.0", id, result: { tools } });
+      return;
+    }
+
+    if (method === "tools/call") {
+      const name = params.name;
+      if (typeof name !== "string") {
+        writeError(id, -32602, "Invalid params: name required");
+        return;
+      }
+      const rawArgs = params.arguments;
+      if (rawArgs !== undefined && (typeof rawArgs !== "object" || rawArgs === null || Array.isArray(rawArgs))) {
+        writeError(id, -32602, "Invalid params: arguments must be an object");
+        return;
+      }
+      const toolList = collectMcpTools(root);
+      const tool = toolList.find((t) => t.name === name);
+      if (!tool) {
+        writeError(id, -32602, `Unknown tool: ${name}`);
+        return;
+      }
+      const argvResult = mcpToolCallToArgv(root, tool, (rawArgs ?? {}) as Record<string, unknown>);
+      if ("error" in argvResult) {
+        writeResponse({
+          jsonrpc: "2.0",
+          id,
+          result: {
+            content: [{ type: "text", text: argvResult.error }],
+            isError: true,
+          },
+        });
+        return;
+      }
+      const invokeResult = await cliInvoke(root, argvResult);
+      if (invokeResult.kind === "ok" && invokeResult.exitCode === 0) {
+        writeResponse({
+          jsonrpc: "2.0",
+          id,
+          result: buildToolCallSuccess(invokeResult.stdout, invokeResult.stderr),
+        });
+        return;
+      }
+      const errText = invokeResult.stderr.trim() || invokeResult.errorMsg || `Exit code ${invokeResult.exitCode}`;
+      writeResponse({
+        jsonrpc: "2.0",
+        id,
+        result: {
+          content: [{ type: "text", text: errText }],
+          isError: true,
+        },
+      });
+      return;
+    }
+
+    if (method === "resources/list") {
+      const uri = resolveMcpSchemaUri(root);
+      writeResponse({
+        jsonrpc: "2.0",
+        id,
+        result: {
+          resources: [
+            {
+              uri,
+              name: "cli-schema",
+              description: "Full CLI command tree (same as --schema).",
+              mimeType: "application/json",
+            },
+          ],
+        },
+      });
+      return;
+    }
+
+    if (method === "resources/read") {
+      const uri = params.uri;
+      if (typeof uri !== "string") {
+        writeError(id, -32602, "Invalid params: uri required");
+        return;
+      }
+      const expected = resolveMcpSchemaUri(root);
+      if (uri !== expected) {
+        writeError(id, -32602, `Unknown resource: ${uri}`);
+        return;
+      }
+      writeResponse({
+        jsonrpc: "2.0",
+        id,
+        result: {
+          contents: [
+            {
+              uri: expected,
+              mimeType: "application/json",
+              text: cliSchemaJson(root).trimEnd(),
+            },
+          ],
+        },
+      });
+      return;
+    }
+
+    writeError(id, -32601, "Method not found");
+  } catch (err) {
+    const message = err instanceof Error ? err.message : "Internal error";
+    writeError(id, -32603, message);
+  }
+}
+
+/** Runs the MCP NDJSON read loop on stdin until EOF. */
+export async function mcpServeStdioLoop(root: CliCommand): Promise<void> {
+  let buffer = "";
+  for await (const chunk of Bun.stdin.stream()) {
+    buffer += new TextDecoder().decode(chunk);
+    let nl: number;
+    while ((nl = buffer.indexOf("\n")) !== -1) {
+      const line = buffer.slice(0, nl).trim();
+      buffer = buffer.slice(nl + 1);
+      if (line.length === 0) {
+        continue;
+      }
+      await handleRequestLine(root, line);
+    }
+  }
+  const trailing = buffer.trim();
+  if (trailing.length > 0) {
+    await handleRequestLine(root, trailing);
+  }
+}

package/src/mcp/tools.ts

@@ -0,0 +1,209 @@
+/*
+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 { 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 };
+  }
+}
+
+/** 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;
+}
+
+/** 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: mcpToolDescription(path, root.key, cmd.description),
+        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,24 @@
+/*
+This module starts the ArgsBarg MCP stdio server for opt-in program roots.
+*/
+
+import { mcpServeStdioLoop } from "./mcp/server.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 {
+    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,

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);

package/src/types.ts

@@ -78,6 +78,26 @@ 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.
  */
@@ -90,6 +110,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

@@ -13,7 +13,7 @@ import {
   CliSchemaValidationError,
 } from "./types.ts";
 
-const reservedCommandNames = ["completion"];
+const reservedCommandNames = ["completion", "mcp"];
 
 /**
  * Validates the static CliCommand tree against ArgBarg rules.
@@ -50,6 +50,21 @@ 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");
+  }
 
   // Check for duplicate child names
   const seenNames = new Set<string>();