@evantahler/mcpx 0.15.9 → 0.16.1

package/.claude/skills/mcpx.md

@@ -29,7 +29,7 @@ mcpx exec <server> <tool> '<json args>'
 mcpx exec <server> <tool> -f params.json
 ```
 
-Output is JSON when piped. Use `--json` to force JSON output in any context — prefer this when you need to parse results programmatically.
+Output is JSON by default. Use `--json` to force JSON output in any context — prefer this when you need to parse results programmatically. Use `--format text` to extract just the text content (stripping the MCP protocol wrapper), or `--format markdown` for rich terminal rendering.
 
 ## Rules
 
@@ -38,6 +38,8 @@ Output is JSON when piped. Use `--json` to force JSON output in any context —
 - Use `mcpx search -k` for exact name matching
 - Pipe results through `jq` when you need to extract specific fields
 - Use `--json` when parsing output programmatically (automatic when piped, but explicit is safer)
+- Use `--format text` to extract plain text from tool results (strips MCP protocol wrapper)
+- Use `--format markdown` for rich terminal-rendered output with colors and formatting
 - Use `-v` for verbose debugging (HTTP details + JSON-RPC protocol messages) if an exec fails unexpectedly
 - Use `-l debug` to see all server log messages, or `-l error` for errors only
 
@@ -149,15 +151,16 @@ mcpx deauth <server>           # remove stored auth
 
 ## Global flags
 
-| Flag                      | Purpose                                                  |
-| ------------------------- | -------------------------------------------------------- |
-| `-j, --json`              | Force JSON output (default when piped)                   |
-| `-v, --verbose`           | Show HTTP details and JSON-RPC protocol messages         |
-| `-d, --with-descriptions` | Include tool descriptions in list output                 |
-| `-c, --config <path>`     | Specify config file location                             |
-| `-N, --no-interactive`    | Decline server elicitation requests (for scripted usage) |
-| `-S, --show-secrets`      | Show full auth tokens in verbose output (unmasked)       |
-| `-l, --log-level <level>` | Minimum server log level to display (default: `warning`) |
+| Flag                        | Purpose                                                  |
+| --------------------------- | -------------------------------------------------------- |
+| `-j, --json`                | Force JSON output (default when piped)                   |
+| `-F, --format <format>`     | Output format: `json`, `text`, or `markdown`             |
+| `-v, --verbose`             | Show HTTP details and JSON-RPC protocol messages         |
+| `-d, --with-descriptions`   | Include tool descriptions in list output                 |
+| `-c, --config <path>`       | Specify config file location                             |
+| `-N, --no-interactive`      | Decline server elicitation requests (for scripted usage) |
+| `-S, --show-secrets`        | Show full auth tokens in verbose output (unmasked)       |
+| `-l, --log-level <level>`   | Minimum server log level to display (default: `warning`) |
 
 ## `add` options
 

package/.cursor/rules/mcpx.mdc

@@ -29,12 +29,17 @@ mcpx exec <server> <tool> '<json args>'
 mcpx exec <server> <tool> -f params.json
 ```
 
+Output is JSON by default. Use `--json` to force JSON output in any context — prefer this when you need to parse results programmatically. Use `--format text` to extract just the text content (stripping the MCP protocol wrapper), or `--format markdown` for rich terminal rendering.
+
 ## Rules
 
 - Always search before executing — don't assume tool names exist
 - Always inspect the schema before executing — validate you have the right arguments
 - Use `mcpx search -k` for exact name matching
 - Pipe results through `jq` when you need to extract specific fields
+- Use `--json` when parsing output programmatically (automatic when piped, but explicit is safer)
+- Use `--format text` to extract plain text from tool results (strips MCP protocol wrapper)
+- Use `--format markdown` for rich terminal-rendered output with colors and formatting
 - Use `-v` for verbose debugging (HTTP details + JSON-RPC protocol messages) if an exec fails unexpectedly
 - Use `-l debug` to see all server log messages, or `-l error` for errors only
 
@@ -58,16 +63,22 @@ mcpx exec github search_repositories '{"query":"mcp"}' \
 # Read args from stdin
 echo '{"path":"./README.md"}' | mcpx exec filesystem read_file
 
