@evantahler/mcpx 0.15.4 → 0.15.9

package/src/commands/info.ts

@@ -1,63 +1,58 @@
 import type { Command } from "commander";
 import type { Tool, Resource, Prompt } from "../config/schemas.ts";
-import { getContext } from "../context.ts";
 import { formatServerOverview, formatToolSchema, formatError } from "../output/formatter.ts";
-import { logger } from "../output/logger.ts";
+import { withCommand } from "./with-command.ts";
 
 export function registerInfoCommand(program: Command) {
   program
     .command("info <server> [tool]")
     .description("show server overview, or schema for a specific tool")
-    .action(async (server: string, tool: string | undefined) => {
-      const { manager, formatOptions } = await getContext(program);
-      const target = tool ? `${server}/${tool}` : server;
-      const spinner = logger.startSpinner(`Connecting to ${target}...`, formatOptions);
-      try {
-        if (tool) {
-          const toolSchema = await manager.getToolSchema(server, tool);
-          spinner.stop();
-          if (!toolSchema) {
-            console.error(
-              formatError(`Tool "${tool}" not found on server "${server}"`, formatOptions),
-            );
-            process.exit(1);
-          }
-          console.log(formatToolSchema(server, toolSchema, formatOptions));
-        } else {
-          // Get server info first to check capabilities
-          const serverInfo = await manager.getServerInfo(server);
-          const caps = serverInfo.capabilities as Record<string, unknown> | undefined;
+    .action(
+      withCommand(
+        program,
+        { spinnerText: "Connecting..." },
+        async ({ manager, formatOptions, spinner }, server: string, tool?: string) => {
+          const target = tool ? `${server}/${tool}` : server;
+          spinner.update(`Connecting to ${target}...`);
+
+          if (tool) {
+            const toolSchema = await manager.getToolSchema(server, tool);
+            spinner.stop();
+            if (!toolSchema) {
+              console.error(
+                formatError(`Tool "${tool}" not found on server "${server}"`, formatOptions),
+              );
+              process.exit(1);
+            }
+            console.log(formatToolSchema(server, toolSchema, formatOptions));
+          } else {
+            const serverInfo = await manager.getServerInfo(server);
+            const caps = serverInfo.capabilities as Record<string, unknown> | undefined;
 
-          // Only fetch what the server supports
-          const fetches: [Promise<Tool[]>, Promise<Resource[]>, Promise<Prompt[]>] = [
-            caps?.tools !== undefined ? manager.listTools(server) : Promise.resolve([]),
-            caps?.resources !== undefined ? manager.listResources(server) : Promise.resolve([]),
-            caps?.prompts !== undefined ? manager.listPrompts(server) : Promise.resolve([]),
-          ];
-          const [tools, resources, prompts] = await Promise.all(fetches);
+            const fetches: [Promise<Tool[]>, Promise<Resource[]>, Promise<Prompt[]>] = [
+              caps?.tools !== undefined ? manager.listTools(server) : Promise.resolve([]),
+              caps?.resources !== undefined ? manager.listResources(server) : Promise.resolve([]),
+              caps?.prompts !== undefined ? manager.listPrompts(server) : Promise.resolve([]),
+            ];
+            const [tools, resources, prompts] = await Promise.all(fetches);
 
-          spinner.stop();
-          console.log(
-            formatServerOverview(
-              {
-                serverName: server,
-                version: serverInfo.version,
-                capabilities: caps,
-                instructions: serverInfo.instructions,
-                tools,
-                resourceCount: resources.length,
-                promptCount: prompts.length,
-              },
-              formatOptions,
-            ),
-          );
-        }
-      } catch (err) {
-        spinner.error(`Failed to connect to ${target}`);
-        console.error(formatError(String(err), formatOptions));
-        process.exit(1);
-      } finally {
-        await manager.close();
-      }
-    });
+            spinner.stop();
+            console.log(
+              formatServerOverview(
+                {
+                  serverName: server,
+                  version: serverInfo.version,
+                  capabilities: caps,
+                  instructions: serverInfo.instructions,
+                  tools,
+                  resourceCount: resources.length,
+                  promptCount: prompts.length,
+                },
+                formatOptions,
+              ),
+            );
+          }
+        },
+      ),
+    );
 }

package/src/commands/list.ts

@@ -1,64 +1,59 @@
 import type { Command } from "commander";
-import { getContext } from "../context.ts";
-import { formatUnifiedList, formatError } from "../output/formatter.ts";
+import { formatUnifiedList } from "../output/formatter.ts";
 import type { UnifiedItem } from "../output/formatter.ts";
