@evantahler/mcpx 0.16.2 → 0.16.4

package/.claude/skills/mcpx.md

@@ -30,7 +30,7 @@ mcpx exec <server> <tool> '<json args>'       # explicit server (required if too
 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.
+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 markdown` for rich terminal rendering with colors, headings, and bullet lists.
 
 ## Rules
 
@@ -39,7 +39,6 @@ Output is JSON by default. 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
@@ -159,7 +158,7 @@ mcpx deauth <server>           # remove stored auth
 | Flag                        | Purpose                                                  |
 | --------------------------- | -------------------------------------------------------- |
 | `-j, --json`                | Force JSON output (default when piped)                   |
-| `-F, --format <format>`     | Output format: `json`, `text`, or `markdown`             |
+| `-F, --format <format>`     | Output format: `json` 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                             |

package/.cursor/rules/mcpx.mdc

@@ -30,7 +30,7 @@ mcpx exec <server> <tool> '<json args>'       # explicit server (required if too
 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.
+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 markdown` for rich terminal rendering with colors, headings, and bullet lists.
 
 ## Rules
 
@@ -39,7 +39,6 @@ Output is JSON by default. 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
@@ -159,7 +158,7 @@ mcpx deauth <server>           # remove stored auth
 | Flag                        | Purpose                                                  |
 | --------------------------- | -------------------------------------------------------- |
 | `-j, --json`                | Force JSON output (default when piped)                   |
-| `-F, --format <format>`     | Output format: `json`, `text`, or `markdown`             |
+| `-F, --format <format>`     | Output format: `json` 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                             |

package/README.md

@@ -12,14 +12,19 @@ Two audiences:
 ## Install
 
 ```bash
-# Via bun
+# Via bun (all platforms)
 bun install -g @evantahler/mcpx
 
-# Via curl
+# Via curl (macOS/Linux)
 curl -fsSL https://raw.githubusercontent.com/evantahler/mcpx/main/install.sh | bash
 ```
 