-# Pipe from a file
-cat params.json | mcpx exec server tool
-
 # Read args from a file with --file flag
 mcpx exec filesystem read_file -f params.json
 ```
 
-## 4. Long-running tools (Tasks)
+## Troubleshooting
+
+- **"Not authenticated" / 401 error** → Run `mcpx auth <server>` to start the OAuth flow
+- **Exec timeout** → Use `-v` to see where it stalls; set `MCP_TIMEOUT=<seconds>` to increase the timeout (default: 1800)
+- **Search returns no results** → Try `mcpx search -k "*keyword*"` for glob matching, or `mcpx index` to rebuild the search index
+- **Missing or stale tools** → Run `mcpx index` to rebuild; any command that connects to a server also auto-updates the index
+- **Server won't connect** → Run `mcpx ping <server>` to check connectivity; use `-v` for protocol-level details
+- **Auth token expired** → Run `mcpx auth <server> -r` to force a token refresh
+
+## Long-running tools (Tasks)
 
-Some tools support async execution via MCP Tasks. mcpx auto-detects this and uses task-augmented execution when available.
+Some tools support async execution via MCP Tasks. mcpx auto-detects this.
 
 ```bash
 # Default: waits for the task to complete, showing progress
@@ -76,90 +87,122 @@ mcpx exec my-server long_running_tool '{"input": "data"}'
 # Return immediately with a task handle (for scripting/polling)
 mcpx exec my-server long_running_tool '{"input": "data"}' --no-wait
 
-# Check task status
+# Check task status / retrieve result / cancel
 mcpx task get my-server <taskId>
-
-# Retrieve the result once complete
 mcpx task result my-server <taskId>
-
-# List all tasks on a server
-mcpx task list my-server
-
-# Cancel a running task
 mcpx task cancel my-server <taskId>
+mcpx task list my-server
 ```
 
-For tools that don't support tasks, `exec` works exactly as before.
-
-## 5. Elicitation (Server-Requested Input)
-
-Some servers request user input mid-operation (e.g., confirmations, auth flows). mcpx handles this automatically:
-
-```bash
-# Interactive — prompts appear in the terminal
-mcpx exec my-server deploy_tool '{"target": "staging"}'
-# Server requests input: Confirm deployment
-#   *Confirm [y/n]: y
-
-# Non-interactive — decline all elicitation (for scripts/CI)
-mcpx exec my-server deploy_tool '{"target": "staging"}' --no-interactive
+## Elicitation (Server-Requested Input)
 
-# JSON mode — read/write elicitation as JSON via stdin/stdout
-echo '{"action":"accept","content":{"confirm":true}}' | \
-  mcpx exec my-server deploy_tool '{"target": "staging"}' --json
-```
+Some servers request user input mid-operation. mcpx handles this automatically in interactive mode. Use `-N` / `--no-interactive` to decline all elicitation (for scripts/CI), or `--json` to handle elicitation programmatically via stdin/stdout.
 
 ## Authentication
 
-Some HTTP servers require OAuth. If you see an "Not authenticated" error:
-
 ```bash
