@tronsfey/ucli 0.5.0 → 0.5.2

package/dist/index.js

@@ -166,23 +166,59 @@ var ExitCode = {
   SERVER_ERROR: 7
 };
 
+// src/lib/output.ts
+var currentMode = "text";
+function setOutputMode(mode) {
+  currentMode = mode;
+}
+function isJsonOutput() {
+  return currentMode === "json";
+}
+function outputSuccess(data) {
+  if (currentMode === "json") {
+    console.log(JSON.stringify({ success: true, data }, null, 2));
+  }
+}
+function outputError(code, message, hint) {
+  if (currentMode === "json") {
+    const envelope = {
+      success: false,
+      error: { code, message, ...hint ? { hint } : {} }
+    };
+    console.log(JSON.stringify(envelope, null, 2));
+    process.exit(code);
+  }
+  console.error(`
+\u2716 Error: ${message}`);
+  if (hint) console.error(`  Hint: ${hint}`);
+  process.exit(code);
+}
+
 // src/commands/configure.ts
 function registerConfigure(program2) {
   program2.command("configure").description("Configure the OAS Gateway server URL and authentication token").requiredOption("--server <url>", "OAS Gateway server URL (e.g. https://oas.example.com)").requiredOption("--token <jwt>", "Group JWT token issued by the server admin").action(async (opts) => {
     const serverUrl = opts.server.replace(/\/$/, "");
     const token = opts.token;
-    console.log(`Connecting to ${serverUrl}...`);
+    if (!isJsonOutput()) {
+      console.log(`Connecting to ${serverUrl}...`);
+    }
     const client = new ServerClient({ serverUrl, token });
     try {
       await client.listOAS();
       saveConfig({ serverUrl, token });
+      if (isJsonOutput()) {
+        outputSuccess({ serverUrl, configured: true });
+        return;
+      }
       console.log("\u2713 Configuration saved successfully.");
       console.log(`  Server: ${serverUrl}`);
       console.log(`  Token:  ${token.slice(0, 20)}...`);
     } catch (err) {
-      console.error("Connection failed:", err.message);
-      console.error("Please check the server URL and token.");
-      process.exit(ExitCode.CONNECTIVITY_ERROR);
+      outputError(
+        ExitCode.CONNECTIVITY_ERROR,
+        `Connection failed: ${err.message}`,
+        "Check the server URL and token"
+      );
     }
   });
 }
