@evantahler/mcpx 0.15.3 → 0.15.8

package/src/commands/resource.ts

@@ -1,46 +1,42 @@
 import type { Command } from "commander";
-import { getContext } from "../context.ts";
 import {
   formatResourceList,
   formatServerResources,
   formatResourceContents,
   formatError,
 } from "../output/formatter.ts";
-import { logger } from "../output/logger.ts";
+import { withCommand } from "./with-command.ts";
 
 export function registerResourceCommand(program: Command) {
   program
     .command("resource [server] [uri]")
     .description("list resources for a server, or read a specific resource")
-    .action(async (server: string | undefined, uri: string | undefined) => {
-      const { manager, formatOptions } = await getContext(program);
-      const spinner = logger.startSpinner(
-        server ? `Connecting to ${server}...` : "Connecting to servers...",
-        formatOptions,
-      );
-      try {
-        if (server && uri) {
-          const result = await manager.readResource(server, uri);
-          spinner.stop();
-          console.log(formatResourceContents(server, uri, result, formatOptions));
-        } else if (server) {
-          const resources = await manager.listResources(server);
-          spinner.stop();
-          console.log(formatServerResources(server, resources, formatOptions));
-        } else {
-          const { resources, errors } = await manager.getAllResources();
-          spinner.stop();
-          console.log(formatResourceList(resources, formatOptions));
-          for (const err of errors) {
-            console.error(formatError(`${err.server}: ${err.message}`, formatOptions));
+    .action(
+      withCommand(
+        program,
+        { spinnerText: "Connecting to servers..." },
+        async ({ manager, formatOptions, spinner }, server?: string, uri?: string) => {
+          if (server) {
+            spinner.update(`Connecting to ${server}...`);
           }
-        }
-      } catch (err) {
-        spinner.error("Failed");
-        console.error(formatError(String(err), formatOptions));
-        process.exit(1);
-      } finally {
-        await manager.close();
-      }
-    });
+
+          if (server && uri) {
+            const result = await manager.readResource(server, uri);
+            spinner.stop();
+            console.log(formatResourceContents(server, uri, result, formatOptions));
+          } else if (server) {
+            const resources = await manager.listResources(server);
+            spinner.stop();
+            console.log(formatServerResources(server, resources, formatOptions));
+          } else {
+            const { resources, errors } = await manager.getAllResources();
+            spinner.stop();
+            console.log(formatResourceList(resources, formatOptions));
+            for (const err of errors) {
+              console.error(formatError(`${err.server}: ${err.message}`, formatOptions));
+            }
+          }
+        },
+      ),
+    );
 }

package/src/commands/search.ts

@@ -4,6 +4,7 @@ import { search } from "../search/index.ts";
 import { getStaleServers } from "../search/staleness.ts";
 import { formatError, formatSearchResults } from "../output/formatter.ts";
 import { logger } from "../output/logger.ts";
+import { DEFAULTS } from "../constants.ts";
 
 export function registerSearchCommand(program: Command) {
   program
@@ -11,7 +12,7 @@ export function registerSearchCommand(program: Command) {
     .description("search tools by keyword and/or semantic similarity")
     .option("-k, --keyword", "keyword/glob search only")
     .option("-q, --query", "semantic search only")
-    .option("-n, --limit <number>", "max results to return", "10")
+    .option("-n, --limit <number>", "max results to return", String(DEFAULTS.SEARCH_TOP_K))
     .action(
       async (terms: string[], options: { keyword?: boolean; query?: boolean; limit: string }) => {
         const query = terms.join(" ");

package/src/commands/servers.ts

@@ -1,16 +1,15 @@
 import { cyan, dim, green, yellow } from "ansis";
 import type { Command } from "commander";
-import { getContext } from "../context.ts";
 import { isStdioServer, isHttpServer } from "../config/schemas.ts";
-import { formatError, isInteractive } from "../output/formatter.ts";
+import { isInteractive } from "../output/formatter.ts";
+import { withCommand } from "./with-command.ts";
 
 export function registerServersCommand(program: Command) {
   program
     .command("servers")
     .description("List configured MCP servers")
-    .action(async () => {
-      const { manager, config, formatOptions } = await getContext(program);
-      try {
+    .action(
+      withCommand(program, {}, async ({ config, formatOptions }) => {
         const servers = Object.entries(config.servers.mcpServers);
 
         if (!isInteractive(formatOptions)) {
@@ -56,11 +55,6 @@ export function registerServersCommand(program: Command) {
             : dim(cfg.url);
           console.log(`${n}  ${type}  ${detail}`);
         }
-      } catch (err) {
-        console.error(formatError(String(err), formatOptions));
-        process.exit(1);
-      } finally {
-        await manager.close();
-      }
-    });
+      }),
+    );
 }

package/src/commands/task.ts

@@ -1,82 +1,66 @@
 import type { Command } from "commander";
-import { getContext } from "../context.ts";
 import {
   formatCallResult,
   formatError,
   formatTaskStatus,
   formatTasksList,
 } from "../output/formatter.ts";
-import { logger } from "../output/logger.ts";
+import { withCommand } from "./with-command.ts";
 
 export function registerTaskCommand(program: Command) {
   program
     .command("task <action> <server> [taskId]")
     .description("manage tasks (actions: get, list, result, cancel)")
-    .action(async (action: string, server: string, taskId: string | undefined) => {
-      const { manager, formatOptions } = await getContext(program);
-      const spinner = logger.startSpinner(`Connecting to ${server}...`, formatOptions);
+    .action(
+      withCommand(
+        program,
+        { spinnerText: "Connecting..." },
+        async (
+          { manager, formatOptions, spinner },
+          action: string,
+          server: string,
+          taskId?: string,
+        ) => {
+          spinner.update(`Connecting to ${server}...`);
 
-      try {
-        switch (action) {
-          case "list": {
-            const result = await manager.listTasks(server);
-            spinner.stop();
-            console.log(formatTasksList(result.tasks, result.nextCursor, formatOptions));
-            break;
-          }
-          case "get": {
-            if (!taskId) {
-              spinner.error("Missing task ID");
-              console.error(formatError("Usage: mcpx task get <server> <taskId>", formatOptions));
-              process.exit(1);
+          switch (action) {
+            case "list": {
+              const result = await manager.listTasks(server);
+              spinner.stop();
+              console.log(formatTasksList(result.tasks, result.nextCursor, formatOptions));
+              break;
             }
-            const task = await manager.getTask(server, taskId);
-            spinner.stop();
-            console.log(formatTaskStatus(task, formatOptions));
-            break;
-          }
-          case "result": {
-            if (!taskId) {
-              spinner.error("Missing task ID");
-              console.error(
-                formatError("Usage: mcpx task result <server> <taskId>", formatOptions),
-              );
-              process.exit(1);
+            case "get": {
+              if (!taskId) {
+                throw new Error("Usage: mcpx task get <server> <taskId>");
+              }
+              const task = await manager.getTask(server, taskId);
+              spinner.stop();
+              console.log(formatTaskStatus(task, formatOptions));
+              break;
             }
-            const result = await manager.getTaskResult(server, taskId);
-            spinner.stop();
-            console.log(formatCallResult(result, formatOptions));
-            break;
-          }
-          case "cancel": {
-            if (!taskId) {
-              spinner.error("Missing task ID");
-              console.error(
-                formatError("Usage: mcpx task cancel <server> <taskId>", formatOptions),
-              );
-              process.exit(1);
+            case "result": {
+              if (!taskId) {
+                throw new Error("Usage: mcpx task result <server> <taskId>");
+              }
+              const result = await manager.getTaskResult(server, taskId);
+              spinner.stop();
+              console.log(formatCallResult(result, formatOptions));
+              break;
+            }
+            case "cancel": {
+              if (!taskId) {
+                throw new Error("Usage: mcpx task cancel <server> <taskId>");
+              }
+              const cancelled = await manager.cancelTask(server, taskId);
+              spinner.stop();
+              console.log(formatTaskStatus(cancelled, formatOptions));
+              break;
             }
-            const cancelled = await manager.cancelTask(server, taskId);
-            spinner.stop();
-            console.log(formatTaskStatus(cancelled, formatOptions));
-            break;
+            default:
+              throw new Error(`Unknown task action: "${action}". Use: get, list, result, cancel`);
           }
-          default:
-            spinner.error("Unknown action");
-            console.error(
-              formatError(
-                `Unknown task action: "${action}". Use: get, list, result, cancel`,
-                formatOptions,
-              ),
-            );
-            process.exit(1);
-        }
-      } catch (err) {
-        spinner.error("Failed");
-        console.error(formatError(String(err), formatOptions));
-        process.exit(1);
-      } finally {
-        await manager.close();
-      }
-    });
+        },
+      ),
+    );
 }

package/src/commands/with-command.ts

@@ -0,0 +1,59 @@
+import type { Command } from "commander";
+import { getContext, type AppContext } from "../context.ts";
+import { formatError } from "../output/formatter.ts";
+import { logger, type Spinner } from "../output/logger.ts";
+
+export interface CommandContext extends AppContext {
+  spinner: Spinner;
+}
+
+interface WithCommandOptions {
+  /** Spinner text shown during execution. If omitted, no spinner is started. */
+  spinnerText?: string;
+  /** Error message for spinner.error(). Defaults to "Failed". */
+  errorLabel?: string;
+}
+
+const noopSpinner: Spinner = {
+  update() {},
+  success() {},
+  error() {},
+  stop() {},
+};
+
+/**
+ * Wrap a command action with standard context setup, spinner, error handling,
+ * and manager cleanup.
+ *
+ * The handler receives { config, manager, formatOptions, spinner } and should:
+ *   1. Do async work
+ *   2. Call spinner.stop() when done
+ *   3. Output results via console.log()
+ *
+ * Errors are caught, formatted, and cause process.exit(1).
+ * manager.close() is always called in finally.
+ */
+export function withCommand<TArgs extends unknown[]>(
+  program: Command,
+  options: WithCommandOptions,
+  handler: (ctx: CommandContext, ...args: TArgs) => Promise<void>,
+): (...args: TArgs) => Promise<void> {
+  return async (...args: TArgs) => {
+    const appCtx = await getContext(program);
+    const { manager, formatOptions } = appCtx;
+
+    const spinner = options.spinnerText
+      ? logger.startSpinner(options.spinnerText, formatOptions)
+      : noopSpinner;
+
+    try {
+      await handler({ ...appCtx, spinner }, ...args);
+    } catch (err) {
+      spinner.error(options.errorLabel ?? "Failed");
+      console.error(formatError(String(err), formatOptions));
+      process.exit(1);
+    } finally {
+      await manager.close();
+    }
+  };
+}

package/src/config/env.ts

@@ -1,8 +1,10 @@
+import { ENV } from "../constants.ts";
+
 const ENV_VAR_PATTERN = /\$\{([^}]+)\}/g;
 
 /** Whether to throw on missing env vars (default: true) */
 function isStrictEnv(): boolean {
-  return process.env.MCP_STRICT_ENV !== "false";
+  return process.env[ENV.STRICT_ENV] !== "false";
 }
 
 /** Replace ${VAR_NAME} in a string with the corresponding env var value */
@@ -12,7 +14,7 @@ export function interpolateEnvString(value: string): string {
     if (envValue === undefined) {
       if (isStrictEnv()) {
         throw new Error(
-          `Environment variable "${varName}" is not set (set MCP_STRICT_ENV=false to warn instead)`,
+          `Environment variable "${varName}" is not set (set ${ENV.STRICT_ENV}=false to warn instead)`,
         );
       }
       console.warn(`Warning: environment variable "${varName}" is not set`);

package/src/config/loader.ts

@@ -1,6 +1,7 @@
 import { join, resolve } from "path";
 import { homedir } from "os";
 import { interpolateEnv } from "./env.ts";
+import { ENV } from "../constants.ts";
 import {
   type Config,
   type ServersFile,
@@ -36,7 +37,7 @@ function resolveConfigDir(configFlag?: string): string {
   if (configFlag) return resolve(configFlag);
 
   // 2. MCP_CONFIG_PATH env var
-  const envPath = process.env.MCP_CONFIG_PATH;
+  const envPath = process.env[ENV.CONFIG_PATH];
   if (envPath) return resolve(envPath);
 
   // 3. ./servers.json exists in cwd → use cwd
@@ -107,9 +108,14 @@ export async function loadConfig(options: LoadConfigOptions = {}): Promise<Confi
   return { configDir, servers, auth, searchIndex };
 }
 
+/** Write a JSON file to the config directory */
+async function saveJsonFile(configDir: string, filename: string, data: unknown): Promise<void> {
+  await Bun.write(join(configDir, filename), JSON.stringify(data, null, 2) + "\n");
+}
+
 /** Save auth.json to the config directory */
 export async function saveAuth(configDir: string, auth: AuthFile): Promise<void> {
-  await Bun.write(join(configDir, "auth.json"), JSON.stringify(auth, null, 2) + "\n");
+  return saveJsonFile(configDir, "auth.json", auth);
 }
 
 /** Load search.json from the config directory */
@@ -120,12 +126,12 @@ export async function loadSearchIndex(configDir: string): Promise<SearchIndex> {
 
 /** Save search.json to the config directory */
 export async function saveSearchIndex(configDir: string, index: SearchIndex): Promise<void> {
-  await Bun.write(join(configDir, "search.json"), JSON.stringify(index, null, 2) + "\n");
+  return saveJsonFile(configDir, "search.json", index);
 }
 
 /** Save servers.json to the config directory */
 export async function saveServers(configDir: string, servers: ServersFile): Promise<void> {
-  await Bun.write(join(configDir, "servers.json"), JSON.stringify(servers, null, 2) + "\n");
+  return saveJsonFile(configDir, "servers.json", servers);
 }
 
 /** Load servers.json without env interpolation (preserves ${VAR} placeholders) */

package/src/constants.ts

@@ -0,0 +1,19 @@
+/** Environment variable names used by mcpx */
+export const ENV = {
+  DEBUG: "MCP_DEBUG",
+  CONCURRENCY: "MCP_CONCURRENCY",
+  TIMEOUT: "MCP_TIMEOUT",
+  MAX_RETRIES: "MCP_MAX_RETRIES",
+  STRICT_ENV: "MCP_STRICT_ENV",
+  CONFIG_PATH: "MCP_CONFIG_PATH",
+} as const;
+
+/** Default values for configurable options */
+export const DEFAULTS = {
+  CONCURRENCY: 5,
+  TIMEOUT_SECONDS: 1800,
+  MAX_RETRIES: 3,
+  TASK_TTL_MS: 60_000,
+  SEARCH_TOP_K: 10,
+  LOG_LEVEL: "warning",
+} as const;

package/src/context.ts

@@ -4,6 +4,7 @@ import { ServerManager } from "./client/manager.ts";
 import type { Config } from "./config/schemas.ts";
 import type { FormatOptions } from "./output/formatter.ts";
 import { logger } from "./output/logger.ts";
+import { ENV, DEFAULTS } from "./constants.ts";
 
 export interface AppContext {
   config: Config;
@@ -21,14 +22,14 @@ export async function getContext(program: Command): Promise<AppContext> {
 
   const verbose = !!(
     (opts.verbose as boolean | undefined) ||
-    process.env.MCP_DEBUG === "1" ||
-    process.env.MCP_DEBUG === "true"
+    process.env[ENV.DEBUG] === "1" ||
+    process.env[ENV.DEBUG] === "true"
   );
   const showSecrets = !!(opts.showSecrets as boolean | undefined);
-  const concurrency = Number(process.env.MCP_CONCURRENCY ?? 5);
-  const timeout = Number(process.env.MCP_TIMEOUT ?? 1800) * 1000;
-  const maxRetries = Number(process.env.MCP_MAX_RETRIES ?? 3);
-  const logLevel = (opts.logLevel as string | undefined) ?? "warning";
+  const concurrency = Number(process.env[ENV.CONCURRENCY] ?? DEFAULTS.CONCURRENCY);
+  const timeout = Number(process.env[ENV.TIMEOUT] ?? DEFAULTS.TIMEOUT_SECONDS) * 1000;
+  const maxRetries = Number(process.env[ENV.MAX_RETRIES] ?? DEFAULTS.MAX_RETRIES);
+  const logLevel = (opts.logLevel as string | undefined) ?? DEFAULTS.LOG_LEVEL;
 
   const json = !!(opts.json as boolean | undefined);
   // Commander's --no-interactive sets opts.interactive = false (default true)

package/src/output/format-output.ts

@@ -0,0 +1,18 @@
+import type { FormatOptions } from "./formatter.ts";
+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.
+ */
+export function formatOutput(
+  jsonData: unknown,
+  interactiveFn: () => string,
+  options: FormatOptions,
+): string {
+  if (!isInteractive(options)) {
+    return JSON.stringify(jsonData, null, 2);
+  }
+  return interactiveFn();
+}

package/src/output/format-table.ts

@@ -0,0 +1,63 @@
+import ansis from "ansis";
+import { dim } from "ansis";
+import { wrapDescription } from "./formatter.ts";
+
+export interface Column<T> {
+  value: (item: T) => string;
+  style: (text: string) => string;
+}
+
+export interface TableOptions<T> {
+  columns: Column<T>[];
+  description?: (item: T) => string | undefined;
+  separator?: string;
+  emptyMessage?: string;
+}
+
+/** Measure visible length of a string (excluding ANSI escape codes) */
+function visibleLength(s: string): number {
+  return ansis.strip(s).length;
+}
+
+/** Get terminal width, or undefined if not a TTY */
+function getTerminalWidth(): number | undefined {
+  if (process.stdout.isTTY) return Math.max(process.stdout.columns - 1, 40);
+  return undefined;
+}
+
+/**
+ * Format a list of items as an aligned table with optional description wrapping.
+ */
+export function formatTable<T>(items: T[], options: TableOptions<T>): string {
+  if (items.length === 0) {
+    return dim(options.emptyMessage ?? "No items found");
+  }
+
+  const sep = options.separator ?? "  ";
+  const termWidth = getTerminalWidth();
+
+  // Calculate max width for each column
+  const maxWidths = options.columns.map((col) =>
+    Math.max(...items.map((item) => col.value(item).length)),
+  );
+
+  return items
+    .map((item) => {
+      const parts = options.columns.map((col, i) => {
+        const raw = col.value(item);
+        const pad = maxWidths[i]! - raw.length;
+        return col.style(raw) + " ".repeat(Math.max(0, pad));
+      });
+      const prefix = parts.join(sep);
+
+      const desc = options.description?.(item);
+      if (desc) {
+        const pw = visibleLength(prefix) + sep.length;
+        const formatted = termWidth != null ? wrapDescription(desc, pw, termWidth) : dim(desc);
+        return `${prefix}${sep}${formatted}`;
+      }
+
+      return prefix;
+    })
+    .join("\n");
+}