@evantahler/mcpx 0.15.0

package/src/commands/add.ts

@@ -0,0 +1,179 @@
+import type { Command } from "commander";
+import type { ServerConfig } from "../config/schemas.ts";
+import { loadRawAuth, loadRawServers, saveServers } from "../config/loader.ts";
+import { tryOAuthIfSupported, resolveResourceUrl } from "../client/oauth.ts";
+import { runIndex } from "./index.ts";
+
+export function registerAddCommand(program: Command) {
+  program
+    .command("add <name>")
+    .description("add an MCP server to your config")
+    .option("--command <cmd>", "command to run (stdio server)")
+    .option("--args <args>", "comma-separated arguments for the command")
+    .option("--env <vars>", "comma-separated KEY=VAL environment variables")
+    .option("--cwd <dir>", "working directory for the command")
+    .option("--url <url>", "server URL (HTTP server)")
+    .option("--header <h>", "header in Key:Value format (repeatable)", collect, [])
+    .option("--transport <type>", 'transport for HTTP servers: "sse" or "streamable-http"')
+    .option("--allowed-tools <tools>", "comma-separated list of allowed tools")
+    .option("--disabled-tools <tools>", "comma-separated list of disabled tools")
+    .option("-f, --force", "overwrite if server already exists")
+    .option("--no-auth", "skip automatic OAuth authentication after adding an HTTP server")
+    .option("--no-index", "skip rebuilding the search index after adding")
+    .action(
+      async (
+        name: string,
+        options: {
+          command?: string;
+          args?: string;
+          env?: string;
+          cwd?: string;
+          url?: string;
+          header?: string[];
+          transport?: string;
+          allowedTools?: string;
+          disabledTools?: string;
+          force?: boolean;
+          auth?: boolean;
+          index?: boolean;
+        },
+      ) => {
+        const hasCommand = !!options.command;
+        const hasUrl = !!options.url;
+
+        if (!hasCommand && !hasUrl) {
+          console.error("Must specify --command (stdio) or --url (http)");
+          process.exit(1);
+        }
+        if (hasCommand && hasUrl) {
+          console.error("Cannot specify both --command and --url");
+          process.exit(1);
+        }
+
+        const configFlag = program.opts().config;
+        const { configDir, servers } = await loadRawServers(configFlag);
+
+        if (servers.mcpServers[name] && !options.force) {
+          console.error(`Server "${name}" already exists (use --force to overwrite)`);
+          process.exit(1);
+        }
+
+        let config: ServerConfig;
+
+        if (hasCommand) {
+          config = buildStdioConfig(options);
+        } else {
+          config = buildHttpConfig(options);
+        }
+
+        if (hasUrl && options.transport) {
+          if (options.transport !== "sse" && options.transport !== "streamable-http") {
+            console.error('--transport must be "sse" or "streamable-http"');
+            process.exit(1);
+          }
+          (config as { transport: string }).transport = options.transport;
+        }
+
+        // Common options
+        if (options.allowedTools) {
+          config.allowedTools = options.allowedTools.split(",").map((t) => t.trim());
+        }
+        if (options.disabledTools) {
+          config.disabledTools = options.disabledTools.split(",").map((t) => t.trim());
+        }
+
+        // For HTTP servers, resolve the canonical resource URL before saving.
+        // Some servers (e.g. hf.co → huggingface.co) advertise a different canonical
+        // URL in their OAuth protected resource metadata, and the SDK enforces that the
+        // stored URL matches this canonical URL during the OAuth token flow.
+        let effectiveUrl = options.url!;
+        if (hasUrl && options.auth !== false) {
+          const canonical = await resolveResourceUrl(effectiveUrl);
+          if (canonical !== effectiveUrl) {
+            (config as { url: string }).url = canonical;
+            effectiveUrl = canonical;
+            console.log(`Resolved canonical URL: ${canonical}`);
+          }
+        }
+
+        servers.mcpServers[name] = config;
+        await saveServers(configDir, servers);
+        console.log(`Added server "${name}" to ${configDir}/servers.json`);
+
+        // Auto-auth: probe for OAuth support and run the flow if supported
+        if (hasUrl && options.auth !== false) {
+          const auth = await loadRawAuth(configDir);
+          const formatOptions = {
+            json: !!program.opts().json,
+            verbose: !!program.opts().verbose,
+            showSecrets: false,
+          };
+          try {
+            await tryOAuthIfSupported(name, effectiveUrl, configDir, auth, formatOptions);
+          } catch {
+            console.error(`Warning: OAuth authentication failed. Run: mcpx auth ${name}`);
+          }
+        }
+
+        // Commander treats --no-index as index=false (default true)
+        if (options.index !== false) {
+          await runIndex(program);
+        }
+      },
+    );
+}
+
+function collect(value: string, previous: string[]): string[] {
+  return previous.concat([value]);
+}
+
+function buildStdioConfig(options: {
+  command?: string;
+  args?: string;
+  env?: string;
+  cwd?: string;
+}): ServerConfig {
+  const config: Record<string, unknown> = { command: options.command! };
+
+  if (options.args) {
+    config.args = options.args.split(",").map((a) => a.trim());
+  }
+
+  if (options.env) {
+    const env: Record<string, string> = {};
+    for (const pair of options.env.split(",")) {
+      const eqIdx = pair.indexOf("=");
+      if (eqIdx === -1) {
+        console.error(`Invalid env format "${pair}", expected KEY=VAL`);
+        process.exit(1);
+      }
+      env[pair.slice(0, eqIdx).trim()] = pair.slice(eqIdx + 1).trim();
+    }
+    config.env = env;
+  }
+
+  if (options.cwd) {
+    config.cwd = options.cwd;
+  }
+
+  return config as ServerConfig;
+}
+
+function buildHttpConfig(options: { url?: string; header?: string[] }): ServerConfig {
+  const config: Record<string, unknown> = { url: options.url! };
+
+  if (options.header && options.header.length > 0) {
+    const headers: Record<string, string> = {};
+    for (const h of options.header) {
+      const colonIdx = h.indexOf(":");
+      if (colonIdx === -1) {
+        console.error(`Invalid header format "${h}", expected Key:Value`);
+        process.exit(1);
+      }
+      headers[h.slice(0, colonIdx).trim()] = h.slice(colonIdx + 1).trim();
+    }
+    config.headers = headers;
+  }
+
+  return config as ServerConfig;
+}

