@evantahler/mcpx 0.15.0

package/src/commands/ping.ts

@@ -0,0 +1,69 @@
+import { green, red } from "ansis";
+import type { Command } from "commander";
+import { getContext } from "../context.ts";
+import { formatError } from "../output/formatter.ts";
+import { logger } from "../output/logger.ts";
+
+interface PingResult {
+  server: string;
+  success: boolean;
+  latencyMs?: number;
+  error?: string;
+}
+
+export function registerPingCommand(program: Command) {
+  program
+    .command("ping [servers...]")
+    .description("Check connectivity to MCP servers")
+    .action(async (servers: string[]) => {
+      const { manager, formatOptions } = await getContext(program);
+
+      const targetServers = servers.length > 0 ? servers : manager.getServerNames();
+
+      if (targetServers.length === 0) {
+        console.error(formatError("No servers configured", formatOptions));
+        await manager.close();
+        process.exit(1);
+      }
+
+      const spinner = logger.startSpinner(
+        `Pinging ${targetServers.length} server(s)...`,
+        formatOptions,
+      );
+
+      const results: PingResult[] = [];
+
+      try {
+        await Promise.all(
+          targetServers.map(async (serverName) => {
+            const start = Date.now();
+            try {
+              await manager.getClient(serverName);
+              results.push({ server: serverName, success: true, latencyMs: Date.now() - start });
+            } catch (err) {
+              results.push({ server: serverName, success: false, error: String(err) });
+            }
+          }),
+        );
+
+        spinner.stop();
+
+        if (formatOptions.json) {
+          console.log(JSON.stringify(results, null, 2));
+        } else {
+          for (const r of results) {
+            if (r.success) {
+              console.log(`${green("✔")} ${r.server} connected (${r.latencyMs}ms)`);
+            } else {
+              console.log(`${red("✖")} ${r.server} failed: ${r.error}`);
+            }
+          }
+        }
+      } finally {
+        await manager.close();
+      }
+
+      const anyFailed = results.some((r) => !r.success);
+      if (anyFailed) process.exit(1);
+    });
+}

package/src/commands/prompt.ts

@@ -0,0 +1,60 @@
+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";
+
+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 {
+          if (server && name) {
+            let args: Record<string, string> | undefined;
+
+            if (argsStr) {
+              args = parseJsonArgs(argsStr, { coerceToString: true }) as Record<string, string>;
+            } else if (!process.stdin.isTTY) {
+              const stdin = await readStdin();
+              if (stdin.trim()) {
+                args = parseJsonArgs(stdin, { coerceToString: true }) as Record<string, string>;
+              }
+            }
+
+            const result = await manager.getPrompt(server, name, args);
+            spinner.stop();
+            console.log(formatPromptMessages(server, name, result, formatOptions));
+          } else if (server) {
+            const prompts = await manager.listPrompts(server);
+            spinner.stop();
+            console.log(formatServerPrompts(server, prompts, formatOptions));
+          } else {
+            const { prompts, errors } = await manager.getAllPrompts();
+            spinner.stop();
+            console.log(formatPromptList(prompts, formatOptions));
+            for (const err of errors) {
+              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/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/src/commands/resource.ts

@@ -0,0 +1,46 @@
+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";
+
+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));
+          }
+        }
+      } catch (err) {
+        spinner.error("Failed");
+        console.error(formatError(String(err), formatOptions));
+        process.exit(1);
+      } finally {
+        await manager.close();
+      }
+    });
+}

package/src/commands/search.ts

@@ -0,0 +1,49 @@
+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")
+    .option("-n, --limit <number>", "max results to return", "10")
+    .action(
+      async (terms: string[], options: { keyword?: boolean; query?: boolean; limit: string }) => {
+        const query = terms.join(" ");
+        const { config, formatOptions } = await getContext(program);
+
+        if (config.searchIndex.tools.length === 0) {
+          console.error(formatError("No search index found. Run: mcpx 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: mcpx index`,
+          );
+        }
+
+        const spinner = logger.startSpinner("Searching...", formatOptions);
+
+        try {
+          const results = await search(query, config.searchIndex, {
+            keywordOnly: options.keyword,
+            semanticOnly: options.query,
+            topK: parseInt(options.limit, 10),
+          });
+          spinner.stop();
+          console.log(formatSearchResults(results, formatOptions));
+        } catch (err) {
+          spinner.stop();
+          console.error(formatError(String(err), formatOptions));
+          process.exit(1);
+        }
+      },
+    );
+}

package/src/commands/servers.ts