-import { logger } from "../output/logger.ts";
+import { withCommand } from "./with-command.ts";
 
 export function registerListCommand(program: Command) {
-  program.action(async () => {
-    const { manager, formatOptions } = await getContext(program);
-    const spinner = logger.startSpinner("Connecting to servers...", formatOptions);
-    try {
-      const [toolsResult, resourcesResult, promptsResult] = await Promise.all([
-        manager.getAllTools(),
-        manager.getAllResources(),
-        manager.getAllPrompts(),
-      ]);
-      spinner.stop();
+  program.action(
+    withCommand(
+      program,
+      { spinnerText: "Connecting to servers...", errorLabel: "Failed to list servers" },
+      async ({ manager, formatOptions, spinner }) => {
+        const [toolsResult, resourcesResult, promptsResult] = await Promise.all([
+          manager.getAllTools(),
+          manager.getAllResources(),
+          manager.getAllPrompts(),
+        ]);
+        spinner.stop();
 
-      const items: UnifiedItem[] = [
-        ...toolsResult.tools.map((t) => ({
-          server: t.server,
-          type: "tool" as const,
-          name: t.tool.name,
-          description: t.tool.description,
-        })),
-        ...resourcesResult.resources.map((r) => ({
-          server: r.server,
-          type: "resource" as const,
-          name: r.resource.uri,
-          description: r.resource.description,
-        })),
-        ...promptsResult.prompts.map((p) => ({
-          server: p.server,
-          type: "prompt" as const,
-          name: p.prompt.name,
-          description: p.prompt.description,
-        })),
-      ];
+        const items: UnifiedItem[] = [
+          ...toolsResult.tools.map((t) => ({
+            server: t.server,
+            type: "tool" as const,
+            name: t.tool.name,
+            description: t.tool.description,
+          })),
+          ...resourcesResult.resources.map((r) => ({
+            server: r.server,
+            type: "resource" as const,
+            name: r.resource.uri,
+            description: r.resource.description,
+          })),
+          ...promptsResult.prompts.map((p) => ({
+            server: p.server,
+            type: "prompt" as const,
+            name: p.prompt.name,
+            description: p.prompt.description,
+          })),
+        ];
 
-      const typeOrder = { tool: 0, resource: 1, prompt: 2 };
-      items.sort((a, b) => {
-        if (a.server !== b.server) return a.server.localeCompare(b.server);
-        if (a.type !== b.type) return typeOrder[a.type] - typeOrder[b.type];
-        return a.name.localeCompare(b.name);
-      });
+        const typeOrder = { tool: 0, resource: 1, prompt: 2 };
+        items.sort((a, b) => {
+          if (a.server !== b.server) return a.server.localeCompare(b.server);
+          if (a.type !== b.type) return typeOrder[a.type] - typeOrder[b.type];
+          return a.name.localeCompare(b.name);
+        });
 
-      const errors = [...toolsResult.errors, ...resourcesResult.errors, ...promptsResult.errors];
-      if (errors.length > 0) {
-        for (const err of errors) {
-          console.error(`"${err.server}": ${err.message}`);
+        const errors = [...toolsResult.errors, ...resourcesResult.errors, ...promptsResult.errors];
+        if (errors.length > 0) {
+          for (const err of errors) {
+            console.error(`"${err.server}": ${err.message}`);
+          }
+          if (items.length > 0) console.log("");
         }
-        if (items.length > 0) console.log("");
-      }
 
-      console.log(formatUnifiedList(items, formatOptions));
-    } catch (err) {
-      spinner.error("Failed to list servers");
-      console.error(formatError(String(err), formatOptions));
-      process.exit(1);
-    } finally {
-      await manager.close();
-    }
-  });
+        console.log(formatUnifiedList(items, formatOptions));
+      },
+    ),
+  );
 }

package/src/commands/prompt.ts

@@ -1,26 +1,31 @@
 import type { Command } from "commander";
-import { getContext } from "../context.ts";
 import {
   formatPromptList,
   formatServerPrompts,
   formatPromptMessages,
   formatError,
 } from "../output/formatter.ts";
-import { logger } from "../output/logger.ts";
 import { parseJsonArgs, readStdin } from "../lib/input.ts";
+import { withCommand } from "./with-command.ts";
 
 export function registerPromptCommand(program: Command) {
   program
     .command("prompt [server] [name] [args]")
     .description("list prompts for a server, or get a specific prompt")
     .action(
-      async (server: string | undefined, name: string | undefined, argsStr: string | undefined) => {
-        const { manager, formatOptions } = await getContext(program);
-        const spinner = logger.startSpinner(
-          server ? `Connecting to ${server}...` : "Connecting to servers...",
-          formatOptions,
-        );
-        try {
+      withCommand(
+        program,
+        { spinnerText: "Connecting to servers..." },
+        async (
+          { manager, formatOptions, spinner },
+          server?: string,
+          name?: string,
+          argsStr?: string,
+        ) => {
+          if (server) {
+            spinner.update(`Connecting to ${server}...`);
+          }
+
           if (server && name) {
             let args: Record<string, string> | undefined;
 
@@ -48,13 +53,7 @@ export function registerPromptCommand(program: Command) {
               console.error(formatError(`${err.server}: ${err.message}`, formatOptions));
             }
           }
-        } catch (err) {
-          spinner.error("Failed");
-          console.error(formatError(String(err), formatOptions));
-          process.exit(1);
-        } finally {
-          await manager.close();
-        }
-      },
+        },
+      ),
     );
 }

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`);