package/src/commands/auth.ts

@@ -0,0 +1,114 @@
+import type { Command } from "commander";
+import { getContext } from "../context.ts";
+import { isHttpServer } from "../config/schemas.ts";
+import { saveAuth } from "../config/loader.ts";
+import { McpOAuthProvider, runOAuthFlow } from "../client/oauth.ts";
+import { logger } from "../output/logger.ts";
+import { runIndex } from "./index.ts";
+
+export function registerAuthCommand(program: Command) {
+  program
+    .command("auth <server>")
+    .description("authenticate with an HTTP MCP server")
+    .option("-s, --status", "check auth status and token TTL")
+    .option("-r, --refresh", "force token refresh")
+    .option("--no-index", "skip rebuilding the search index after auth")
+    .action(
+      async (server: string, options: { status?: boolean; refresh?: boolean; index?: boolean }) => {
+        const { config, formatOptions } = await getContext(program);
+
+        const serverConfig = config.servers.mcpServers[server];
+        if (!serverConfig) {
+          console.error(`Unknown server: "${server}"`);
+          process.exit(1);
+        }
+        if (!isHttpServer(serverConfig)) {
+          console.error(
+            `Server "${server}" is not an HTTP server — OAuth only applies to HTTP servers`,
+          );
+          process.exit(1);
+        }
+
+        const provider = new McpOAuthProvider({
+          serverName: server,
+          configDir: config.configDir,
+          auth: config.auth,
+        });
+
+        if (options.status) {
+          showStatus(server, provider);
+          return;
+        }
+
+        if (options.refresh) {
+          const spinner = logger.startSpinner(`Refreshing token for "${server}"…`, formatOptions);
+          try {
+            await provider.refreshIfNeeded(serverConfig.url);
+            spinner.success(`Token refreshed for "${server}"`);
+          } catch (err) {
+            spinner.error(`Refresh failed: ${err instanceof Error ? err.message : err}`);
+            process.exit(1);
+          }
+          return;
+        }
+
+        // Default: full OAuth flow
+        const spinner = logger.startSpinner(`Authenticating with "${server}"…`, formatOptions);
+        try {
+          await runOAuthFlow(serverConfig.url, provider);
+          spinner.success(`Authenticated with "${server}"`);
+        } catch (err) {
+          spinner.error(`Authentication failed: ${err instanceof Error ? err.message : err}`);
+          process.exit(1);
+        }
+
+        if (options.index !== false) {
+          await runIndex(program);
+        }
+      },
+    );
+}
+
+export function registerDeauthCommand(program: Command) {
+  program
+    .command("deauth <server>")
+    .description("remove stored authentication for a server")
+    .action(async (server: string) => {
+      const { config } = await getContext(program);
+
+      if (!config.auth[server]) {
+        console.log(`No auth stored for "${server}"`);
+        return;
+      }
+
+      delete config.auth[server];
+      await saveAuth(config.configDir, config.auth);
+      console.log(`Deauthenticated "${server}"`);
+    });
+}
+
+function showStatus(server: string, provider: McpOAuthProvider) {
+  if (!provider.isComplete()) {
+    console.log(`${server}: not authenticated`);
+    return;
+  }
+
+  const expired = provider.isExpired();
+  const hasRefresh = provider.hasRefreshToken();
+  const status = expired ? "expired" : "authenticated";
+
+  console.log(`${server}: ${status}`);
+  if (hasRefresh) {
+    console.log("  refresh token: present");
+  }
+
+  if (!expired) {
+    // Show TTL if we have expires_at from the auth entry
+    const entry = provider["auth"][server];
+    if (entry?.expires_at) {
+      const remaining = new Date(entry.expires_at).getTime() - Date.now();
+      const minutes = Math.round(remaining / 60000);
+      console.log(`  expires in: ${minutes} minutes`);
+    }
+  }
+}