-mcpx auth <server>        # authenticate via browser
-mcpx auth <server> -s     # check token status and TTL
-mcpx auth <server> -r     # force token refresh
-mcpx deauth <server>      # remove stored auth
+mcpx auth <server>             # authenticate via browser
+mcpx auth <server> -s          # check token status and TTL
+mcpx auth <server> -r          # force token refresh
+mcpx auth <server> --no-index  # authenticate without rebuilding search index
+mcpx deauth <server>           # remove stored auth
 ```
 
 ## Available commands
 
 | Command                                | Purpose                           |
 | -------------------------------------- | --------------------------------- |
-| `mcpx`                               | List all servers and tools        |
-| `mcpx servers`                       | List servers (name, type, detail) |
-| `mcpx -d`                            | List with descriptions            |
-| `mcpx info <server>`                 | Server overview (version, capabilities, tools) |
-| `mcpx info <server> <tool>`          | Show tool schema                  |
-| `mcpx exec <server>`                 | List tools for a server           |
-| `mcpx exec <server> <tool> '<json>'` | Execute a tool                    |
-| `mcpx exec <server> <tool> -f file`  | Execute with args from file       |
-| `mcpx search "<query>"`              | Search tools (keyword + semantic) |
-| `mcpx search -k "<pattern>"`         | Keyword/glob search only          |
-| `mcpx search -q "<query>"`           | Semantic search only              |
-| `mcpx search -n <number> "<query>"`  | Limit number of results (default: 10) |
-| `mcpx index`                         | Build/rebuild search index        |
-| `mcpx index -i`                      | Show index status                 |
-| `mcpx auth <server>`                 | Authenticate with OAuth           |
-| `mcpx auth <server> -s`              | Check token status and TTL        |
+| `mcpx`                                | List all servers and tools        |
+| `mcpx servers`                        | List servers (name, type, detail) |
+| `mcpx -d`                             | List with descriptions            |
+| `mcpx info <server>`                  | Server overview (version, capabilities, tools) |
+| `mcpx info <server> <tool>`           | Show tool schema                  |
+| `mcpx exec <server>`                  | List tools for a server           |
+| `mcpx exec <server> <tool> '<json>'`  | Execute a tool                    |
+| `mcpx exec <server> <tool> -f file`   | Execute with args from file       |
+| `mcpx search "<query>"`               | Search tools (keyword + semantic) |
+| `mcpx search -k "<pattern>"`          | Keyword/glob search only          |
+| `mcpx search -q "<query>"`            | Semantic search only              |
+| `mcpx search -n <number> "<query>"`   | Limit number of results (default: 10) |
+| `mcpx index`                          | Build/rebuild search index        |
+| `mcpx index -i`                       | Show index status                 |
+| `mcpx auth <server>`                  | Authenticate with OAuth           |
+| `mcpx auth <server> -s`               | Check token status and TTL        |
 | `mcpx auth <server> -r`              | Force token refresh               |
-| `mcpx deauth <server>`               | Remove stored authentication      |
-| `mcpx ping`                          | Check connectivity to all servers |
-| `mcpx ping <server> [server2...]`    | Check specific server(s)          |
-| `mcpx add <name> --command <cmd>`    | Add a stdio MCP server            |
-| `mcpx add <name> --url <url>`        | Add an HTTP MCP server            |
-| `mcpx add <name> --url <url> --transport sse` | Add a legacy SSE server  |
-| `mcpx remove <name>`                 | Remove an MCP server              |
-| `mcpx skill install --claude`        | Install mcpx skill for Claude   |
-| `mcpx skill install --cursor`        | Install mcpx rule for Cursor    |
-| `mcpx resource`                     | List all resources across servers |
-| `mcpx resource <server>`            | List resources for a server       |
-| `mcpx resource <server> <uri>`      | Read a specific resource          |
-| `mcpx prompt`                       | List all prompts across servers   |
-| `mcpx prompt <server>`              | List prompts for a server         |
-| `mcpx prompt <server> <name> '<json>'` | Get a specific prompt          |
-| `mcpx exec <server> <tool> --no-wait` | Execute as async task, return handle |
-| `mcpx exec <server> <tool> --ttl <ms>` | Set task TTL (default: 60000) |
-| `mcpx -N exec <server> <tool> ...`  | Decline elicitation (non-interactive) |
-| `mcpx task list <server>`            | List tasks on a server          |
-| `mcpx task get <server> <taskId>`    | Get task status                 |
-| `mcpx task result <server> <taskId>` | Retrieve completed task result  |
-| `mcpx task cancel <server> <taskId>` | Cancel a running task           |
+| `mcpx auth <server> --no-index`       | Authenticate without rebuilding index |
+| `mcpx deauth <server>`                | Remove stored authentication      |
+| `mcpx ping`                           | Check connectivity to all servers |
+| `mcpx ping <server> [server2...]`     | Check specific server(s)          |
+| `mcpx add <name> --command <cmd>`     | Add a stdio MCP server            |
+| `mcpx add <name> --url <url>`         | Add an HTTP MCP server            |
+| `mcpx remove <name>`                  | Remove an MCP server              |
+| `mcpx skill install --claude`         | Install mcpx skill for Claude     |
+| `mcpx skill install --cursor`         | Install mcpx rule for Cursor      |
+| `mcpx resource`                       | List all resources across servers |
+| `mcpx resource <server>`              | List resources for a server       |
+| `mcpx resource <server> <uri>`        | Read a specific resource          |
+| `mcpx prompt`                         | List all prompts across servers   |
+| `mcpx prompt <server>`                | List prompts for a server         |
+| `mcpx prompt <server> <name> '<json>'` | Get a specific prompt            |
+| `mcpx task list <server>`             | List tasks on a server            |
+| `mcpx task get <server> <taskId>`     | Get task status                   |
+| `mcpx task result <server> <taskId>`  | Retrieve completed task result    |
+| `mcpx task cancel <server> <taskId>`  | Cancel a running task             |
+
+## Global flags
+
+| Flag                        | Purpose                                                  |
+| --------------------------- | -------------------------------------------------------- |
+| `-j, --json`                | Force JSON output (default when piped)                   |
+| `-F, --format <format>`     | Output format: `json`, `text`, or `markdown`             |
+| `-v, --verbose`             | Show HTTP details and JSON-RPC protocol messages         |
+| `-d, --with-descriptions`   | Include tool descriptions in list output                 |
+| `-c, --config <path>`       | Specify config file location                             |
+| `-N, --no-interactive`      | Decline server elicitation requests (for scripted usage) |
+| `-S, --show-secrets`        | Show full auth tokens in verbose output (unmasked)       |
+| `-l, --log-level <level>`   | Minimum server log level to display (default: `warning`) |
+
+## `add` options
+
+| Flag                       | Purpose                                |
+| -------------------------- | -------------------------------------- |
+| `--command <cmd>`          | Command to run (stdio server)          |
+| `--args <a1,a2,...>`       | Comma-separated arguments              |
+| `--env <KEY=VAL,...>`      | Comma-separated environment variables  |
+| `--cwd <dir>`              | Working directory for the command      |
+| `--url <url>`              | Server URL (HTTP server)               |
+| `--header <Key:Value>`     | HTTP header (repeatable)               |
+| `--transport <type>`       | Transport: `sse` or `streamable-http`  |
+| `--allowed-tools <t1,t2>`  | Comma-separated allowed tool patterns  |
+| `--disabled-tools <t1,t2>` | Comma-separated disabled tool patterns |
+| `-f, --force`              | Overwrite if server already exists     |
+| `--no-auth`                | Skip automatic OAuth after adding      |
+| `--no-index`               | Skip rebuilding the search index       |
+
+## `remove` options
+
+| Flag          | Purpose                                          |
+| ------------- | ------------------------------------------------ |
+| `--keep-auth` | Don't remove stored auth credentials             |
+| `--dry-run`   | Show what would be removed without changing files |
+
+## `skill install` options
+
+| Flag        | Purpose                                    |
+| ----------- | ------------------------------------------ |
+| `--claude`  | Install skill for Claude Code              |
+| `--cursor`  | Install rule for Cursor                    |
+| `--global`  | Install to global location (`~/`)          |
+| `--project` | Install to project location (default)      |
+| `-f, --force` | Overwrite if file already exists         |
+
+## Environment variables
+
+| Variable          | Purpose                     | Default    |
+| ----------------- | --------------------------- | ---------- |
+| `MCP_CONFIG_PATH` | Config directory path       | `~/.mcpx/` |
+| `MCP_TIMEOUT`     | Request timeout (seconds)   | `1800`     |
+| `MCP_CONCURRENCY` | Parallel server connections | `5`        |
+| `MCP_MAX_RETRIES` | Retry attempts              | `3`        |
+| `MCP_STRICT_ENV`  | Error on missing `${VAR}`   | `true`     |
+| `MCP_DEBUG`       | Enable debug output         | `false`    |

package/README.md

@@ -107,6 +107,7 @@ mcpx search -n 5 "manage pull requests"
 | `-v, --verbose`           | Show HTTP details and JSON-RPC protocol messages         |
 | `-S, --show-secrets`      | Show full auth tokens in verbose output (unmasked)       |
 | `-j, --json`              | Force JSON output (default when piped)                   |
+| `-F, --format <format>`   | Output format: `json`, `text`, or `markdown`             |
 | `-N, --no-interactive`    | Decline server elicitation requests (for scripted usage) |
 | `-l, --log-level <level>` | Minimum server log level to display (default: `warning`) |
 
@@ -495,7 +496,36 @@ mcpx info github | jq '.tools[].name'
 mcpx info github --json
 ```
 
