@evantahler/mcpx 0.16.3 → 0.17.0

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
@@ -153,13 +152,15 @@ mcpx deauth <server>           # remove stored auth
 | `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 check-update`                  | Check for a newer version of mcpx |
+| `mcpx upgrade`                       | Upgrade mcpx to the latest version|
 
 ## Global flags
 
 | 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
@@ -153,13 +152,15 @@ mcpx deauth <server>           # remove stored auth
 | `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 check-update`                  | Check for a newer version of mcpx |
+| `mcpx upgrade`                       | Upgrade mcpx to the latest version|
 
 ## Global flags
 
 | 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

@@ -104,6 +104,8 @@ mcpx search -n 5 "manage pull requests"
 | `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 check-update`                    | Check for a newer version of mcpx                      |
+| `mcpx upgrade`                         | Upgrade mcpx to the latest version                     |
 
 ## Options
 
@@ -116,7 +118,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`) |
 
@@ -519,18 +521,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.3",
+  "version": "0.17.0",
   "description": "A command-line interface for MCP servers. curl for MCP.",
   "type": "module",
   "bin": {

package/src/cli.ts

@@ -15,6 +15,9 @@ import { registerResourceCommand } from "./commands/resource.ts";
 import { registerPromptCommand } from "./commands/prompt.ts";
 import { registerServersCommand } from "./commands/servers.ts";
 import { registerTaskCommand } from "./commands/task.ts";
+import { registerCheckUpdateCommand } from "./commands/check-update.ts";
+import { registerUpgradeCommand } from "./commands/upgrade.ts";
+import { maybeCheckForUpdate } from "./update/background.ts";
 
 import pkg from "../package.json";
 
@@ -25,7 +28,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")
@@ -50,6 +53,8 @@ registerResourceCommand(program);
 registerPromptCommand(program);
 registerServersCommand(program);
 registerTaskCommand(program);
+registerCheckUpdateCommand(program);
+registerUpgradeCommand(program);
 
 // Detect unknown subcommands before commander misreports them as "too many arguments"
 const knownCommands = new Set(program.commands.map((c) => c.name()));
@@ -77,4 +82,13 @@ if (firstCommand && !knownCommands.has(firstCommand)) {
   process.exit(1);
 }
 
+// Fire-and-forget background update check
+const updateNotice = maybeCheckForUpdate();
+
 program.parse();
+
+// Print update notice after command output completes
+process.on("beforeExit", async () => {
+  const notice = await updateNotice;
+  if (notice) process.stderr.write(notice);
+});

package/src/commands/check-update.ts

@@ -0,0 +1,70 @@
+import { green, yellow, cyan, dim } from "ansis";
+import type { Command } from "commander";
+import { createSpinner } from "nanospinner";
+import pkg from "../../package.json";
+import { checkForUpdate } from "../update/checker.ts";
+import { saveUpdateCache } from "../update/cache.ts";
+import type { UpdateCache } from "../update/checker.ts";
+
+export function registerCheckUpdateCommand(program: Command) {
+  program
+    .command("check-update")
+    .description("Check for a newer version of mcpx")
+    .action(async () => {
+      const opts = program.opts();
+      const json = !!(opts.json as boolean | undefined);
+      const isTTY = process.stderr.isTTY ?? false;
+
+      const spinner =
+        !json && isTTY
+          ? createSpinner("Checking for updates...", { stream: process.stderr }).start()
+          : null;
+
+      try {
+        const info = await checkForUpdate(pkg.version);
+
+        // Save to cache
+        const cache: UpdateCache = {
+          lastCheckAt: new Date().toISOString(),
+          latestVersion: info.latestVersion,
+          hasUpdate: info.hasUpdate,
+          changelog: info.changelog,
+        };
+        await saveUpdateCache(cache);
+
+        spinner?.stop();
+
+        if (json) {
+          console.log(JSON.stringify(info, null, 2));
+          return;
+        }
+
+        if (!info.hasUpdate) {
+          if (info.aheadOfLatest) {
+            console.log(
+              yellow(
+                `mcpx v${info.currentVersion} is ahead of latest published release (v${info.latestVersion})`,
+              ),
+            );
+          } else {
+            console.log(green(`mcpx is up to date (v${info.currentVersion})`));
+          }
+          return;
+        }
+
+        console.log(yellow(`Update available: ${info.currentVersion} → ${info.latestVersion}`));
+
+        if (info.changelog) {
+          console.log("");
+          console.log(dim(info.changelog));
+        }
+
+        console.log("");
+        console.log(cyan(`Run \`mcpx upgrade\` to update`));
+      } catch (err) {
+        spinner?.error({ text: "Failed to check for updates" });
+        console.error(String(err));
+        process.exit(1);
+      }
+    });
+}