@@ -335,7 +371,7 @@ function buildSafeEnv(authEnv) {
 }
 async function runOperation(opts) {
   const bin = resolveOpenapi2CliBin();
-  const { entry, operationArgs, format, query } = opts;
+  const { entry, operationArgs, format, query, machine, dryRun } = opts;
   const args = [
     "run",
     "--oas",
@@ -343,6 +379,8 @@ async function runOperation(opts) {
     "--cache-ttl",
     String(entry.cacheTtl),
     ...entry.baseEndpoint ? ["--endpoint", entry.baseEndpoint] : [],
+    ...machine ? ["--machine"] : [],
+    ...dryRun ? ["--dry-run"] : [],
     ...format ? ["--format", format] : [],
     ...query ? ["--query", query] : [],
     ...operationArgs
@@ -466,24 +504,24 @@ function registerServices(program2) {
         await writeOASListCache(entries, maxTtl);
       }
     }
+    const safe = entries.map(({ authConfig, ...rest }) => ({
+      ...rest,
+      authConfig: { type: authConfig["type"] ?? rest.authType }
+    }));
+    if (isJsonOutput()) {
+      outputSuccess(safe);
+      return;
+    }
     const format = (opts.format ?? "table").toLowerCase();
     if (entries.length === 0) {
       console.log("No services registered in this group.");
       return;
     }
     if (format === "json") {
-      const safe = entries.map(({ authConfig, ...rest }) => ({
-        ...rest,
-        authConfig: { type: authConfig["type"] ?? rest.authType }
-      }));
       console.log(JSON.stringify(safe, null, 2));
       return;
     }
     if (format === "yaml") {
-      const safe = entries.map(({ authConfig, ...rest }) => ({
-        ...rest,
-        authConfig: { type: authConfig["type"] ?? rest.authType }
-      }));
       console.log(toYaml(safe));
       return;
     }
@@ -504,30 +542,30 @@ ${"SERVICE".padEnd(nameWidth)}  AUTH      DESCRIPTION`);
     let entry;
     try {
       entry = await client.getOAS(name);
-    } catch (err) {
-      console.error(`Service not found: ${name}`);
-      console.error("Run `ucli services list` to see available services.");
-      process.exit(ExitCode.NOT_FOUND);
+    } catch {
+      outputError(
+        ExitCode.NOT_FOUND,
+        `Service not found: ${name}`,
+        "Run: ucli services list  to see available services"
+      );
     }
     const help = await getServiceHelp(entry);
+    const { authConfig, ...rest } = entry;
+    const safe = {
+      ...rest,
+      authConfig: { type: authConfig["type"] ?? rest.authType },
+      operationsHelp: help
+    };
+    if (isJsonOutput()) {
+      outputSuccess(safe);
+      return;
+    }
     const format = (opts.format ?? "table").toLowerCase();
     if (format === "json") {
-      const { authConfig, ...rest } = entry;
-      const safe = {
-        ...rest,
-        authConfig: { type: authConfig["type"] ?? rest.authType },
-        operationsHelp: help
-      };
       console.log(JSON.stringify(safe, null, 2));
       return;
     }
     if (format === "yaml") {
-      const { authConfig, ...rest } = entry;
-      const safe = {
-        ...rest,
-        authConfig: { type: authConfig["type"] ?? rest.authType },
-        operationsHelp: help
-      };
       console.log(toYaml(safe));
       return;
     }
@@ -546,15 +584,20 @@ Service: ${entry.name}`);
 
 // src/commands/run.ts
 function registerRun(program2) {
-  program2.command("run [service] [args...]").description("Execute an operation on a service").option("--service <name>", "Service name (from `services list`)").option("--operation <id>", "OperationId to execute").option("--params <json>", "JSON string of operation parameters").option("--format <fmt>", "Output format: json | table | yaml", "json").option("--query <jmespath>", "Filter response with JMESPath expression").option("--data <json>", "Request body (JSON string or @filename)").allowUnknownOption(true).action(async (serviceArg, args, opts) => {
+  program2.command("run [service] [args...]").description("Execute an operation on a service").option("--service <name>", "Service name (from `services list`)").option("--operation <id>", "OperationId to execute").option("--params <json>", "JSON string of operation parameters").option("--format <fmt>", "Output format: json | table | yaml", "json").option("--query <jmespath>", "Filter response with JMESPath expression").option("--data <json>", "Request body (JSON string or @filename)").option("--machine", "Agent-friendly mode: structured JSON envelope output").option("--dry-run", "Preview the HTTP request without executing (implies --machine)").allowUnknownOption(true).action(async (serviceArg, args, opts) => {
     if (serviceArg && opts.service && serviceArg !== opts.service) {
-      console.error(`Conflicting service values: positional "${serviceArg}" and --service "${opts.service}". Use either the positional argument or --service flag, not both.`);
-      process.exit(ExitCode.USAGE_ERROR);
+      outputError(
+        ExitCode.USAGE_ERROR,
+        `Conflicting service values: positional "${serviceArg}" and --service "${opts.service}". Use either the positional argument or --service flag, not both.`
+      );
     }
     const service = opts.service ?? serviceArg;
     if (!service) {
-      console.error("Missing service name. Use positional <service> or --service <name>.");
-      process.exit(ExitCode.USAGE_ERROR);
+      outputError(
+        ExitCode.USAGE_ERROR,
+        "Missing service name. Use positional <service> or --service <name>.",
+        "Run: ucli services list  to see available services"
+      );
     }
     const cfg = getConfig();
     const client = new ServerClient(cfg);
@@ -562,9 +605,11 @@ function registerRun(program2) {
     try {
       entry = await client.getOAS(service);
     } catch {
-      console.error(`Unknown service: ${service}`);
-      console.error("Run `ucli services list` to see available services.");
-      process.exit(ExitCode.NOT_FOUND);
+      outputError(
+        ExitCode.NOT_FOUND,
+        `Unknown service: ${service}`,
+        "Run: ucli services list  to see available services"
+      );
     }
     const extraArgs = opts.args ?? [];
     const operationArgs = [...args, ...extraArgs];
@@ -576,8 +621,11 @@ function registerRun(program2) {
       try {
         parsed = JSON.parse(opts.params);
       } catch {
-        console.error(`Invalid --params JSON. Example: --params '{"petId": 1}'`);
-        process.exit(ExitCode.USAGE_ERROR);
+        outputError(
+          ExitCode.USAGE_ERROR,
+          "Invalid --params JSON.",
+          `Example: --params '{"petId": 1}'`
+        );
       }
       if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
         for (const [k, v] of Object.entries(parsed)) {
@@ -592,16 +640,22 @@ function registerRun(program2) {
     }
     const format = opts.format;
     const query = opts.query;
+    const machine = opts.machine ?? false;
+    const dryRun = opts.dryRun ?? false;
     try {
       await runOperation({
         entry,
         operationArgs,
         ...format !== void 0 ? { format } : {},
-        ...query !== void 0 ? { query } : {}
+        ...query !== void 0 ? { query } : {},
+        ...machine ? { machine } : {},
+        ...dryRun ? { dryRun } : {}
       });
     } catch (err) {
-      console.error("Operation failed:", err.message);
-      process.exit(ExitCode.GENERAL_ERROR);
+      outputError(
+        ExitCode.GENERAL_ERROR,
+        `Operation failed: ${err.message}`
+      );
     }
   });
 }
@@ -611,7 +665,9 @@ function registerRefresh(program2) {
   program2.command("refresh").description("Force-refresh the local OAS cache from the server").option("--service <name>", "Refresh only a specific service").action(async (opts) => {
     const cfg = getConfig();
     const client = new ServerClient(cfg);
-    console.log("Refreshing OAS list from server...");
+    if (!isJsonOutput()) {
+      console.log("Refreshing OAS list from server...");
+    }
     if (opts.service) {
       await clearOASCache(opts.service);
     } else {
@@ -622,6 +678,10 @@ function registerRefresh(program2) {
       const maxTtl = Math.min(...entries.map((e) => e.cacheTtl));
       await writeOASListCache(entries, maxTtl);
     }
+    if (isJsonOutput()) {
+      outputSuccess({ refreshed: entries.length });
+      return;
+    }
     console.log(`\u2713 Refreshed ${entries.length} service(s).`);
   });
 }
@@ -696,6 +756,10 @@ DISCOVERY
   ucli services info <service>
       Show detailed service info and all available operations.
 
+  ucli introspect
+      Return complete capability manifest in a single call (JSON).
+      Ideal for AI agents: includes services, MCP servers, and command reference.
+
   ucli help [service]
       Show this guide, or service-specific operations.
 
@@ -708,6 +772,16 @@ EXECUTION
         --query <jmespath>         Filter response with JMESPath
         --data <json|@file>        Request body for POST/PUT/PATCH
 
+MCP SERVERS
+  ucli mcp list
+      List all MCP servers in your group.
+
+  ucli mcp tools <server>
+      List tools available on a MCP server.
+
+  ucli mcp run <server> <tool> [key=value ...]
+      Call a tool on a MCP server.
+
 MAINTENANCE
   ucli refresh
       Force-refresh the local OAS cache from the server.
@@ -722,6 +796,8 @@ SHELL COMPLETIONS
 
 GLOBAL FLAGS
   --debug                          Enable verbose debug logging
+  --output json                    Wrap ALL output in structured JSON envelopes
+                                   (for agent/automation consumption)
   -v, --version                    Show version number
 
 ERRORS
@@ -729,6 +805,11 @@ ERRORS
   404 Not Found     \u2192 Check service name: ucli services list
   4xx Client Error  \u2192 Check operation args: ucli services info <service>
   5xx Server Error  \u2192 Retry or run: ucli refresh
+
+AI AGENT QUICK START
+  1. ucli introspect               # discover everything in one call
+  2. ucli run <svc> <op> [args]    # execute operations
+  3. Use --output json globally    # get structured { success, data/error } envelopes
 `);
 }
 
@@ -739,12 +820,14 @@ function resolve(mod, name) {
   throw new Error(`Cannot resolve export "${name}" from module`);
 }
 async function getMcp2cli() {
-  const clientMod = await import("./client-3I7XBDJU.js");
-  const runnerMod = await import("./runner-GVYIJNHN.js");
+  const clientMod = await import("./client-Y6NONDCI.js");
+  const runnerMod = await import("./runner-ROLDMGH3.js");
   return {
     createMcpClient: resolve(clientMod, "createMcpClient"),
     getTools: resolve(runnerMod, "getTools"),
-    runTool: resolve(runnerMod, "runTool")
+    runTool: resolve(runnerMod, "runTool"),
+    describeTool: resolve(runnerMod, "describeTool"),
+    describeToolJson: resolve(runnerMod, "describeToolJson")
   };
 }
 async function closeClient(client) {
@@ -778,7 +861,24 @@ async function listMcpTools(entry) {
     await closeClient(client);
   }
 }
-async function runMcpTool(entry, toolName, rawArgs) {
+async function describeMcpTool(entry, toolName, opts) {
+  const { createMcpClient, getTools, describeTool, describeToolJson } = await getMcp2cli();
+  const config = buildMcpConfig(entry);
+  const client = await createMcpClient(config);
+  try {
+    const tools = await getTools(client, config, { noCache: false, cacheTtl: 3600 });
+    const tool = tools.find((t) => t.name === toolName);
+    if (!tool) throw new Error(`Tool "${toolName}" not found on MCP server "${entry.name}"`);
+    if (opts?.json) {
+      describeToolJson(tool);
+    } else {
+      describeTool(tool);
+    }
+  } finally {
+    await closeClient(client);
+  }
+}
+async function runMcpTool(entry, toolName, rawArgs, opts) {
   const { createMcpClient, getTools, runTool } = await getMcp2cli();
   const config = buildMcpConfig(entry);
   const client = await createMcpClient(config);
@@ -797,7 +897,10 @@ async function runMcpTool(entry, toolName, rawArgs) {
         normalizedArgs.push(arg);
       }
     }
-    await runTool(client, tool, normalizedArgs, {});
+    await runTool(client, tool, normalizedArgs, {
+      ...opts?.json ? { json: true } : {},
+      ...opts?.inputJson ? { inputJson: opts.inputJson } : {}
+    });
   } finally {
     await closeClient(client);
   }
@@ -810,24 +913,24 @@ function registerMcp(program2) {
     const cfg = getConfig();
     const client = new ServerClient(cfg);
     const entries = await client.listMCP();
+    const safe = entries.map(({ authConfig, ...rest }) => ({
+      ...rest,
+      authConfig: { type: authConfig.type }
+    }));
+    if (isJsonOutput()) {
+      outputSuccess(safe);
+      return;
+    }
     if (entries.length === 0) {
       console.log("No MCP servers registered in this group.");
       return;
     }
     const format = (opts.format ?? "table").toLowerCase();
     if (format === "json") {
-      const safe = entries.map(({ authConfig, ...rest }) => ({
-        ...rest,
-        authConfig: { type: authConfig.type }
-      }));
       console.log(JSON.stringify(safe, null, 2));
       return;
     }
     if (format === "yaml") {
-      const safe = entries.map(({ authConfig, ...rest }) => ({
-        ...rest,
-        authConfig: { type: authConfig.type }
-      }));
       console.log(toYaml(safe));
       return;
     }
@@ -848,16 +951,21 @@ ${"SERVER".padEnd(nameWidth)}  TRANSPORT  DESCRIPTION`);
     try {
       entry = await client.getMCP(serverName);
     } catch {
-      console.error(`Unknown MCP server: ${serverName}`);
-      console.error("Run `ucli mcp list` to see available servers.");
-      process.exit(ExitCode.NOT_FOUND);
+      outputError(
+        ExitCode.NOT_FOUND,
+        `Unknown MCP server: ${serverName}`,
+        "Run: ucli mcp list  to see available servers"
+      );
     }
     let tools;
     try {
       tools = await listMcpTools(entry);
     } catch (err) {
-      console.error("Failed to fetch tools:", err.message);
-      process.exit(ExitCode.GENERAL_ERROR);
+      outputError(ExitCode.GENERAL_ERROR, `Failed to fetch tools: ${err.message}`);
+    }
+    if (isJsonOutput()) {
+      outputSuccess(tools);
+      return;
     }
     if (tools.length === 0) {
       console.log(`No tools found on MCP server "${serverName}".`);
@@ -881,22 +989,45 @@ Tools on "${serverName}":`);
     }
     console.log();
   });
-  mcp.command("run <server> <tool> [args...]").description("Call a tool on a MCP server").action(async (serverName, toolName, args) => {
+  mcp.command("describe <server> <tool>").description("Show detailed schema for a tool on a MCP server").option("--json", "Output full schema as JSON (for agent consumption)").action(async (serverName, toolName, opts) => {
     const cfg = getConfig();
     const client = new ServerClient(cfg);
     let entry;
     try {
       entry = await client.getMCP(serverName);
     } catch {
-      console.error(`Unknown MCP server: ${serverName}`);
-      console.error("Run `ucli mcp list` to see available servers.");
-      process.exit(ExitCode.NOT_FOUND);
+      outputError(
+        ExitCode.NOT_FOUND,
+        `Unknown MCP server: ${serverName}`,
+        "Run: ucli mcp list  to see available servers"
+      );
+    }
+    try {
+      await describeMcpTool(entry, toolName, { json: opts.json });
+    } catch (err) {
+      outputError(ExitCode.GENERAL_ERROR, `Failed to describe tool: ${err.message}`);
+    }
+  });
+  mcp.command("run <server> <tool> [args...]").description("Call a tool on a MCP server").option("--json", "Machine-readable JSON output").option("--input-json <json>", "Pass tool arguments as a JSON object").action(async (serverName, toolName, args, opts) => {
+    const cfg = getConfig();
+    const client = new ServerClient(cfg);
+    let entry;
+    try {
+      entry = await client.getMCP(serverName);
+    } catch {
+      outputError(
+        ExitCode.NOT_FOUND,
+        `Unknown MCP server: ${serverName}`,
+        "Run: ucli mcp list  to see available servers"
+      );
     }
     try {
-      await runMcpTool(entry, toolName, args);
+      await runMcpTool(entry, toolName, args, {
+        json: opts.json,
+        inputJson: opts.inputJson
+      });
     } catch (err) {
-      console.error("Tool execution failed:", err.message);
-      process.exit(ExitCode.GENERAL_ERROR);
+      outputError(ExitCode.GENERAL_ERROR, `Tool execution failed: ${err.message}`);
     }
   });
 }
@@ -931,8 +1062,11 @@ function registerDoctor(program2) {
         ok: false,
         detail: "Not configured. Run: ucli configure --server <url> --token <jwt>"
       });
-      printResults(results);
-      process.exit(ExitCode.CONFIG_ERROR);
+      outputError(
+        ExitCode.CONFIG_ERROR,
+        "Not configured",
+        "Run: ucli configure --server <url> --token <jwt>"
+      );
     }
     let cfg;
     try {
@@ -948,8 +1082,11 @@ function registerDoctor(program2) {
         ok: false,
         detail: `Failed to read config: ${err.message}`
       });
-      printResults(results);
-      process.exit(ExitCode.CONFIG_ERROR);
+      outputError(
+        ExitCode.CONFIG_ERROR,
+        `Failed to read config: ${err.message}`,
+        "Run: ucli configure --server <url> --token <jwt>"
+      );
     }
     debug(`Checking connectivity to ${cfg.serverUrl}...`);
     try {
@@ -985,8 +1122,15 @@ function registerDoctor(program2) {
         detail: `Token rejected: ${msg}`
       });
     }
-    printResults(results);
     const allOk = results.every((r) => r.ok);
+    if (isJsonOutput()) {
+      outputSuccess({
+        healthy: allOk,
+        checks: results
+      });
+      process.exit(allOk ? ExitCode.SUCCESS : ExitCode.GENERAL_ERROR);
+    }
+    printResults(results);
     process.exit(allOk ? ExitCode.SUCCESS : ExitCode.GENERAL_ERROR);
   });
 }
@@ -1026,7 +1170,7 @@ _ucli_completions() {
   COMPREPLY=()
   cur="\${COMP_WORDS[COMP_CWORD]}"
   prev="\${COMP_WORDS[COMP_CWORD-1]}"
-  commands="configure services run refresh help mcp doctor completions"
+  commands="configure services run refresh help mcp doctor completions introspect"
 
   case "\${COMP_WORDS[1]}" in
     services)
@@ -1070,6 +1214,7 @@ _ucli() {
     'mcp:Interact with MCP servers'
     'doctor:Check configuration and connectivity'
     'completions:Generate shell completion script'
+    'introspect:Return complete capability manifest for AI agents'
   )
 
   _arguments -C \\
@@ -1112,6 +1257,8 @@ complete -c ucli -n __fish_use_subcommand -a mcp -d 'Interact with MCP servers'
 complete -c ucli -n __fish_use_subcommand -a doctor -d 'Check config and connectivity'
 complete -c ucli -n __fish_use_subcommand -a completions -d 'Generate shell completions'
 
+complete -c ucli -n __fish_use_subcommand -a introspect -d 'Return capability manifest for AI agents'
+
 # services subcommands
 complete -c ucli -n '__fish_seen_subcommand_from services' -a list -d 'List services'
 complete -c ucli -n '__fish_seen_subcommand_from services' -a info -d 'Show service details'
@@ -1125,16 +1272,188 @@ complete -c ucli -n '__fish_seen_subcommand_from mcp' -a run -d 'Call a tool'
 complete -c ucli -n '__fish_seen_subcommand_from completions' -a 'bash zsh fish' -d 'Shell type'`;
 }
 
+// src/commands/introspect.ts
+function registerIntrospect(program2) {
+  program2.command("introspect").description("Return a complete capability manifest for AI agent discovery (services, MCP servers, commands)").option("--format <fmt>", "Output format: json | yaml", "json").action(async (opts) => {
+    const cfg = getConfig();
+    const client = new ServerClient(cfg);
+    let oasEntries = [];
+    let mcpEntries = [];
+    try {
+      ;
+      [oasEntries, mcpEntries] = await Promise.all([
+        client.listOAS(),
+        client.listMCP()
+      ]);
+    } catch (err) {
+      const message = err.message;
+      outputError(
+        ExitCode.CONNECTIVITY_ERROR,
+        `Failed to fetch capabilities: ${message}`,
+        "Check server connectivity with: ucli doctor"
+      );
+    }
+    const manifest = {
+      version: "1",
+      services: oasEntries.map(toIntrospectService),
+      mcpServers: mcpEntries.map(toIntrospectMcpServer),
+      commands: getCommandReference()
+    };
+    const format = (opts.format ?? "json").toLowerCase();
+    if (isJsonOutput()) {
+      outputSuccess(manifest);
+      return;
+    }
+    if (format === "json") {
+      console.log(JSON.stringify(manifest, null, 2));
+      return;
+    }
+    if (format === "yaml") {
+      console.log(toYaml(manifest));
+      return;
+    }
+    console.log(JSON.stringify(manifest, null, 2));
+  });
+}
+function toIntrospectService(e) {
+  return {
+    name: e.name,
+    description: e.description,
+    authType: e.authType,
+    remoteUrl: e.remoteUrl,
+    baseEndpoint: e.baseEndpoint,
+    cacheTtl: e.cacheTtl
+  };
+}
+function toIntrospectMcpServer(e) {
+  return {
+    name: e.name,
+    description: e.description,
+    transport: e.transport,
+    enabled: e.enabled
+  };
+}
+function getCommandReference() {
+  return [
+    {
+      name: "services list",
+      description: "List all OAS services available in the current group",
+      usage: "ucli services list [--format json|table|yaml] [--refresh]",
+      examples: [
+        "ucli services list",
+        "ucli services list --format json",
+        "ucli services list --refresh"
+      ]
+    },
+    {
+      name: "services info",
+      description: "Show detailed information and available operations for a service",
+      usage: "ucli services info <name> [--format json|table|yaml]",
+      examples: [
+        "ucli services info payments",
+        "ucli services info payments --format json"
+      ]
+    },
+    {
+      name: "run",
+      description: "Execute an operation on an OAS service",
+      usage: "ucli run <service> <operation> [--format json|table|yaml] [--query <jmespath>] [--data <json|@file>] [--params <json>] [--machine] [--dry-run]",
+      examples: [
+        "ucli run payments listTransactions",
+        "ucli run payments getTransaction --transactionId txn_123",
+        `ucli run payments createCharge --data '{"amount": 5000, "currency": "USD"}'`,
+        'ucli run inventory listProducts --query "items[?stock > `0`].name"',
+        "ucli run payments listTransactions --machine",
+        `ucli run payments createCharge --dry-run --data '{"amount": 5000}'`
+      ]
+    },
+    {
+      name: "mcp list",
+      description: "List all MCP servers available in the current group",
+      usage: "ucli mcp list [--format json|table|yaml]",
+      examples: [
+        "ucli mcp list",
+        "ucli mcp list --format json"
+      ]
+    },
+    {
+      name: "mcp tools",
+      description: "List tools available on a MCP server",
+      usage: "ucli mcp tools <server> [--format json|table|yaml]",
+      examples: [
+        "ucli mcp tools weather",
+        "ucli mcp tools weather --format json"
+      ]
+    },
+    {
+      name: "mcp describe",
+      description: "Show detailed schema for a tool on a MCP server",
+      usage: "ucli mcp describe <server> <tool> [--json]",
+      examples: [
+        "ucli mcp describe weather get_forecast",
+        "ucli mcp describe weather get_forecast --json"
+      ]
+    },
+    {
+      name: "mcp run",
+      description: "Call a tool on a MCP server",
+      usage: "ucli mcp run <server> <tool> [key=value ...] [--json] [--input-json <json>]",
+      examples: [
+        'ucli mcp run weather get_forecast location="New York"',
+        'ucli mcp run search web_search query="ucli docs" limit=5',
+        `ucli mcp run weather get_forecast --input-json '{"location": "New York"}'`,
+        'ucli mcp run weather get_forecast --json location="New York"'
+      ]
+    },
+    {
+      name: "introspect",
+      description: "Return complete capability manifest (this command)",
+      usage: "ucli introspect [--format json|yaml]",
+      examples: [
+        "ucli introspect",
+        "ucli introspect --format yaml"
+      ]
+    },
+    {
+      name: "refresh",
+      description: "Force-refresh the local OAS cache from the server",
+      usage: "ucli refresh [--service <name>]",
+      examples: [
+        "ucli refresh",
+        "ucli refresh --service payments"
+      ]
+    },
+    {
+      name: "doctor",
+      description: "Check configuration, server connectivity, and token validity",
+      usage: "ucli doctor",
+      examples: ["ucli doctor"]
+    },
+    {
+      name: "configure",
+      description: "Configure the server URL and authentication token",
+      usage: "ucli configure --server <url> --token <jwt>",
+      examples: ["ucli configure --server https://oas.example.com --token eyJ..."]
+    }
+  ];
+}
+
 // src/index.ts
 var require3 = createRequire2(import.meta.url);
 var pkg = require3("../package.json");
 var program = new Command();
-program.name("ucli").description(pkg.description).version(pkg.version, "-v, --version").option("--debug", "Enable verbose debug logging").addHelpCommand(false).hook("preAction", (_thisCommand, actionCommand) => {
+program.name("ucli").description(pkg.description).version(pkg.version, "-v, --version").option("--debug", "Enable verbose debug logging").option("--output <mode>", "Output mode: text | json (json wraps every result in a structured envelope for agent consumption)", "text").addHelpCommand(false).hook("preAction", (_thisCommand, actionCommand) => {
   let cmd = actionCommand;
   while (cmd) {
-    if (cmd.opts().debug) {
+    const opts = cmd.opts();
+    if (opts.debug) {
       setDebugMode(true);
-      break;
+    }
+    if (opts.output && typeof opts.output === "string") {
+      const mode = opts.output.toLowerCase();
+      if (mode === "json" || mode === "text") {
+        setOutputMode(mode);
+      }
     }
     cmd = cmd.parent;
   }
@@ -1146,6 +1465,7 @@ registerRefresh(program);
 registerMcp(program);
 registerDoctor(program);
 registerCompletions(program);
+registerIntrospect(program);
 registerHelp(program);
 program.parse(process.argv);
 //# sourceMappingURL=index.js.map