-Tool results are always JSON, designed for chaining:
+### Output Formats (`--format`)
+
+Tool results (`exec`, `task result`) support three output formats via the global `--format` / `-F` flag:
+
+| Format     | Description                                                             |
+| ---------- | ----------------------------------------------------------------------- |
+| `json`     | Full MCP protocol response as JSON (default)                            |
+| `text`     | Extract text from content blocks, strip protocol wrapper                |
+| `markdown` | Extract text and render with rich terminal formatting (colors, borders) |
+
+```bash
+# Default JSON output — full MCP response with content array
+mcpx exec github search_repositories '{"query":"mcp"}'
+
+# Text — just the content, no protocol wrapper
+mcpx exec github search_repositories '{"query":"mcp"}' --format text
+
+# Markdown — rich terminal rendering with colors and formatting
+mcpx exec github search_repositories '{"query":"mcp"}' -F markdown
+```
+
+The `text` format extracts text from MCP content blocks and strips the protocol wrapper. If the text contains JSON, it's pretty-printed. Non-text content (images, resources) gets descriptive placeholders.
+
+The `markdown` format extracts text the same way, then renders it through Bun's built-in markdown parser with ANSI styling — headings, bold/italic, code blocks with borders, colored links, and bullet lists.
+
+For other commands (`list`, `info`, `search`), `--format json` forces JSON output and `--format text`/`--format markdown` use the existing human-friendly formatting.
+
+### Chaining tool results
+
+Tool results are JSON by default, designed for chaining:
 
 ```bash
 # Search repos and read the first result

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@evantahler/mcpx",
-  "version": "0.15.9",
+  "version": "0.16.1",
   "description": "A command-line interface for MCP servers. curl for MCP.",
   "type": "module",
   "bin": {

package/src/cli.ts

@@ -25,6 +25,7 @@ program
   .option("-c, --config <path>", "config directory path")
   .option("-d, --with-descriptions", "include tool descriptions in output")
   .option("-j, --json", "force JSON output")
+  .option("-F, --format <format>", "output format (json, text, markdown)")
   .option("-v, --verbose", "show HTTP details and JSON-RPC protocol messages")
   .option("-S, --show-secrets", "show full auth tokens in verbose output")
   .option("-N, --no-interactive", "decline server elicitation requests")
@@ -56,7 +57,14 @@ const cliArgs = process.argv.slice(2);
 let firstCommand: string | undefined;
 for (let i = 0; i < cliArgs.length; i++) {
   const a = cliArgs[i];
-  if (a === "-c" || a === "--config" || a === "-l" || a === "--log-level") {
+  if (
+    a === "-c" ||
+    a === "--config" ||
+    a === "-l" ||
+    a === "--log-level" ||
+    a === "-F" ||
+    a === "--format"
+  ) {
     i++; // skip the option's value argument
     continue;
   }

package/src/context.ts

@@ -2,7 +2,7 @@ import type { Command } from "commander";
 import { loadConfig, type LoadConfigOptions } from "./config/loader.ts";
 import { ServerManager } from "./client/manager.ts";
 import type { Config } from "./config/schemas.ts";
-import type { FormatOptions } from "./output/formatter.ts";
+import { type FormatOptions, type OutputFormat, VALID_FORMATS } from "./output/formatter.ts";
 import { logger } from "./output/logger.ts";
 import { ENV, DEFAULTS } from "./constants.ts";
 
@@ -35,6 +35,13 @@ export async function getContext(program: Command): Promise<AppContext> {
   // Commander's --no-interactive sets opts.interactive = false (default true)
   const noInteractive = opts.interactive === false;
 
+  const formatFlag = opts.format as string | undefined;
+  if (formatFlag && !VALID_FORMATS.includes(formatFlag as OutputFormat)) {
+    console.error(`error: Invalid format "${formatFlag}". Use: ${VALID_FORMATS.join(", ")}`);
+    process.exit(1);
+  }
+  const format = formatFlag as OutputFormat | undefined;
+
   const manager = new ServerManager({
     servers: config.servers,
     configDir: config.configDir,
@@ -55,6 +62,7 @@ export async function getContext(program: Command): Promise<AppContext> {
     verbose,
     showSecrets,
     logLevel,
+    format,
   };
 
   logger.configure(formatOptions);

package/src/output/format-output.ts

@@ -3,14 +3,24 @@ import { isInteractive } from "./formatter.ts";
 
 /**
  * Format output with automatic JSON/interactive branching.
- * In non-interactive mode, returns JSON.stringify of jsonData.
- * In interactive mode, calls interactiveFn() for formatted output.
+ * When --format is explicitly set, it takes precedence:
+ *   json → JSON.stringify of jsonData
+ *   text or markdown → interactiveFn() (already well-formatted for non-exec commands)
+ * Otherwise falls back to the existing auto-detection:
+ *   non-interactive → JSON, interactive → formatted text.
  */
 export function formatOutput(
   jsonData: unknown,
   interactiveFn: () => string,
   options: FormatOptions,
 ): string {
+  if (options.format) {
+    if (options.format === "json") {
+      return JSON.stringify(jsonData, null, 2);
+    }
+    // text and markdown use the interactive formatter for non-exec commands
+    return interactiveFn();
+  }
   if (!isInteractive(options)) {
     return JSON.stringify(jsonData, null, 2);
   }

package/src/output/formatter.ts

@@ -6,12 +6,17 @@ import type { SearchResult } from "../search/index.ts";
 import { formatOutput } from "./format-output.ts";
 import { formatTable } from "./format-table.ts";
 
+export const VALID_FORMATS = ["json", "text", "markdown"] as const;
+
+export type OutputFormat = (typeof VALID_FORMATS)[number];
+
 export interface FormatOptions {
   json?: boolean;
   withDescriptions?: boolean;
   verbose?: boolean;
   showSecrets?: boolean;
   logLevel?: string;
+  format?: OutputFormat;
 }
 
 export interface UnifiedItem {
@@ -345,9 +350,201 @@ function exampleValue(name: string, prop: Record<string, unknown>): unknown {
   }
 }
 
-/** Format a tool call result */
-export function formatCallResult(result: unknown, _options: FormatOptions): string {
-  return JSON.stringify(parseNestedJson(result), null, 2);
+/** Format a tool call result, dispatching on the --format option */
+export function formatCallResult(result: unknown, options: FormatOptions): string {
+  const format = options.format ?? "json";
+
+  switch (format) {
+    case "text":
+      return formatCallResultAsText(result);
+    case "markdown":
+      return formatCallResultAsMarkdown(result);
+    case "json":
+    default:
+      return JSON.stringify(parseNestedJson(result), null, 2);
+  }
+}
+
+/** Extract human-readable text from an MCP tool call result */
+function formatCallResultAsText(result: unknown): string {
+  const r = result as {
+    content?: Array<{
+      type: string;
+      text?: string;
+      data?: string;
+      mimeType?: string;
+      uri?: string;
+    }>;
+    isError?: boolean;
+  };
+
+  if (!r.content || !Array.isArray(r.content) || r.content.length === 0) {
+    return JSON.stringify(result, null, 2);
+  }
+
+  const parts: string[] = [];
+
+  for (const block of r.content) {
+    switch (block.type) {
+      case "text":
+        if (block.text !== undefined) {
+          try {
+            const parsed = JSON.parse(block.text);
+            parts.push(JSON.stringify(parsed, null, 2));
+          } catch {
+            parts.push(block.text);
+          }
+        }
+        break;
+      case "image":
+        parts.push(
+          `[image: ${block.mimeType ?? "unknown type"}, ${block.data ? Math.ceil((block.data.length * 3) / 4) : 0} bytes]`,
+        );
+        break;
+      case "resource":
+        parts.push(`[resource: ${block.uri ?? "unknown"}]`);
+        break;
+      default:
+        parts.push(`[${block.type}]`);
+        break;
+    }
+  }
+
+  let output = parts.join("\n");
+  if (r.isError) {
+    output = `error: ${output}`;
+  }
+  return output;
+}
+
+/** Render an MCP tool call result as styled markdown for terminal output */
+function formatCallResultAsMarkdown(result: unknown): string {
+  const r = result as {
+    content?: Array<{
+      type: string;
+      text?: string;
+      data?: string;
+      mimeType?: string;
+      uri?: string;
+    }>;
+    isError?: boolean;
+  };
+
+  if (!r.content || !Array.isArray(r.content) || r.content.length === 0) {
+    return renderMarkdownToAnsi(jsonToMarkdown(result));
+  }
+
+  const parts: string[] = [];
+
+  for (const block of r.content) {
+    switch (block.type) {
+      case "text":
+        if (block.text !== undefined) {
+          try {
+            const parsed = JSON.parse(block.text);
+            parts.push(jsonToMarkdown(parsed));
+          } catch {
+            // Plain text / already markdown — pass through as-is
+            parts.push(block.text);
+          }
+        }
+        break;
+      case "image":
+        parts.push(
+          `[image: ${block.mimeType ?? "unknown type"}, ${block.data ? Math.ceil((block.data.length * 3) / 4) : 0} bytes]`,
+        );
+        break;
+      case "resource":
+        parts.push(`[resource: ${block.uri ?? "unknown"}]`);
+        break;
+      default:
+        parts.push(`[${block.type}]`);
+        break;
+    }
+  }
+
+  let output = parts.join("\n\n");
+  if (r.isError) {
+    output = `**error:** ${output}`;
+  }
+  return renderMarkdownToAnsi(output);
+}
+
+/** Convert a key name like "display_name" to "Display Name" */
+function humanizeKey(key: string): string {
+  return key
+    .replace(/[_-]/g, " ")
+    .replace(/([a-z])([A-Z])/g, "$1 $2")
+    .replace(/\b\w/g, (c) => c.toUpperCase());
+}
+
+/** Check if a value is a plain primitive (string, number, boolean, null) */
+function isPrimitive(value: unknown): value is string | number | boolean | null {
+  return value === null || typeof value !== "object";
+}
+
+/**
+ * Convert a JSON value into a readable markdown document.
+ * Object keys become headings at their nesting depth (depth 1 = #, depth 2 = ##, etc.).
+ * Arrays of primitives become bullet lists. Arrays of objects get numbered sub-sections.
+ * Headings are capped at depth 6 (######); deeper nesting uses **bold** labels instead.
+ */
+export function jsonToMarkdown(value: unknown, depth: number = 1): string {
+  if (isPrimitive(value)) {
+    return String(value ?? "null");
+  }
+
+  if (Array.isArray(value)) {
+    // Array of all primitives → bullet list
+    if (value.every(isPrimitive)) {
+      return value.map((v) => `- ${String(v ?? "null")}`).join("\n");
+    }
+    // Array of objects → numbered sub-sections
+    return value
+      .map((item, i) => {
+        if (isPrimitive(item)) {
+          return `- ${String(item ?? "null")}`;
+        }
+        const label = depth <= 6 ? `${"#".repeat(depth)} ${i + 1}` : `**${i + 1}**`;
+        return `${label}\n\n${jsonToMarkdown(item, depth + 1)}`;
+      })
+      .join("\n\n");
+  }
+
+  // Object → each key becomes a heading
+  const entries = Object.entries(value as Record<string, unknown>);
+  const lines: string[] = [];
+
+  for (const [key, val] of entries) {
+    const heading = humanizeKey(key);
+
+    if (isPrimitive(val)) {
+      if (depth <= 6) {
+        lines.push(`${"#".repeat(depth)} ${heading}\n\n${String(val ?? "null")}`);
+      } else {
+        lines.push(`**${heading}:** ${String(val ?? "null")}`);
+      }
+    } else if (Array.isArray(val) && val.every(isPrimitive)) {
+      // Array of primitives: heading then bullet list
+      const list = val.map((v) => `- ${String(v ?? "null")}`).join("\n");
+      if (depth <= 6) {
+        lines.push(`${"#".repeat(depth)} ${heading}\n\n${list}`);
+      } else {
+        lines.push(`**${heading}:**\n${list}`);
+      }
+    } else {
+      // Nested object or array of objects
+      const label = depth <= 6 ? `${"#".repeat(depth)} ${heading}` : `**${heading}**`;
+      lines.push(`${label}\n\n${jsonToMarkdown(val, depth + 1)}`);
+    }
+  }
+
+  return lines.join("\n\n");
+}
+
+/** Render a markdown string to ANSI-styled terminal output using Bun's built-in renderer */
+export function renderMarkdownToAnsi(input: string): string {
+  return Bun.markdown.ansi(input);
 }
 
 /** Recursively parse JSON strings inside MCP content blocks */