package/src/commands/upgrade.ts

@@ -0,0 +1,226 @@
+import { $ } from "bun";
+import { green, yellow, red, cyan, dim } from "ansis";
+import type { Command } from "commander";
+import { createSpinner } from "nanospinner";
+import { tmpdir } from "os";
+import { join } from "path";
+import pkg from "../../package.json";
+import {
+  checkForUpdate,
+  detectInstallMethod,
+  needsCheck,
+  type InstallMethod,
+} from "../update/checker.ts";
+import { loadUpdateCache, saveUpdateCache, clearUpdateCache } from "../update/cache.ts";
+import type { UpdateCache } from "../update/checker.ts";
+import pkgMeta from "../../package.json";
+
+const GITHUB_REPO = pkgMeta.repository.url
+  .replace(/^https:\/\/github\.com\//, "")
+  .replace(/\.git$/, "");
+
+function platformArtifactName(): string {
+  let os: string;
+  let ext = "";
+  switch (process.platform) {
+    case "darwin":
+      os = "darwin";
+      break;
+    case "win32":
+      os = "windows";
+      ext = ".exe";
+      break;
+    default:
+      os = "linux";
+      break;
+  }
+  const arch = process.arch === "arm64" ? "arm64" : "x64";
+  return `mcpx-${os}-${arch}${ext}`;
+}
+
+async function upgradeWithPackageManager(command: string, args: string[]): Promise<boolean> {
+  const result = await $`${command} ${args}`.nothrow();
+  return result.exitCode === 0;
+}
+
+async function upgradeFromBinary(latestVersion: string): Promise<boolean> {
+  const artifact = platformArtifactName();
+  const tag = `v${latestVersion}`;
+  const url = `https://github.com/${GITHUB_REPO}/releases/download/${tag}/${artifact}`;
+
+  const tmpPath = join(tmpdir(), `mcpx-upgrade-${Date.now()}`);
+  const targetPath = process.execPath;
+
+  try {
+    const res = await fetch(url);
+    if (!res.ok) {
+      console.error(red(`Failed to download binary: HTTP ${res.status}`));
+      return false;
+    }
+
+    const bytes = await res.arrayBuffer();
+    await Bun.write(tmpPath, bytes);
+
+    await $`chmod +x ${tmpPath}`.quiet();
+
+    // Try to move into place
+    const mv = await $`mv ${tmpPath} ${targetPath}`.quiet().nothrow();
+
+    if (mv.exitCode !== 0) {
+      // Try with sudo
+      console.log(dim("Requires elevated permissions..."));
+      const sudo = await $`sudo mv ${tmpPath} ${targetPath}`.nothrow();
+      if (sudo.exitCode !== 0) {
+        console.error(red("Failed to install binary. Try running with sudo."));
+        return false;
+      }
+    }
+
+    return true;
+  } catch (err) {
+    console.error(red(`Failed to upgrade binary: ${err}`));
+    // Clean up temp file
+    await $`rm -f ${tmpPath}`.quiet().nothrow();
+    return false;
+  }
+}
+
+export function registerUpgradeCommand(program: Command) {
+  program
+    .command("upgrade")
+    .description("Upgrade mcpx to the latest version")
+    .action(async () => {
+      const opts = program.opts();
+      const json = !!(opts.json as boolean | undefined);
+      const isTTY = process.stderr.isTTY ?? false;
+
+      const spinner =
+        !json && isTTY
+          ? createSpinner("Checking for updates...", { stream: process.stderr }).start()
+          : null;
+
+      try {
+        // Check for update (use cache if fresh)
+        const cache = await loadUpdateCache();
+        let latestVersion: string;
+        let hasUpdate: boolean;
+
+        if (!needsCheck(cache) && cache) {
+          latestVersion = cache.latestVersion;
+          hasUpdate = cache.hasUpdate;
+        } else {
+          const info = await checkForUpdate(pkg.version);
+          latestVersion = info.latestVersion;
+          hasUpdate = info.hasUpdate;
+
+          const newCache: UpdateCache = {
+            lastCheckAt: new Date().toISOString(),
+            latestVersion,
+            hasUpdate,
+            changelog: info.changelog,
+          };
+          await saveUpdateCache(newCache);
+        }
+
+        if (!hasUpdate) {
+          spinner?.stop();
+          if (json) {
+            console.log(
+              JSON.stringify({
+                upgraded: false,
+                currentVersion: pkg.version,
+                message: "Already up to date",
+              }),
+            );
+          } else {
+            console.log(green(`mcpx is already up to date (v${pkg.version})`));
+          }
+          return;
+        }
+
+        const method: InstallMethod = detectInstallMethod();
+        spinner?.update({
+          text: `Upgrading from v${pkg.version} to v${latestVersion} (${method})...`,
+        });
+
+        let success = false;
+
+        switch (method) {
+          case "bun":
+            spinner?.stop();
+            success = await upgradeWithPackageManager("bun", [
+              "install",
+              "-g",
+              `@evantahler/mcpx@${latestVersion}`,
+            ]);
+            break;
+
+          case "npm":
+            spinner?.stop();
+            success = await upgradeWithPackageManager("npm", [
+              "install",
+              "-g",
+              `@evantahler/mcpx@${latestVersion}`,
+            ]);
+            break;
+
+          case "binary":
+            spinner?.stop();
+            success = await upgradeFromBinary(latestVersion);
+            break;
+
+          case "local-dev":
+            spinner?.stop();
+            if (json) {
+              console.log(
+                JSON.stringify({
+                  upgraded: false,
+                  currentVersion: pkg.version,
+                  latestVersion,
+                  installMethod: "local-dev",
+                  message: "Running from source. Use `git pull && bun install` to update.",
+                }),
+              );
+            } else {
+              console.log(yellow("Running from source. Use `git pull && bun install` to update."));
+            }
+            return;
+        }
+
+        if (success) {
+          await clearUpdateCache();
+          if (json) {
+            console.log(
+              JSON.stringify({
+                upgraded: true,
+                previousVersion: pkg.version,
+                newVersion: latestVersion,
+                installMethod: method,
+              }),
+            );
+          } else {
+            console.log(green(`Successfully upgraded mcpx: v${pkg.version} → v${latestVersion}`));
+          }
+        } else {
+          if (json) {
+            console.log(
+              JSON.stringify({
+                upgraded: false,
+                currentVersion: pkg.version,
+                latestVersion,
+                installMethod: method,
+                message: "Upgrade failed",
+              }),
+            );
+          } else {
+            console.error(red("Upgrade failed. See errors above."));
+          }
+          process.exit(1);
+        }
+      } catch (err) {
+        spinner?.error({ text: "Upgrade failed" });
+        console.error(String(err));
+        process.exit(1);
+      }
+    });
+}

package/src/config/loader.ts

@@ -1,7 +1,6 @@
 import { join, resolve } from "path";
-import { homedir } from "os";
 import { interpolateEnv } from "./env.ts";
-import { ENV } from "../constants.ts";
+import { DEFAULT_CONFIG_DIR, ENV } from "../constants.ts";
 import {
   type Config,
   type ServersFile,
@@ -12,8 +11,6 @@ import {
   validateSearchIndex,
 } from "./schemas.ts";
 
-const DEFAULT_CONFIG_DIR = join(homedir(), ".mcpx");
-
 const EMPTY_SERVERS: ServersFile = { mcpServers: {} };
 const EMPTY_AUTH: AuthFile = {};
 const EMPTY_SEARCH_INDEX: SearchIndex = {

package/src/constants.ts

@@ -1,3 +1,9 @@
+import { join } from "path";
+import { homedir } from "os";
+
+/** Default config directory (~/.mcpx) */
+export const DEFAULT_CONFIG_DIR = join(homedir(), ".mcpx");
+
 /** Environment variable names used by mcpx */
 export const ENV = {
   DEBUG: "MCP_DEBUG",
@@ -6,6 +12,7 @@ export const ENV = {
   MAX_RETRIES: "MCP_MAX_RETRIES",
   STRICT_ENV: "MCP_STRICT_ENV",
   CONFIG_PATH: "MCP_CONFIG_PATH",
+  NO_UPDATE_CHECK: "MCPX_NO_UPDATE_CHECK",
 } as const;
 
 /** Default values for configurable options */
@@ -16,4 +23,6 @@ export const DEFAULTS = {
   TASK_TTL_MS: 60_000,
   SEARCH_TOP_K: 10,
   LOG_LEVEL: "warning",
+  UPDATE_CHECK_INTERVAL_MS: 24 * 60 * 60 * 1000,
+  UPDATE_CHECK_TIMEOUT_MS: 5_000,
 } as const;

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 */

package/src/update/background.ts

@@ -0,0 +1,76 @@
+import { yellow, cyan, dim } from "ansis";
+import pkg from "../../package.json";
+import { ENV, DEFAULTS } from "../constants.ts";
+import { checkForUpdate, needsCheck, type UpdateCache } from "./checker.ts";
+import { loadUpdateCache, saveUpdateCache } from "./cache.ts";
+
+/** Format an update notice for stderr output. */
+function formatNotice(currentVersion: string, latestVersion: string, changelog?: string): string {
+  const lines: string[] = ["", yellow(`Update available: ${currentVersion} → ${latestVersion}`)];
+
+  if (changelog) {
+    lines.push("");
+    lines.push(dim(changelog));
+  }
+
+  lines.push("");
+  lines.push(cyan(`Run \`mcpx upgrade\` to update`));
+  lines.push("");
+
+  return lines.join("\n");
+}
+
+/**
+ * Non-blocking background update check. Returns a formatted notice string
+ * if an update is available, or null otherwise. Never throws.
+ */
+export async function maybeCheckForUpdate(): Promise<string | null> {
+  try {
+    // Opt-out via env var
+    if (process.env[ENV.NO_UPDATE_CHECK] === "1") return null;
+
+    // Skip if this is the check-update or upgrade command
+    const args = process.argv.slice(2);
+    const command = args.find((a) => !a.startsWith("-"));
+    if (command === "check-update" || command === "upgrade") return null;
+
+    // Only show in TTY
+    if (!(process.stderr.isTTY ?? false)) return null;
+
+    const cache = await loadUpdateCache();
+
+    if (!needsCheck(cache)) {
+      // Cache is fresh — use cached result
+      if (cache?.hasUpdate) {
+        return formatNotice(pkg.version, cache.latestVersion, cache.changelog);
+      }
+      return null;
+    }
+
+    // Cache is stale or missing — check with timeout
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), DEFAULTS.UPDATE_CHECK_TIMEOUT_MS);
+
+    try {
+      const info = await checkForUpdate(pkg.version, controller.signal);
+
+      const newCache: UpdateCache = {
+        lastCheckAt: new Date().toISOString(),
+        latestVersion: info.latestVersion,
+        hasUpdate: info.hasUpdate,
+        changelog: info.changelog,
+      };
+      await saveUpdateCache(newCache);
+
+      if (info.hasUpdate) {
+        return formatNotice(pkg.version, info.latestVersion, info.changelog);
+      }
+    } finally {
+      clearTimeout(timeout);
+    }
+
+    return null;
+  } catch {
+    return null;
+  }
+}

package/src/update/cache.ts

@@ -0,0 +1,37 @@
+import { join } from "path";
+import { DEFAULT_CONFIG_DIR } from "../constants.ts";
+import type { UpdateCache } from "./checker.ts";
+
+const UPDATE_CACHE_PATH = join(DEFAULT_CONFIG_DIR, "update.json");
+
+/** Load the cached update check result, if it exists. */
+export async function loadUpdateCache(): Promise<UpdateCache | undefined> {
+  try {
+    const file = Bun.file(UPDATE_CACHE_PATH);
+    if (!(await file.exists())) return undefined;
+    return JSON.parse(await file.text()) as UpdateCache;
+  } catch {
+    return undefined;
+  }
+}
+
+/** Save update check result to the cache file. */
+export async function saveUpdateCache(cache: UpdateCache): Promise<void> {
+  try {
+    await Bun.write(UPDATE_CACHE_PATH, JSON.stringify(cache, null, 2) + "\n");
+  } catch {
+    // Ignore write failures (e.g. permissions)
+  }
+}
+
+/** Remove the cached update check result. */
+export async function clearUpdateCache(): Promise<void> {
+  try {
+    const file = Bun.file(UPDATE_CACHE_PATH);
+    if (await file.exists()) {
+      await Bun.write(UPDATE_CACHE_PATH, "");
+    }
+  } catch {
+    // Ignore
+  }
+}

package/src/update/checker.ts

@@ -0,0 +1,122 @@
+import pkg from "../../package.json";
+import { DEFAULTS } from "../constants.ts";
+
+const NPM_REGISTRY_URL = `https://registry.npmjs.org/${pkg.name}/latest`;
+const GITHUB_REPO = pkg.repository.url
+  .replace(/^https:\/\/github\.com\//, "")
+  .replace(/\.git$/, "");
+
+export interface UpdateInfo {
+  currentVersion: string;
+  latestVersion: string;
+  hasUpdate: boolean;
+  aheadOfLatest: boolean;
+  changelog?: string;
+}
+
+export interface UpdateCache {
+  lastCheckAt: string;
+  latestVersion: string;
+  hasUpdate: boolean;
+  changelog?: string;
+}
+
+export type InstallMethod = "npm" | "bun" | "binary" | "local-dev";
+
+/** Compare two semver strings. Returns true if latest > current. */
+export function isNewerVersion(current: string, latest: string): boolean {
+  return Bun.semver.order(current, latest) === -1;
+}
+
+/** Fetch the latest version from the npm registry. */
+export async function fetchLatestVersion(signal?: AbortSignal): Promise<string> {
+  try {
+    const res = await fetch(NPM_REGISTRY_URL, { signal });
+    if (!res.ok) return pkg.version;
+    const data = (await res.json()) as { version: string };
+    return data.version;
+  } catch {
+    return pkg.version;
+  }
+}
+
+/** Fetch changelog from GitHub releases between two versions. */
+export async function fetchChangelog(
+  fromVersion: string,
+  toVersion: string,
+  signal?: AbortSignal,
+): Promise<string | undefined> {
+  try {
+    const res = await fetch(`https://api.github.com/repos/${GITHUB_REPO}/releases?per_page=20`, {
+      signal,
+      headers: { Accept: "application/vnd.github.v3+json" },
+    });
+    if (!res.ok) return undefined;
+
+    const releases = (await res.json()) as Array<{
+      tag_name: string;
+      body: string | null;
+    }>;
+
+    const relevant = releases.filter((r) => {
+      const v = r.tag_name.replace(/^v/, "");
+      return isNewerVersion(fromVersion, v) && !isNewerVersion(toVersion, v);
+    });
+
+    if (relevant.length === 0) return undefined;
+
+    return relevant
+      .map((r) => `## ${r.tag_name}\n${r.body ?? ""}`)
+      .join("\n\n")
+      .trim();
+  } catch {
+    return undefined;
+  }
+}
+
+/** Check npm for a newer version and fetch changelog if available. */
+export async function checkForUpdate(
+  currentVersion: string,
+  signal?: AbortSignal,
+): Promise<UpdateInfo> {
+  const latestVersion = await fetchLatestVersion(signal);
+  const hasUpdate = isNewerVersion(currentVersion, latestVersion);
+  const aheadOfLatest = isNewerVersion(latestVersion, currentVersion);
+
+  let changelog: string | undefined;
+  if (hasUpdate) {
+    changelog = await fetchChangelog(currentVersion, latestVersion, signal);
+  }
+
+  return { currentVersion, latestVersion, hasUpdate, aheadOfLatest, changelog };
+}
+
+/** Returns true if the cache is missing or older than 24 hours. */
+export function needsCheck(cache?: UpdateCache): boolean {
+  if (!cache?.lastCheckAt) return true;
+  return Date.now() - new Date(cache.lastCheckAt).getTime() > DEFAULTS.UPDATE_CHECK_INTERVAL_MS;
+}
+
+/** Detect how mcpx was installed. */
+export function detectInstallMethod(): InstallMethod {
+  const script = process.argv[1] ?? "";
+  const execPath = process.execPath;
+
+  // Local dev: running src/cli.ts directly outside node_modules
+  if (script.includes("src/cli.ts") && !script.includes("node_modules")) {
+    return "local-dev";
+  }
+
+  // Compiled binary: execPath is the binary itself (not bun/node)
+  if (!execPath.includes("bun") && !execPath.includes("node")) {
+    return "binary";
+  }
+
+  // Bun global install: path contains .bun/install
+  if (script.includes(".bun/install") || script.includes(".bun/bin")) {
+    return "bun";
+  }
+
+  // npm global install: fallback for node_modules paths
+  return "npm";
+}