argsbarg 5.1.16 → 6.0.0

package/src/docs/http-guide.ts

@@ -0,0 +1,132 @@
+import { resolveApiListenAddress } from "../api/server.ts";
+import { defaultConfigEntryTitle } from "../config/entry.ts";
+import { displayAppConfigPath } from "../config/file.ts";
+import { collectMcpTools, type McpToolDef } from "../mcp/tools.ts";
+import { collectOptionDefs } from "../parse.ts";
+import { CliOptionKind, type CliProgram } from "../types.ts";
+
+/** Formats one exposed tool for the auto-generated HTTP guide. */
+function formatToolLine(root: CliProgram, tool: McpToolDef): string {
+  const cliPath = tool.path.length > 0 ? `${root.key} ${tool.path.join(" ")}` : root.key;
+  let line = `- \`${tool.apiName}\` (MCP: \`${tool.name}\`, CLI: \`${cliPath}\`) — ${tool.description}`;
+  const opts = collectOptionDefs(root, tool.path);
+  const flags = opts.filter((o) => o.kind === CliOptionKind.Presence).map((o) => `--${o.name}`);
+  if (flags.length > 0) {
+    line += ` (flags: ${flags.join(", ")})`;
+  }
+  return line;
+}
+
+/** Generates the auto `docs http` markdown guide from schema and API config. */
+export function generateHttpGuide(root: CliProgram): string {
+  const api = root.apiServer;
+  if (!api) {
+    throw new Error("HTTP API server not enabled");
+  }
+
+  const tools = collectMcpTools(root);
+  const { hostname, port } = resolveApiListenAddress(root);
+  const baseUrl = `http://${hostname}:${port}`;
+
+  const lines: string[] = [
+    `# HTTP API (${root.key})`,
+    "",
+    `${root.key} exposes the same callable tools over HTTP as MCP.`,
+    "",
+    "## Running",
+    "",
+    "```bash",
+    `${root.key} api`,
+    "```",
+    "",
+    `Listens on **${baseUrl}** by default (\`apiServer.host\` / \`apiServer.port\`).`,
+    "",
+    "Bind is localhost-only in v0 — use a reverse proxy for remote access.",
+    "",
+    "## Endpoints",
+    "",
+    "| Method | Path | Purpose |",
+    "| --- | --- | --- |",
+    "| `GET` | `/health` | Liveness check |",
+    "| `GET` | `/openapi.json` | OpenAPI 3.1 document (tool paths and request shapes) |",
+    "| `GET` | `/openapi-browser` | Interactive Scalar API reference |",
+    "| `POST` | `/tools/:name` | Invoke with flat JSON args object in the body |",
+    "| `OPTIONS` | `*` | CORS preflight |",
+    "",
+    "Replace `{tool-key}` below with a path segment from `openapi.json` (`paths` keys are `/tools/{tool-key}`). Match body keys to that tool's `requestBody` schema in the spec.",
+    "",
+    "## Examples",
+    "",
+    "```bash",
+    `curl -s ${baseUrl}/health`,
+    `curl -s ${baseUrl}/openapi.json`,
+    `curl -s -X POST ${baseUrl}/tools/{tool-key} \\`,
+    '  -H "content-type: application/json" \\',
+    "  -d '{...}'",
+    "```",
+    "",
+    "## Responses",
+    "",
+    "Success (`200`): raw response body (JSON object, string, or binary). No `{ ok, stdout }` envelope.",
+    "",
+    "Handlers must use `ctx.respond()` or return a value for API/MCP tool calls.",
+    "",
+    'Errors use `{ "error": "..." }` with `400`, `404`, `503`, or `500`.',
+    "",
+  ];
+
+  if (root.appConfig?.entries && Object.keys(root.appConfig.entries).length > 0) {
+    lines.push("## Configuration", "");
+    lines.push(
+      `Configure before first use: \`${root.key} configure\`.`,
+      "",
+      `Default config file: \`${displayAppConfigPath(root)}\`.`,
+      "",
+    );
+    for (const [key, entry] of Object.entries(root.appConfig.entries)) {
+      const label = entry.title ?? defaultConfigEntryTitle(key);
+      const req = entry.required === false ? "optional" : "required";
+      const envNote = entry.env ? ` → env \`${entry.env}\`` : "";
+      lines.push(`- **${label}** (\`${key}\`, ${req}${envNote}) — ${entry.description}`);
+    }
+    lines.push("");
+  }
+
+  lines.push("## Exposed tools", "");
+
+  if (tools.length === 0) {
+    lines.push("(No tools exposed.)", "");
+  } else {
+    for (const tool of tools) {
+      lines.push(formatToolLine(root, tool));
+    }
+    lines.push("");
+  }
+
+  lines.push(
+    "## Tool arguments",
+    "",
+    "POST bodies are a flat JSON object keyed by long option and positional names (hyphenated option names are valid keys).",
+    "",
+    `For HTTP clients, use **\`GET /openapi.json\`** (or **\`GET /openapi-browser\`**) for per-tool request shapes — each \`POST /tools/{name}\` path has a \`requestBody\` schema.`,
+    "",
+    "Varargs positionals accept a JSON array of strings (not a comma-separated string).",
+    "Options with `format: comma-list` accept a comma-separated string or JSON array.",
+    "Options with a schema `default` are applied when omitted.",
+    "",
+    `Shell invocation reference: \`${root.key} docs api\`. Full CLI tree JSON: \`${root.key} docs cli-schema\`.`,
+    "",
+    "## OpenAPI",
+    "",
+    "The HTTP API is described in OpenAPI 3.1.",
+    "",
+    `- **Browse** — [${baseUrl}/openapi-browser](${baseUrl}/openapi-browser) (Scalar UI; loads \`/openapi.json\`)`,
+    `- **Fetch** — \`curl -s ${baseUrl}/openapi.json\``,
+    `- **Save offline** — \`${root.key} docs openapi --save\` → \`./docs/openapi.json\` (or \`just docgen\` in app repos)`,
+    "",
+    "Use the spec to discover tool names (`paths`) and request/response shapes before calling `POST /tools/:name`.",
+    "",
+  );
+
+  return lines.join("\n");
+}