@@ -0,0 +1,66 @@
+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";
+
+export function registerServersCommand(program: Command) {
+  program
+    .command("servers")
+    .description("List configured MCP servers")
+    .action(async () => {
+      const { manager, config, formatOptions } = await getContext(program);
+      try {
+        const servers = Object.entries(config.servers.mcpServers);
+
+        if (!isInteractive(formatOptions)) {
+          console.log(
+            JSON.stringify(
+              servers.map(([name, cfg]) => ({
+                name,
+                type: isStdioServer(cfg) ? "stdio" : "http",
+                ...(isHttpServer(cfg) ? { transport: cfg.transport ?? "http" } : {}),
+                ...(isStdioServer(cfg)
+                  ? { command: cfg.command, args: cfg.args ?? [] }
+                  : { url: cfg.url }),
+              })),
+              null,
+              2,
+            ),
+          );
+          return;
+        }
+
+        if (servers.length === 0) {
+          console.log(dim("No servers configured"));
+          return;
+        }
+
+        const maxName = Math.max(...servers.map(([n]) => n.length));
+
+        function typeLabel(cfg: (typeof servers)[number][1]): string {
+          if (isStdioServer(cfg)) return "stdio";
+          if (isHttpServer(cfg) && cfg.transport === "sse") return "http/sse";
+          if (isHttpServer(cfg) && cfg.transport === "streamable-http") return "http/streamable";
+          return "http";
+        }
+        const maxType = Math.max(...servers.map(([, cfg]) => typeLabel(cfg).length));
+
+        for (const [name, cfg] of servers) {
+          const n = cyan(name.padEnd(maxName));
+          const type = isStdioServer(cfg)
+            ? green(typeLabel(cfg).padEnd(maxType))
+            : yellow(typeLabel(cfg).padEnd(maxType));
+          const detail = isStdioServer(cfg)
+            ? dim([cfg.command, ...(cfg.args ?? [])].join(" "))
+            : 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/skill.ts

@@ -0,0 +1,112 @@
+import type { Command } from "commander";
+import { resolve, dirname, join } from "path";
+import { readFile, mkdir, writeFile, access } from "fs/promises";
+import { homedir } from "os";
+
+interface SkillTarget {
+  label: string;
+  dir: string;
+  filename: string;
+}
+
+export function registerSkillCommand(program: Command) {
+  const skill = program.command("skill").description("manage mcpx skills");
+
+  skill
+    .command("install")
+    .description("install the mcpx skill for an AI agent")
+    .option("--claude", "install for Claude Code")
+    .option("--cursor", "install for Cursor")
+    .option("--global", "install to global location (e.g. ~/.claude/skills/)")
+    .option("--project", "install to project location (default)")
+    .option("-f, --force", "overwrite if file already exists")
+    .action(
+      async (options: {
+        claude?: boolean;
+        cursor?: boolean;
+        global?: boolean;
+        project?: boolean;
+        force?: boolean;
+      }) => {
+        if (!options.claude && !options.cursor) {
+          console.error("error: specify at least one agent target: --claude, --cursor");
+          process.exit(1);
+        }
+
+        const agents: {
+          name: string;
+          sourcePath: string;
+          globalDir: string;
+          projectDir: string;
+          filename: string;
+        }[] = [];
+
+        if (options.claude) {
+          agents.push({
+            name: "Claude Code",
+            sourcePath: resolve(dirname(Bun.main), "..", ".claude", "skills", "mcpx.md"),
+            globalDir: join(homedir(), ".claude", "skills"),
+            projectDir: resolve(".claude", "skills"),
+            filename: "mcpx.md",
+          });
+        }
+
+        if (options.cursor) {
+          agents.push({
+            name: "Cursor",
+            sourcePath: resolve(dirname(Bun.main), "..", ".cursor", "rules", "mcpx.mdc"),
+            globalDir: join(homedir(), ".cursor", "rules"),
+            projectDir: resolve(".cursor", "rules"),
+            filename: "mcpx.mdc",
+          });
+        }
+
+        for (const agent of agents) {
+          let content: string;
+          try {
+            content = await readFile(agent.sourcePath, "utf-8");
+          } catch {
+            console.error(`Could not read skill file: ${agent.sourcePath}`);
+            process.exit(1);
+          }
+
+          // Determine targets — default to project if neither flag is set
+          const targets: SkillTarget[] = [];
+
+          if (options.global) {
+            targets.push({
+              label: "global",
+              dir: agent.globalDir,
+              filename: agent.filename,
+            });
+          }
+          if (options.project || !options.global) {
+            targets.push({
+              label: "project",
+              dir: agent.projectDir,
+              filename: agent.filename,
+            });
+          }
+
+          for (const target of targets) {
+            const dest = join(target.dir, target.filename);
+
+            // 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 mcpx skill for ${agent.name} (${target.label}): ${dest}`);
+          }
+        }
+      },
+    );
+}

package/src/commands/task.ts

@@ -0,0 +1,82 @@
+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";
+
+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);
+
+      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);
+            }
+            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);
+            }
+            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);
+            }
+            const cancelled = await manager.cancelTask(server, taskId);
+            spinner.stop();
+            console.log(formatTaskStatus(cancelled, formatOptions));
+            break;
+          }
+          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/config/env.ts

@@ -0,0 +1,41 @@
+const ENV_VAR_PATTERN = /\$\{([^}]+)\}/g;
+
+/** Whether to throw on missing env vars (default: true) */
+function isStrictEnv(): boolean {
+  return process.env.MCP_STRICT_ENV !== "false";
+}
+
+/** Replace ${VAR_NAME} in a string with the corresponding env var value */
+export function interpolateEnvString(value: string): string {
+  return value.replace(ENV_VAR_PATTERN, (_match, varName: string) => {
+    const envValue = process.env[varName];
+    if (envValue === undefined) {
+      if (isStrictEnv()) {
+        throw new Error(
+          `Environment variable "${varName}" is not set (set MCP_STRICT_ENV=false to warn instead)`,
+        );
+      }
+      console.warn(`Warning: environment variable "${varName}" is not set`);
+      return "";
+    }
+    return envValue;
+  });
+}
+
+/** Recursively interpolate env vars in all string values of an object */
+export function interpolateEnv<T>(obj: T): T {
+  if (typeof obj === "string") {
+    return interpolateEnvString(obj) as T;
+  }
+  if (Array.isArray(obj)) {
+    return obj.map((item) => interpolateEnv(item)) as T;
+  }
+  if (typeof obj === "object" && obj !== null) {
+    const result: Record<string, unknown> = {};
+    for (const [key, value] of Object.entries(obj)) {
+      result[key] = interpolateEnv(value);
+    }
+    return result as T;
+  }
+  return obj;
+}