@evantahler/mcpx 0.15.0

package/.claude/worktrees/elastic-jennings/src/commands/add.ts

@@ -0,0 +1,155 @@
+import type { Command } from "commander";
+import type { ServerConfig } from "../config/schemas.ts";
+import { loadRawAuth, loadRawServers, saveServers } from "../config/loader.ts";
+import { tryOAuthIfSupported } 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("--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[];
+          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);
+        }
+
+        // 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());
+        }
+
+        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, options.url!, configDir, auth, formatOptions);
+          } catch {
+            console.error(`Warning: OAuth authentication failed. Run: mcpcli 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/.claude/worktrees/elastic-jennings/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/.claude/worktrees/elastic-jennings/src/commands/exec.ts

@@ -0,0 +1,91 @@
+import type { Command } from "commander";
+import { getContext } from "../context.ts";
+import {
+  formatCallResult,
+  formatError,
+  formatServerTools,
+  formatValidationErrors,
+} from "../output/formatter.ts";
+import { logger } from "../output/logger.ts";
+import { validateToolInput } from "../validation/schema.ts";
+
+export function registerExecCommand(program: Command) {
+  program
+    .command("exec <server> [tool] [args]")
+    .description("execute a tool (omit tool name to list available tools)")
+    .action(async (server: string, tool: string | undefined, argsStr: string | undefined) => {
+      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 {
+        // Parse args from argument, stdin, or empty
+        let args: Record<string, unknown> = {};
+
+        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);
+          }
+        }
+
+        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();
+      }
+    });
+}
+
+function parseJsonArgs(str: string): Record<string, unknown> {
+  try {
+    const parsed = JSON.parse(str);
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+      throw new Error("Tool arguments must be a JSON object");
+    }
+    return parsed as Record<string, unknown>;
+  } catch (err) {
+    if (err instanceof SyntaxError) {
+      throw new Error(`Invalid JSON: ${err.message}`);
+    }
+    throw err;
+  }
+}
+
+async function readStdin(): Promise<string> {
+  const chunks: string[] = [];
+  const reader = process.stdin;
+  reader.setEncoding("utf-8");
+  for await (const chunk of reader) {
+    chunks.push(chunk as string);
+  }
+  return chunks.join("");
+}

package/.claude/worktrees/elastic-jennings/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: mcpcli 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 mcpcli index to refresh)`));
+          }
+        }
+        await manager.close();
+        return;
+      }
+
+      await runIndex(program);
+    });
+}

package/.claude/worktrees/elastic-jennings/src/commands/info.ts

@@ -0,0 +1,38 @@
+import type { Command } from "commander";
+import { getContext } from "../context.ts";
+import { formatServerTools, formatToolSchema, formatError } from "../output/formatter.ts";
+import { logger } from "../output/logger.ts";
+
+export function registerInfoCommand(program: Command) {
+  program
+    .command("info <server> [tool]")
+    .description("show tools for a server, 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 {
+          const tools = await manager.listTools(server);
+          spinner.stop();
+          console.log(formatServerTools(server, tools, formatOptions));
+        }
+      } catch (err) {
+        spinner.error(`Failed to connect to ${target}`);
+        console.error(formatError(String(err), formatOptions));
+        process.exit(1);
+      } finally {
+        await manager.close();
+      }
+    });
+}

package/.claude/worktrees/elastic-jennings/src/commands/list.ts

@@ -0,0 +1,30 @@
+import type { Command } from "commander";
+import { getContext } from "../context.ts";
+import { formatToolList, formatError } 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 { tools, errors } = await manager.getAllTools();
+      spinner.stop();
+
+      if (errors.length > 0) {
+        for (const err of errors) {
+          console.error(`"${err.server}": ${err.message}`);
+        }
+        if (tools.length > 0) console.log("");
+      }
+
+      console.log(formatToolList(tools, formatOptions));
+    } catch (err) {
+      spinner.error("Failed to list tools");
+      console.error(formatError(String(err), formatOptions));
+      process.exit(1);
+    } finally {
+      await manager.close();
+    }
+  });
+}

package/.claude/worktrees/elastic-jennings/src/commands/remove.ts