package/src/docs/mcp-guide.ts

@@ -202,7 +202,7 @@ export function generateMcpGuide(root: CliProgram): string {
     "|-----------|---------|",
     "| `tools/list` | Callable tools for exposed leaf commands |",
     "| `tools/call` | Runs handlers headlessly; JSON stdout becomes `structuredContent` when valid |",
-    `| Schema resource | \`${schemaUri}\` — same JSON as \`${root.key} docs schema\` |`,
+    `| Schema resource | \`${schemaUri}\` — same JSON as \`${root.key} docs cli-schema\` |`,
   );
   if (docsEnabled(root)) {
     const docs = root.docs;
@@ -228,7 +228,7 @@ export function generateMcpGuide(root: CliProgram): string {
     "## Tool arguments",
     "",
     "Arguments are a flat JSON object keyed by long option and positional names (hyphenated option names are valid keys).",
-    `See \`${root.key} docs schema\` or the schema resource for per-tool shapes.`,
+    `See \`${root.key} docs cli-schema\` or the schema resource for per-tool shapes.`,
     "",
     "Varargs positionals accept a JSON array of strings (not a comma-separated string).",
     "Options with `format: comma-list` accept a comma-separated string or JSON array.",
@@ -236,7 +236,7 @@ export function generateMcpGuide(root: CliProgram): string {
     "",
     "## Protocol",
     "",
-    "Stdio NDJSON JSON-RPC. Help and `docs schema` are not available through tool calls.",
+    "Stdio NDJSON JSON-RPC. Help and `docs cli-schema` are not available through tool calls.",
     `Run \`${root.key} docs\` for bundled user documentation.`,
     "",
   );

package/src/docs/resolve.ts

@@ -1,11 +1,13 @@
+import { openApiJson } from "../api/openapi.ts";
 import { cliSchemaJson } from "../schema.ts";
 import { generateSkillBundle } from "../skill/generate.ts";
 import type { CliDocsConfig, CliProgram } from "../types.ts";
 import { generateApiGuide } from "./api-guide.ts";
+import { generateHttpGuide } from "./http-guide.ts";
 import { generateMcpGuide } from "./mcp-guide.ts";
 
 /** Built-in docs subcommand keys not allowed in `docs.topics`. */
-export const DOCS_BUILTIN_TOPIC_KEYS = ["mcp", "all", "schema", "api", "skill"] as const;
+export const DOCS_BUILTIN_TOPIC_KEYS = ["http", "mcp", "all", "cli-schema", "api", "skill", "openapi"] as const;
 
 export type DocsBuiltinTopicKey = (typeof DOCS_BUILTIN_TOPIC_KEYS)[number];
 
@@ -43,6 +45,16 @@ export function docsIncludesMcpTopic(program: CliProgram): boolean {
   return docsEnabled(program) && program.mcpServer?.enabled === true;
 }
 
+/** Whether HTTP auto-guide topic is included. */
+export function docsIncludesHttpTopic(program: CliProgram): boolean {
+  return docsEnabled(program) && program.apiServer?.enabled === true;
+}
+
+/** Whether OpenAPI export topic is included. */
+export function docsIncludesOpenApiTopic(program: CliProgram): boolean {
+  return docsIncludesHttpTopic(program);
+}
+
 /** Leaf help description for a user topic. */
 export function docsTopicDescription(key: string, custom?: string): string {
   if (custom) {
@@ -67,6 +79,12 @@ export function docsTopicText(program: CliProgram, topic: string): string {
     }
     return generateMcpGuide(program);
   }
+  if (topic === "http") {
+    if (!docsIncludesHttpTopic(program)) {
+      throw new Error("Unknown docs topic 'http'.");
+    }
+    return generateHttpGuide(program);
+  }
   const entry = docs.topics[topic];
   if (!entry) {
     throw new Error(`Unknown docs topic '${topic}'.`);
@@ -76,9 +94,15 @@ export function docsTopicText(program: CliProgram, topic: string): string {
 
 /** Full file body for a docs topic (stdout or `--save`). */
 export function docsTopicContent(program: CliProgram, topic: string): string {
-  if (topic === "schema") {
+  if (topic === "cli-schema") {
     return cliSchemaJson(program);
   }
+  if (topic === "openapi") {
+    if (!docsIncludesOpenApiTopic(program)) {
+      throw new Error("Unknown docs topic 'openapi'.");
+    }
+    return openApiJson(program);
+  }
   if (topic === "api") {
     return generateApiGuide(program);
   }

package/src/docs/save.ts

@@ -36,8 +36,11 @@ export function docsTopicContentForSave(program: CliProgram, topic: string): str
 
 /** Filename for a saved docs topic. */
 export function docsSaveFilename(topic: string): string {
-  if (topic === "schema") {
-    return "schema.json";
+  if (topic === "cli-schema") {
+    return "cli-schema.json";
+  }
+  if (topic === "openapi") {
+    return "openapi.json";
   }
   return `${topic}.md`;
 }

package/src/headless/tool-call.ts

@@ -0,0 +1,147 @@
+/*
+Shared headless tool dispatch for MCP and HTTP: config bootstrap, argv conversion, and invoke.
+*/
+
+import { apiErrorResponse, apiSuccessResponse } from "../api/result.ts";
+import type { Cli, CliInvokeResult } from "../cli.ts";
+import { bootstrapAppConfig } from "../config/bootstrap.ts";
+import { formatMcpMissingConfigMessage, missingRequiredConfig } from "../config/resolve.ts";
+import { buildToolCallSuccessFromResponse } from "../mcp/result.ts";
+import { collectMcpTools, type McpToolDef, mcpToolCallToArgv } from "../mcp/tools.ts";
+import type { CliInvocation, CliProgram } from "../types.ts";
+
+/** Outcome of resolving a tool name against the program schema. */
+export type ToolLookupResult =
+  | { ok: true; tool: McpToolDef }
+  | { ok: false; kind: "unknown"; message: string }
+  | { ok: false; kind: "missing_config"; message: string };
+
+/** Successful headless tool invocation payload shared by MCP and HTTP. */
+export interface HeadlessToolCallSuccess {
+  ok: true;
+  response: NonNullable<CliInvokeResult["response"]>;
+  mcpResult: ReturnType<typeof buildToolCallSuccessFromResponse>;
+}
+
+/** Failed headless tool invocation payload shared by MCP and HTTP. */
+export interface HeadlessToolCallFailure {
+  ok: false;
+  kind: "argv" | "invoke" | "help";
+  message: string;
+  exitCode: number;
+  stdout: string;
+  stderr: string;
+  invokeResult?: CliInvokeResult;
+}
+
+export type HeadlessToolCallResult = HeadlessToolCallSuccess | HeadlessToolCallFailure;
+
+/** Finds an exposed tool by MCP or HTTP API tool name. */
+export function lookupHeadlessTool(
+  program: CliProgram,
+  toolName: string,
+  invocation: CliInvocation = "mcp",
+): ToolLookupResult {
+  const tools = collectMcpTools(program);
+  const tool =
+    invocation === "api" ? tools.find((t) => t.apiName === toolName) : tools.find((t) => t.name === toolName);
+  if (!tool) {
+    return { ok: false, kind: "unknown", message: `Unknown tool: ${toolName}` };
+  }
+  const { resolved } = bootstrapAppConfig(program, { validateFile: false });
+  const missingConfig = missingRequiredConfig(program, resolved);
+  if (missingConfig.length > 0) {
+    return {
+      ok: false,
+      kind: "missing_config",
+      message: formatMcpMissingConfigMessage(program, missingConfig),
+    };
+  }
+  return { ok: true, tool };
+}
+
+/**
+ * Converts flat tool arguments to argv and invokes the leaf handler headlessly.
+ */
+export async function executeHeadlessToolCall(
+  cli: Cli,
+  tool: McpToolDef,
+  args: Record<string, unknown>,
+  invocation: CliInvocation,
+): Promise<HeadlessToolCallResult> {
+  const argvResult = mcpToolCallToArgv(cli.program, tool, args);
+  if ("error" in argvResult) {
+    return {
+      ok: false,
+      kind: "argv",
+      message: argvResult.error,
+      exitCode: 1,
+      stdout: "",
+      stderr: "",
+    };
+  }
+
+  const invokeResult = await cli.invoke(argvResult, { invocation, toolArgs: args });
+  if (invokeResult.kind === "help") {
+    return {
+      ok: false,
+      kind: "help",
+      message: invokeResult.errorMsg ?? "Help is not available via tool calls.",
+      exitCode: invokeResult.exitCode,
+      stdout: invokeResult.stdout,
+      stderr: invokeResult.stderr,
+      invokeResult,
+    };
+  }
+
+  if (invokeResult.kind === "ok" && invokeResult.exitCode === 0 && invokeResult.response) {
+    const mcpResult = buildToolCallSuccessFromResponse(invokeResult.response);
+    return {
+      ok: true,
+      response: invokeResult.response,
+      mcpResult,
+    };
+  }
+
+  if (invokeResult.kind === "ok" && invokeResult.exitCode === 0) {
+    return {
+      ok: false,
+      kind: "invoke",
+      message: "Handler did not call ctx.respond() or return a value",
+      exitCode: 1,
+      stdout: invokeResult.stdout,
+      stderr: invokeResult.stderr,
+      invokeResult,
+    };
+  }
+
+  const message = invokeResult.errorMsg ?? (invokeResult.stderr.trim() || `Exit code ${invokeResult.exitCode}`);
+  return {
+    ok: false,
+    kind: "invoke",
+    message,
+    exitCode: invokeResult.exitCode,
+    stdout: invokeResult.stdout,
+    stderr: invokeResult.stderr,
+    invokeResult,
+  };
+}
+
+/** Maps a headless success result to an HTTP Response. */
+export function headlessSuccessToHttpResponse(
+  result: HeadlessToolCallSuccess,
+  leafApiResponse?: import("../types.ts").CliApiResponseConfig,
+): Response {
+  return apiSuccessResponse(result.response, leafApiResponse);
+}
+
+/** Maps a headless failure result to a JSON HTTP error Response. */
+export function headlessFailureToHttpResponse(result: HeadlessToolCallFailure): Response {
+  const status = result.kind === "argv" || result.kind === "help" ? 400 : 500;
+  return apiErrorResponse(status, {
+    error: result.message,
+    exitCode: result.exitCode,
+    stdout: result.stdout,
+    stderr: result.stderr,
+  });
+}

package/src/headless.test.ts

@@ -12,14 +12,16 @@ import {
   wantsExplicitJson,
 } from "./headless.ts";
 
-test("wantsExplicitJson includes MCP invocation", () => {
+test("wantsExplicitJson includes MCP and API invocation", () => {
   expect(wantsExplicitJson({ invocation: "cli" }, false)).toBe(false);
   expect(wantsExplicitJson({ invocation: "mcp" }, false)).toBe(true);
+  expect(wantsExplicitJson({ invocation: "api" }, false)).toBe(true);
   expect(wantsExplicitJson({ invocation: "cli" }, true)).toBe(true);
 });
 
-test("shouldRunHeadless is true for MCP and json", () => {
+test("shouldRunHeadless is true for MCP, API, and json", () => {
   expect(shouldRunHeadless({ invocation: "mcp" }, false)).toBe(true);
+  expect(shouldRunHeadless({ invocation: "api" }, false)).toBe(true);
   expect(shouldRunHeadless({ invocation: "cli" }, true)).toBe(true);
   expect(shouldRunHeadless({ invocation: "cli" }, false, true)).toBe(true);
   expect(shouldRunHeadless({ invocation: "cli" }, false, false, false)).toBe(true);

package/src/headless.ts

@@ -4,9 +4,14 @@ import { isInteractiveTty } from "./utils.ts";
 /** Minimal context for headless routing helpers. */
 export type HeadlessContext = Pick<CliContext, "invocation">;
 
-/** True when `--json` was passed or the handler was invoked via MCP. */
+/** True when the handler was invoked via MCP or HTTP API. */
+function isToolInvocation(invocation: CliContext["invocation"]): boolean {
+  return invocation === "mcp" || invocation === "api";
+}
+
+/** True when `--json` was passed or the handler was invoked headlessly over MCP/HTTP. */
 export function wantsExplicitJson(ctx: HeadlessContext, hasJsonFlag: boolean): boolean {
-  return hasJsonFlag || ctx.invocation === "mcp";
+  return hasJsonFlag || isToolInvocation(ctx.invocation);
 }
 
 /**
@@ -19,7 +24,7 @@ export function shouldRunHeadless(
   hasDryRunFlag = false,
   interactive: boolean = isInteractiveTty,
 ): boolean {
-  if (ctx.invocation === "mcp") return true;
+  if (isToolInvocation(ctx.invocation)) return true;
   if (hasJsonFlag || hasDryRunFlag) return true;
   return !interactive;
 }
@@ -35,7 +40,7 @@ export function shouldRunHeadlessWithPositionals(
   hasDryRunFlag = false,
   interactive: boolean = isInteractiveTty,
 ): boolean {
-  if (ctx.invocation === "mcp") return true;
+  if (isToolInvocation(ctx.invocation)) return true;
   if (hasJsonFlag || hasDryRunFlag) return true;
   return !interactive && positionals.length > 0;
 }
@@ -49,7 +54,7 @@ export function shouldRunHeadlessWithYes(
   opts: { yes: boolean; hasRequiredArgs: boolean; dryRun?: boolean },
   interactive: boolean = isInteractiveTty,
 ): boolean {
-  if (ctx.invocation === "mcp") {
+  if (isToolInvocation(ctx.invocation)) {
     return opts.hasRequiredArgs && (opts.yes || Boolean(opts.dryRun));
   }
   if (opts.dryRun && opts.hasRequiredArgs) return true;

package/src/index.ts

@@ -7,6 +7,7 @@ It gives consumers one stable import path without forcing them to know the inter
 module layout.
 */
 
+export { generateOpenApi, openApiJson } from "./api/openapi.ts";
 export { Cli, type CliInvokeKind, type CliInvokeResult } from "./cli.ts";
 export { cliErrWithHelp } from "./cli-errors.ts";
 export { displayAppConfigPath, resolveAppConfigPath } from "./config/file.ts";
@@ -30,6 +31,8 @@ export {
 export type { McpBundlePaths, PackMcpBundleOpts } from "./mcp/bundle.ts";
 export { defaultMcpBundlePaths, generateMcpManifest, packMcpBundle } from "./mcp/bundle.ts";
 export type {
+  CliApiResponseConfig,
+  CliApiServerConfig,
   CliAppConfig,
   CliAppConfigEntry,
   CliAppConfigResolveContext,
@@ -47,6 +50,8 @@ export type {
   CliOption,
   CliPositional,
   CliProgram,
+  CliRespondBody,
+  CliRespondOptions,
   InstallAgentIntegration,
   InstallTargetSpec,
   ResolvedInstallTarget,

package/src/mcp/result.ts

@@ -1,7 +1,10 @@
 /*
-This module builds MCP tools/call success results from captured handler output.
+This module builds MCP tools/call success results from handler respond payloads.
 */
 
+import { encodeRespondBodyBase64 } from "../respond.ts";
+import type { CliRespondOptions } from "../types.ts";
+
 /** Text content block in an MCP tool result. */
 export interface McpTextContent {
   type: "text";
@@ -15,43 +18,45 @@ export interface McpToolCallSuccess {
   isError: false;
 }
 
-/** Parses stdout as JSON when the full trimmed string is valid JSON. */
-function parseStructuredStdout(stdout: string): unknown | undefined {
-  const trimmed = stdout.trim();
-  if (trimmed.length === 0) {
-    return undefined;
-  }
-  try {
-    return JSON.parse(trimmed) as unknown;
-  } catch {
-    return undefined;
-  }
+/** Canonical MCP structuredContent for string respond bodies. */
+export interface McpStringRespondContent {
+  content: string;
+  contentType: string;
+}
+
+/** Canonical MCP structuredContent for binary respond bodies. */
+export interface McpBinaryRespondContent {
+  data: string;
+  contentType: string;
+  encoding: "base64";
 }
 
 /**
- * Builds a successful tools/call result from captured handler stdout/stderr.
- * stderr is a second content block when non-empty; structuredContent is set when stdout is JSON.
+ * Builds a successful tools/call result from a headless respond payload.
+ * Binary bodies are encoded as base64 in structuredContent.
  */
-export function buildToolCallSuccess(stdout: string, stderr: string): McpToolCallSuccess {
-  const content: McpTextContent[] = [];
-  if (stdout.length > 0) {
-    content.push({ type: "text", text: stdout });
-  }
-  const errText = stderr.trim();
-  if (errText.length > 0) {
-    if (content.length === 0) {
-      content.push({ type: "text", text: "" });
-    }
-    content.push({ type: "text", text: errText });
-  }
-  if (content.length === 0) {
-    content.push({ type: "text", text: "" });
-  }
+export function buildToolCallSuccessFromResponse(response: CliRespondOptions): McpToolCallSuccess {
+  const { body, contentType = "application/json; charset=utf-8" } = response;
+  let structuredContent: unknown;
 
-  const structuredContent = parseStructuredStdout(stdout);
-  const result: McpToolCallSuccess = { content, isError: false };
-  if (structuredContent !== undefined) {
-    result.structuredContent = structuredContent;
+  if (body instanceof Uint8Array) {
+    structuredContent = {
+      data: encodeRespondBodyBase64(body),
+      contentType,
+      encoding: "base64",
+    } satisfies McpBinaryRespondContent;
+  } else if (typeof body === "string") {
+    structuredContent = {
+      content: body,
+      contentType,
+    } satisfies McpStringRespondContent;
+  } else {
+    structuredContent = body;
   }
-  return result;
+
+  return {
+    content: [{ type: "text", text: "" }],
+    structuredContent,
+    isError: false,
+  };
 }

package/src/mcp/server.ts

@@ -4,10 +4,8 @@ resources, and ping. Responses are newline-delimited JSON on stdout only.
 */
 
 import type { Cli } from "../cli.ts";
-import { bootstrapAppConfig } from "../config/bootstrap.ts";
-import { formatMcpMissingConfigMessage, missingRequiredConfig } from "../config/resolve.ts";
-import { buildToolCallSuccess } from "./result.ts";
-import { allMcpResources, collectMcpTools, mcpToolCallToArgv, resolveMcpServerInfo } from "./tools.ts";
+import { executeHeadlessToolCall, lookupHeadlessTool } from "../headless/tool-call.ts";
+import { allMcpResources, collectMcpTools, resolveMcpServerInfo } from "./tools.ts";
 
 const MCP_PROTOCOL_VERSION = "2024-11-05";
 
@@ -109,57 +107,41 @@ async function handleRequestLine(cli: Cli, line: string): Promise<void> {
         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 { resolved } = bootstrapAppConfig(root, { validateFile: false });
-      const missingConfig = missingRequiredConfig(root, resolved);
-      if (missingConfig.length > 0) {
-        writeResponse({
-          jsonrpc: "2.0",
-          id,
-          result: {
-            content: [
-              {
-                type: "text",
-                text: formatMcpMissingConfigMessage(root, missingConfig),
-              },
-            ],
-            isError: true,
-          },
-        });
-        return;
-      }
-      const argvResult = mcpToolCallToArgv(root, tool, (rawArgs ?? {}) as Record<string, unknown>);
-      if ("error" in argvResult) {
+      const lookup = lookupHeadlessTool(root, name);
+      if (!lookup.ok) {
+        if (lookup.kind === "unknown") {
+          writeError(id, -32602, lookup.message);
+          return;
+        }
         writeResponse({
           jsonrpc: "2.0",
           id,
           result: {
-            content: [{ type: "text", text: argvResult.error }],
+            content: [{ type: "text", text: lookup.message }],
             isError: true,
           },
         });
         return;
       }
-      const invokeResult = await cli.invoke(argvResult);
-      if (invokeResult.kind === "ok" && invokeResult.exitCode === 0) {
+      const invokeResult = await executeHeadlessToolCall(
+        cli,
+        lookup.tool,
+        (rawArgs ?? {}) as Record<string, unknown>,
+        "mcp",
+      );
+      if (invokeResult.ok) {
         writeResponse({
           jsonrpc: "2.0",
           id,
-          result: buildToolCallSuccess(invokeResult.stdout, invokeResult.stderr),
+          result: invokeResult.mcpResult,
         });
         return;
       }
-      const errText = invokeResult.stderr.trim() || invokeResult.errorMsg || `Exit code ${invokeResult.exitCode}`;
       writeResponse({
         jsonrpc: "2.0",
         id,
         result: {
-          content: [{ type: "text", text: errText }],
+          content: [{ type: "text", text: invokeResult.message }],
           isError: true,
         },
       });