package/src/commands/exec.ts

@@ -0,0 +1,156 @@
+import type { Command } from "commander";
+import { getContext } from "../context.ts";
+import {
+  formatCallResult,
+  formatError,
+  formatServerTools,
+  formatTaskCreated,
+  formatValidationErrors,
+} from "../output/formatter.ts";
+import { logger } from "../output/logger.ts";
+import { validateToolInput } from "../validation/schema.ts";
+import { parseJsonArgs, readStdin } from "../lib/input.ts";
+
+export function registerExecCommand(program: Command) {
+  program
+    .command("exec <server> [tool] [args]")
+    .description("execute a tool (omit tool name to list available tools)")
+    .option("-f, --file <path>", "read JSON args from a file")
+    .option("--no-wait", "return task handle immediately without waiting for completion")
+    .option("--ttl <ms>", "task TTL in milliseconds", "60000")
+    .action(
+      async (
+        server: string,
+        tool: string | undefined,
+        argsStr: string | undefined,
+        options: { file?: string; wait: boolean; ttl: string },
+      ) => {
+        const { manager, formatOptions } = await getContext(program);
+
+        if (!tool) {
+          try {
+            const tools = await manager.listTools(server);
+            console.log(formatServerTools(server, tools, formatOptions));
+          } catch (err) {
+            console.error(formatError(String(err), formatOptions));
+            process.exit(1);
+          } finally {
+            await manager.close();
+          }
+          return;
+        }
+        try {
+          // Error if both --file and positional arg provided
+          if (options.file && argsStr) {
+            throw new Error("Cannot specify both --file and inline JSON args");
+          }
+
+          // Parse args from: --file > positional arg > stdin > empty
+          let args: Record<string, unknown> = {};
+
+          if (options.file) {
+            const file = Bun.file(options.file);
+            if (!(await file.exists())) {
+              throw new Error(`File not found: ${options.file}`);
+            }
+            const content = await file.text();
+            args = parseJsonArgs(content);
+          } else if (argsStr) {
+            args = parseJsonArgs(argsStr);
+          } else if (!process.stdin.isTTY) {
+            // Read from stdin
+            const stdin = await readStdin();
+            if (stdin.trim()) {
+              args = parseJsonArgs(stdin);
+            }
+          }
+
+          // Validate args against tool inputSchema before calling
+          const toolSchema = await manager.getToolSchema(server, tool);
+          if (toolSchema) {
+            const validation = validateToolInput(server, toolSchema, args);
+            if (!validation.valid) {
+              console.error(formatValidationErrors(server, tool, validation.errors, formatOptions));
+              process.exit(1);
+            }
+          }
+
+          // Check if tool supports task-augmented execution
+          const taskSupport = (toolSchema as Record<string, unknown> | undefined)?.execution as
+            | { taskSupport?: string }
+            | undefined;
+          const supportsTask = await manager.serverSupportsTask(server);
+          const useTask =
+            supportsTask &&
+            taskSupport?.taskSupport !== undefined &&
+            taskSupport.taskSupport !== "forbidden";
+
+          if (useTask) {
+            const abortController = new AbortController();
+            let currentTaskId: string | undefined;
+
+            // Graceful Ctrl+C: cancel the task before exiting
+            const sigintHandler = async () => {
+              abortController.abort();
+              if (currentTaskId) {
+                try {
+                  await manager.cancelTask(server, currentTaskId);
+                } catch {
+                  // best effort
+                }
+              }
+              await manager.close();
+              process.exit(130);
+            };
+            process.on("SIGINT", sigintHandler);
+
+            const spinner = logger.startSpinner(`Executing ${server}/${tool}...`, formatOptions);
+            try {
+              const stream = manager.callToolStream(server, tool, args, {
+                ttl: parseInt(options.ttl, 10),
+                signal: abortController.signal,
+              });
+
+              for await (const message of stream) {
+                switch (message.type) {
+                  case "taskCreated":
+                    currentTaskId = message.task.taskId;
+                    if (!options.wait) {
+                      // --no-wait: output the task handle and exit
+                      spinner.stop();
+                      console.log(formatTaskCreated(message.task, formatOptions));
+                      return;
+                    }
+                    spinner.update(`Task ${message.task.taskId} (${message.task.status})...`);
+                    break;
+                  case "taskStatus":
+                    spinner.update(`Task ${message.task.taskId} (${message.task.status})...`);
+                    break;
+                  case "result":
+                    spinner.stop();
+                    console.log(formatCallResult(message.result, formatOptions));
+                    return;
+                  case "error":
+                    spinner.error("Task failed");
+                    throw message.error;
+                }
+              }
+            } finally {
+              process.removeListener("SIGINT", sigintHandler);
+            }
+          } else {
+            // Standard synchronous tool call
+            const spinner = logger.startSpinner(`Executing ${server}/${tool}...`, formatOptions);
+            const result = await manager.callTool(server, tool, args);
+            spinner.stop();
+            console.log(formatCallResult(result, formatOptions));
+          }
+        } catch (err) {
+          console.error(formatError(String(err), formatOptions));
+          process.exit(1);
+        } finally {
+          await manager.close();
+        }
+      },
+    );
+}