@@ -0,0 +1,67 @@
+import type { Command } from "commander";
+import {
+  loadRawServers,
+  loadRawAuth,
+  loadSearchIndex,
+  saveServers,
+  saveAuth,
+  saveSearchIndex,
+} from "../config/loader.ts";
+
+export function registerRemoveCommand(program: Command) {
+  program
+    .command("remove <name>")
+    .description("remove an MCP server from your config")
+    .option("--keep-auth", "keep stored authentication credentials")
+    .option("--dry-run", "show what would be removed without changing files")
+    .action(async (name: string, options: { keepAuth?: boolean; dryRun?: boolean }) => {
+      const configFlag = program.opts().config;
+      const { configDir, servers } = await loadRawServers(configFlag);
+
+      if (!servers.mcpServers[name]) {
+        console.error(`Unknown server: "${name}"`);
+        process.exit(1);
+      }
+
+      if (options.dryRun) {
+        console.log(`Would remove server "${name}" from ${configDir}/servers.json`);
+        if (!options.keepAuth) {
+          const auth = await loadRawAuth(configDir);
+          if (auth[name]) {
+            console.log(`Would remove auth for "${name}" from ${configDir}/auth.json`);
+          }
+        }
+        const searchIndex = await loadSearchIndex(configDir);
+        const indexedCount = searchIndex.tools.filter((t) => t.server === name).length;
+        if (indexedCount > 0) {
+          console.log(
+            `Would remove ${indexedCount} tool(s) for "${name}" from ${configDir}/search.json`,
+          );
+        }
+        return;
+      }
+
+      delete servers.mcpServers[name];
+      await saveServers(configDir, servers);
+      console.log(`Removed server "${name}" from ${configDir}/servers.json`);
+
+      if (!options.keepAuth) {
+        const auth = await loadRawAuth(configDir);
+        if (auth[name]) {
+          delete auth[name];
+          await saveAuth(configDir, auth);
+          console.log(`Removed auth for "${name}" from ${configDir}/auth.json`);
+        }
+      }
+
+      // Remove tools for this server from the search index
+      const searchIndex = await loadSearchIndex(configDir);
+      const before = searchIndex.tools.length;
+      searchIndex.tools = searchIndex.tools.filter((t) => t.server !== name);
+      const removed = before - searchIndex.tools.length;
+      if (removed > 0) {
+        await saveSearchIndex(configDir, searchIndex);
+        console.log(`Removed ${removed} tool(s) for "${name}" from ${configDir}/search.json`);
+      }
+    });
+}

package/.claude/worktrees/elastic-jennings/src/commands/search.ts

@@ -0,0 +1,45 @@
+import type { Command } from "commander";
+import { getContext } from "../context.ts";
+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";
+
+export function registerSearchCommand(program: Command) {
+  program
+    .command("search <terms...>")
+    .description("search tools by keyword and/or semantic similarity")
+    .option("-k, --keyword", "keyword/glob search only")
+    .option("-q, --query", "semantic search only")
+    .action(async (terms: string[], options: { keyword?: boolean; query?: boolean }) => {
+      const query = terms.join(" ");
+      const { config, formatOptions } = await getContext(program);
+
+      if (config.searchIndex.tools.length === 0) {
+        console.error(formatError("No search index found. Run: mcpcli index", formatOptions));
+        process.exit(1);
+      }
+
+      const stale = getStaleServers(config.searchIndex, config.servers);
+      if (stale.length > 0) {
+        logger.warn(
+          `Warning: index has tools for removed servers: ${stale.join(", ")}. Run: mcpcli index`,
+        );
+      }
+
+      const spinner = logger.startSpinner("Searching...", formatOptions);
+
+      try {
+        const results = await search(query, config.searchIndex, {
+          keywordOnly: options.keyword,
+          semanticOnly: options.query,
+        });
+        spinner.stop();
+        console.log(formatSearchResults(results, formatOptions));
+      } catch (err) {
+        spinner.stop();
+        console.error(formatError(String(err), formatOptions));
+        process.exit(1);
+      }
+    });
+}

package/.claude/worktrees/elastic-jennings/src/commands/skill.ts

@@ -0,0 +1,70 @@
+import type { Command } from "commander";
+import { resolve, dirname, join } from "path";
+import { readFile, mkdir, writeFile, access } from "fs/promises";
+import { homedir } from "os";
+
+export function registerSkillCommand(program: Command) {
+  const skill = program.command("skill").description("manage mcpcli skills");
+
+  skill
+    .command("install")
+    .description("install the mcpcli skill for an AI agent")
+    .requiredOption("--claude", "install for Claude Code")
+    .option("--global", "install to ~/.claude/skills/")
+    .option("--project", "install to ./.claude/skills/ (default)")
+    .option("-f, --force", "overwrite if file already exists")
+    .action(
+      async (options: {
+        claude?: boolean;
+        global?: boolean;
+        project?: boolean;
+        force?: boolean;
+      }) => {
+        // Resolve the bundled skill file
+        const skillSource = resolve(dirname(Bun.main), "..", ".claude", "skills", "mcpcli.md");
+
+        let content: string;
+        try {
+          content = await readFile(skillSource, "utf-8");
+        } catch {
+          console.error(`Could not read skill file: ${skillSource}`);
+          process.exit(1);
+        }
+
+        // Determine targets — default to project if neither flag is set
+        const targets: { label: string; dir: string }[] = [];
+
+        if (options.global) {
+          targets.push({
+            label: "global",
+            dir: join(homedir(), ".claude", "skills"),
+          });
+        }
+        if (options.project || !options.global) {
+          targets.push({
+            label: "project",
+            dir: resolve(".claude", "skills"),
+          });
+        }
+
+        for (const target of targets) {
+          const dest = join(target.dir, "mcpcli.md");
+
+          // Check if file already exists
+          if (!options.force) {
+            try {
+              await access(dest);
+              console.error(`${dest} already exists (use --force to overwrite)`);
+              process.exit(1);
+            } catch {
+              // File doesn't exist — good
+            }
+          }
+
+          await mkdir(target.dir, { recursive: true });
+          await writeFile(dest, content, "utf-8");
+          console.log(`Installed mcpcli skill (${target.label}): ${dest}`);
+        }
+      },
+    );
+}