-The curl installer downloads a pre-built binary (macOS/Linux) — no runtime needed. The bun install method requires [Bun](https://bun.sh). Windows `.exe` binaries are available on the [GitHub Releases](https://github.com/evantahler/mcpx/releases) page.
+```powershell
+# Via PowerShell (Windows)
+irm https://raw.githubusercontent.com/evantahler/mcpx/main/install.ps1 | iex
+```
+
+The curl/PowerShell installers download a pre-built binary — no runtime needed. The bun install method requires [Bun](https://bun.sh). Binaries for all platforms are also available on the [GitHub Releases](https://github.com/evantahler/mcpx/releases) page.
 
 ## Quick Start
 
@@ -111,7 +116,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`             |
+| `-F, --format <format>`   | Output format: `json` or `markdown`                      |
 | `-N, --no-interactive`    | Decline server elicitation requests (for scripted usage) |
 | `-l, --log-level <level>` | Minimum server log level to display (default: `warning`) |
 
@@ -514,18 +519,13 @@ Tool results (`exec`, `task result`) support three output formats via the global
 # 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.
+The `markdown` format extracts text from MCP content blocks and renders it through Bun's built-in markdown parser with ANSI styling — headings, bold/italic, code blocks with borders, colored links, and bullet lists. JSON content is converted to a structured document with headings 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.
+For other commands (`list`, `info`, `search`), `--format json` forces JSON output and `--format markdown` uses the existing human-friendly formatting.
 
 ### Chaining tool results
 

package/package.json

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

package/src/cli.ts

@@ -25,7 +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("-F, --format <format>", "output format (json, 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")

package/src/output/format-output.ts

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

package/src/output/formatter.ts

@@ -6,7 +6,7 @@ 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 const VALID_FORMATS = ["json", "markdown"] as const;
 
 export type OutputFormat = (typeof VALID_FORMATS)[number];
 
@@ -355,8 +355,6 @@ export function formatCallResult(result: unknown, options: FormatOptions): strin
   const format = options.format ?? "json";
 
   switch (format) {
-    case "text":
-      return formatCallResultAsText(result);
     case "markdown":
       return formatCallResultAsMarkdown(result);
     case "json":
@@ -365,58 +363,6 @@ export function formatCallResult(result: unknown, options: FormatOptions): strin
   }
 }
 
-/** 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 {
@@ -483,30 +429,162 @@ function isPrimitive(value: unknown): value is string | number | boolean | null
   return value === null || typeof value !== "object";
 }
 
+/**
+ * URL placeholders: Bun.markdown.ansi() wraps and auto-links URLs, so we
+ * replace them with short tokens before rendering, then swap them back after.
+ */
+let urlCounter = 0;
+let urlMap = new Map<string, string>();
+
+function resetUrlPlaceholders(): void {
+  urlCounter = 0;
+  urlMap = new Map();
+}
+
+function restoreUrlPlaceholders(ansiOutput: string): string {
+  for (const [token, url] of urlMap) {
+    ansiOutput = ansiOutput.replace(token, `\x1b[34m\x1b[4m${url}\x1b[24m\x1b[39m`);
+  }
+  return ansiOutput;
+}
+
+/** Format a primitive value, replacing URLs with placeholders to avoid mangling */
+function formatPrimitive(value: string | number | boolean | null): string {
+  const str = String(value ?? "null");
+  if (typeof value === "string" && /^https?:\/\/\S+$/.test(value)) {
+    const token = `URLPLACEHOLDER${urlCounter++}`;
+    urlMap.set(token, str);
+    return token;
+  }
+  return str;
+}
+
+/** Normalize a key for label matching: lowercase, strip underscores/hyphens */
+function normalizeKey(key: string): string {
+  return key.replace(/[_-]/g, "").toLowerCase();
+}
+
+/** Priority-ordered label keys (checked after normalization) */
+const LABEL_KEYS = [
+  "name",
+  "displayname",
+  "fullname",
+  "username",
+  "screenname",
+  "title",
+  "subject",
+  "headline",
+  "heading",
+  "label",
+  "description",
+  "summary",
+  "email",
+  "url",
+  "slug",
+  "key",
+  "identifier",
+];
+
+/** Find the best label field in an object, returning { originalKey, value } or null */
+function findLabel(obj: Record<string, unknown>): { originalKey: string; value: string } | null {
+  const entries = Object.entries(obj);
+  for (const candidate of LABEL_KEYS) {
+    for (const [key, val] of entries) {
+      if (normalizeKey(key) === candidate && typeof val === "string" && val.length > 0) {
+        return { originalKey: key, value: val };
+      }
+    }
+  }
+  return null;
+}
+
+/** Render object entries as an indented bullet list */
+function objectToBullets(entries: [string, unknown][], indent: number, skipKey?: string): string {
+  const prefix = " ".repeat(indent);
+  const lines: string[] = [];
+
+  for (const [key, val] of entries) {
+    if (key === skipKey) continue;
+    const heading = humanizeKey(key);
+
+    if (isPrimitive(val)) {
+      lines.push(`${prefix}- **${heading}:** ${formatPrimitive(val)}`);
+    } else if (Array.isArray(val) && val.every(isPrimitive)) {
+      lines.push(`${prefix}- **${heading}:**`);
+      for (const v of val) {
+        lines.push(`${prefix}  - ${formatPrimitive(v)}`);
+      }
+    } else if (Array.isArray(val)) {
+      lines.push(`${prefix}- **${heading}:**`);
+      for (const item of val) {
+        if (isPrimitive(item)) {
+          lines.push(`${prefix}  - ${formatPrimitive(item)}`);
+        } else {
+          const itemObj = item as Record<string, unknown>;
+          const label = findLabel(itemObj);
+          if (label) {
+            lines.push(`${prefix}  - ${label.value}`);
+            lines.push(objectToBullets(Object.entries(itemObj), indent + 4, label.originalKey));
+          } else {
+            lines.push(`${prefix}  -`);
+            lines.push(objectToBullets(Object.entries(itemObj), indent + 4));
+          }
+        }
+      }
+    } else {
+      lines.push(`${prefix}- **${heading}:**`);
+      lines.push(objectToBullets(Object.entries(val as Record<string, unknown>), indent + 2));
+    }
+  }
+
+  return lines.join("\n");
+}
+
 /**
  * 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.
+ * Depth 1–2 use headings; depth 3+ switch to compact bullet lists.
+ * Arrays of objects use a label field (name, title, etc.) in the heading when available.
  */
-export function jsonToMarkdown(value: unknown, depth: number = 1): string {
+export function jsonToMarkdown(value: unknown, depth: number = 1, skipKey?: string): string {
   if (isPrimitive(value)) {
-    return String(value ?? "null");
+    return formatPrimitive(value);
+  }
+
+  // At depth >= 3, switch to bullet-list rendering
+  if (depth >= 3) {
+    if (Array.isArray(value)) {
+      if (value.every(isPrimitive)) {
+        return value.map((v) => `- ${formatPrimitive(v)}`).join("\n");
+      }
+      return value
+        .map((item) => {
+          if (isPrimitive(item)) return `- ${formatPrimitive(item)}`;
+          const obj = item as Record<string, unknown>;
+          const label = findLabel(obj);
+          const header = label ? `- ${label.value}` : `-`;
+          return `${header}\n${objectToBullets(Object.entries(obj), 2, label?.originalKey)}`;
+        })
+        .join("\n");
+    }
+    return objectToBullets(Object.entries(value as Record<string, unknown>), 0, skipKey);
   }
 
   if (Array.isArray(value)) {
     // Array of all primitives → bullet list
     if (value.every(isPrimitive)) {
-      return value.map((v) => `- ${String(v ?? "null")}`).join("\n");
+      return value.map((v) => `- ${formatPrimitive(v)}`).join("\n");
     }
-    // Array of objects → numbered sub-sections
+    // Array of objects → numbered sub-sections with label
     return value
       .map((item, i) => {
         if (isPrimitive(item)) {
-          return `- ${String(item ?? "null")}`;
+          return `- ${formatPrimitive(item)}`;
         }
-        const label = depth <= 6 ? `${"#".repeat(depth)} ${i + 1}` : `**${i + 1}**`;
-        return `${label}\n\n${jsonToMarkdown(item, depth + 1)}`;
+        const obj = item as Record<string, unknown>;
+        const labelInfo = findLabel(obj);
+        const numberLabel = labelInfo ? `${i + 1}. ${labelInfo.value}` : `${i + 1}`;
+        const heading = depth <= 6 ? `${"#".repeat(depth)} ${numberLabel}` : `**${numberLabel}**`;
+        return `${heading}\n\n${jsonToMarkdown(item, depth + 1, labelInfo?.originalKey)}`;
       })
       .join("\n\n");
   }
@@ -520,13 +598,13 @@ export function jsonToMarkdown(value: unknown, depth: number = 1): string {
 
     if (isPrimitive(val)) {
       if (depth <= 6) {
-        lines.push(`${"#".repeat(depth)} ${heading}\n\n${String(val ?? "null")}`);
+        lines.push(`${"#".repeat(depth)} ${heading}\n\n${formatPrimitive(val)}`);
       } else {
-        lines.push(`**${heading}:** ${String(val ?? "null")}`);
+        lines.push(`**${heading}:** ${formatPrimitive(val)}`);
       }
     } 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");
+      const list = val.map((v) => `- ${formatPrimitive(v)}`).join("\n");
       if (depth <= 6) {
         lines.push(`${"#".repeat(depth)} ${heading}\n\n${list}`);
       } else {
@@ -544,7 +622,10 @@ export function jsonToMarkdown(value: unknown, depth: number = 1): string {
 
 /** 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);
+  const result = Bun.markdown.ansi(input);
+  const restored = restoreUrlPlaceholders(result);
+  resetUrlPlaceholders();
+  return restored;
 }
 
 /** Recursively parse JSON strings inside MCP content blocks */