package/src/commands/index.ts

@@ -0,0 +1,62 @@
+import type { Command } from "commander";
+import { yellow } from "ansis";
+import { getContext } from "../context.ts";
+import { buildSearchIndex } from "../search/indexer.ts";
+import { getStaleServers } from "../search/staleness.ts";
+import { saveSearchIndex } from "../config/loader.ts";
+import { formatError } from "../output/formatter.ts";
+import { logger } from "../output/logger.ts";
+
+/** Run the search index build. Reusable from other commands (e.g. add). */
+export async function runIndex(program: Command): Promise<void> {
+  const { config, manager, formatOptions } = await getContext(program);
+  const spinner = logger.startSpinner("Connecting to servers...", formatOptions);
+
+  try {
+    const start = performance.now();
+    const index = await buildSearchIndex(manager, (progress) => {
+      spinner.update(`Indexing ${progress.current}/${progress.total}: ${progress.tool}`);
+    });
+    const elapsed = ((performance.now() - start) / 1000).toFixed(1);
+
+    await saveSearchIndex(config.configDir, index);
+    spinner.success(`Indexed ${index.tools.length} tools in ${elapsed}s`);
+
+    logger.info(`Saved to ${config.configDir}/search.json`);
+  } catch (err) {
+    spinner.error("Indexing failed");
+    console.error(formatError(String(err), formatOptions));
+    process.exit(1);
+  } finally {
+    await manager.close();
+  }
+}
+
+export function registerIndexCommand(program: Command) {
+  program
+    .command("index")
+    .description("build the search index from all configured servers")
+    .option("-i, --status", "show index status")
+    .action(async (options: { status?: boolean }) => {
+      if (options.status) {
+        const { config, manager } = await getContext(program);
+        const idx = config.searchIndex;
+        if (idx.tools.length === 0) {
+          console.log("No search index. Run: mcpx index");
+        } else {
+          console.log(`Tools:   ${idx.tools.length}`);
+          console.log(`Model:   ${idx.embedding_model}`);
+          console.log(`Indexed: ${idx.indexed_at}`);
+
+          const stale = getStaleServers(idx, config.servers);
+          if (stale.length > 0) {
+            console.log(yellow(`Stale:   ${stale.join(", ")} (run mcpx index to refresh)`));
+          }
+        }
+        await manager.close();
+        return;
+      }
+
+      await runIndex(program);
+    });
+}

package/src/commands/info.ts

@@ -0,0 +1,63 @@
+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";
+
+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;
+
+          // 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);
+
+          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();
+      }
+    });
+}

package/src/commands/list.ts

@@ -0,0 +1,64 @@
+import type { Command } from "commander";
+import { getContext } from "../context.ts";
+import { formatUnifiedList, formatError } from "../output/formatter.ts";
+import type { UnifiedItem } from "../output/formatter.ts";
+import { logger } from "../output/logger.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();
+
+      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 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("");
+      }
+
+      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();
+    }
+  });
+}