@evantahler/mcpcli 0.1.4 → 0.2.3

package/README.md

@@ -65,6 +65,9 @@ mcpcli search -q "manage pull requests"
 | `mcpcli auth <server> -s`            | Check auth status and token TTL              |
 | `mcpcli auth <server> -r`            | Force token refresh                          |
 | `mcpcli deauth <server>`             | Remove stored authentication for a server    |
+| `mcpcli add <name> --command <cmd>`  | Add a stdio MCP server to your config        |
+| `mcpcli add <name> --url <url>`      | Add an HTTP MCP server to your config        |
+| `mcpcli remove <name>`               | Remove an MCP server from your config        |
 
 ## Options
 
@@ -79,6 +82,57 @@ mcpcli search -q "manage pull requests"
 | `-j, --json`              | Force JSON output (default when piped)             |
 | `--no-daemon`             | Disable connection pooling                         |
 
+## Managing Servers
+
+Add and remove servers from the CLI — no manual JSON editing required.
+
+```bash
+# Add a stdio server
+mcpcli add filesystem --command npx --args "-y,@modelcontextprotocol/server-filesystem,/tmp"
+
+# Add an HTTP server with headers
+mcpcli add my-api --url https://api.example.com/mcp --header "Authorization:Bearer tok123"
+
+# Add with tool filtering
+mcpcli add github --url https://mcp.github.com --allowed-tools "search_*,get_*"
+
+# Add with environment variables
+mcpcli add my-server --command node --args "server.js" --env "API_KEY=sk-123,DEBUG=true"
+
+# Overwrite an existing server
+mcpcli add filesystem --command echo --force
+
+# Remove a server (also cleans up auth.json)
+mcpcli remove filesystem
+
+# Remove but keep stored auth credentials
+mcpcli remove my-api --keep-auth
+
+# Preview what would be removed
+mcpcli remove my-api --dry-run
+```
+
+**`add` options:**
+
+| Flag                       | Purpose                                |
+| -------------------------- | -------------------------------------- |
+| `--command <cmd>`          | Command to run (stdio server)          |
+| `--args <a1,a2,...>`       | Comma-separated arguments              |
+| `--env <KEY=VAL,...>`      | Comma-separated environment variables  |
+| `--cwd <dir>`              | Working directory for the command      |
+| `--url <url>`              | Server URL (HTTP server)               |
+| `--header <Key:Value>`     | HTTP header (repeatable)               |
+| `--allowed-tools <t1,t2>`  | Comma-separated allowed tool patterns  |
+| `--disabled-tools <t1,t2>` | Comma-separated disabled tool patterns |
+| `-f, --force`              | Overwrite if server already exists     |
+
+**`remove` options:**
+
+| Flag          | Purpose                                           |
+| ------------- | ------------------------------------------------- |
+| `--keep-auth` | Don't remove stored auth credentials              |
+| `--dry-run`   | Show what would be removed without changing files |
+
 ## Configuration
 
 Config lives in `~/.config/mcpcli/` (or the current directory). Three files:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@evantahler/mcpcli",
-  "version": "0.1.4",
+  "version": "0.2.3",
   "description": "A command-line interface for MCP servers. curl for MCP.",
   "type": "module",
   "bin": {

package/src/cli.ts

@@ -7,6 +7,8 @@ import { registerSearchCommand } from "./commands/search.ts";
 import { registerCallCommand } from "./commands/call.ts";
 import { registerAuthCommand, registerDeauthCommand } from "./commands/auth.ts";
 import { registerIndexCommand } from "./commands/index.ts";
+import { registerAddCommand } from "./commands/add.ts";
+import { registerRemoveCommand } from "./commands/remove.ts";
 
 declare const BUILD_VERSION: string | undefined;
 
@@ -20,8 +22,7 @@ program
   .option("-d, --with-descriptions", "include tool descriptions in output")
   .option("-j, --json", "force JSON output")
   .option("-v, --verbose", "show HTTP request/response details")
-  .option("-S, --show-secrets", "show full auth tokens in verbose output")
-  .option("--no-daemon", "disable connection pooling");
+  .option("-S, --show-secrets", "show full auth tokens in verbose output");
 
 registerListCommand(program);
 registerInfoCommand(program);
@@ -30,5 +31,7 @@ registerCallCommand(program);
 registerAuthCommand(program);
 registerDeauthCommand(program);
 registerIndexCommand(program);
+registerAddCommand(program);
+registerRemoveCommand(program);
 
 program.parse();

package/src/client/manager.ts

@@ -17,6 +17,17 @@ export interface ServerError {
   message: string;
 }
 
+export interface ServerManagerOptions {
+  servers: ServersFile;
+  configDir: string;
+  auth: AuthFile;
+  concurrency?: number;
+  verbose?: boolean;
+  showSecrets?: boolean;
+  timeout?: number; // ms, default 1_800_000 (30 min)
+  maxRetries?: number; // default 3
+}
+
 export class ServerManager {
   private clients = new Map<string, Client>();
   private transports = new Map<string, Transport>();
@@ -27,21 +38,18 @@ export class ServerManager {
   private concurrency: number;
   private verbose: boolean;
   private showSecrets: boolean;
+  private timeout: number;
+  private maxRetries: number;
 
-  constructor(
-    servers: ServersFile,
-    configDir: string,
-    auth: AuthFile,
-    concurrency = 5,
-    verbose = false,
-    showSecrets = false,
-  ) {
-    this.servers = servers;
-    this.configDir = configDir;
-    this.auth = auth;
-    this.concurrency = concurrency;
-    this.verbose = verbose;
-    this.showSecrets = showSecrets;
+  constructor(opts: ServerManagerOptions) {
+    this.servers = opts.servers;
+    this.configDir = opts.configDir;
+    this.auth = opts.auth;
+    this.concurrency = opts.concurrency ?? 5;
+    this.verbose = opts.verbose ?? false;
+    this.showSecrets = opts.showSecrets ?? false;
+    this.timeout = opts.timeout ?? 1_800_000;
+    this.maxRetries = opts.maxRetries ?? 3;
   }
 
   /** Get or create a connected client for a server */
@@ -71,7 +79,7 @@ export class ServerManager {
     this.transports.set(serverName, transport);
 
     const client = new Client({ name: "mcpcli", version: "0.1.0" });
-    await client.connect(transport);
+    await this.withTimeout(client.connect(transport), `connect(${serverName})`);
     this.clients.set(serverName, client);
 
     return client;
@@ -110,12 +118,57 @@ export class ServerManager {
     throw new Error("Invalid server config");
   }
 
+  /** Race a promise against a timeout */
+  private withTimeout<T>(promise: Promise<T>, label: string): Promise<T> {
+    if (this.timeout <= 0) return promise;
+    let timer: ReturnType<typeof setTimeout>;
+    return Promise.race([
+      promise.finally(() => clearTimeout(timer)),
+      new Promise<never>((_, reject) => {
+        timer = setTimeout(
+          () => reject(new Error(`${label}: timed out after ${this.timeout / 1000}s`)),
+          this.timeout,
+        );
+        timer.unref();
+      }),
+    ]);
+  }
+
+  /** Retry a function up to maxRetries times, clearing cached client between attempts */
+  private async withRetry<T>(fn: () => Promise<T>, label: string, serverName?: string): Promise<T> {
+    let lastError: Error | undefined;
+    for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
+      try {
+        return await fn();
+      } catch (err) {
+        lastError = err instanceof Error ? err : new Error(String(err));
+        if (attempt < this.maxRetries && serverName) {
+          // Clear cached client so next attempt reconnects fresh
+          try {
+            await this.clients.get(serverName)?.close();
+          } catch {
+            // ignore close errors
+          }
+          this.clients.delete(serverName);
+          this.transports.delete(serverName);
+        }
+      }
+    }
+    throw lastError;
+  }
+
   /** List tools for a single server, applying allowedTools/disabledTools filters */
   async listTools(serverName: string): Promise<Tool[]> {
-    const client = await this.getClient(serverName);
-    const result = await client.listTools();
-    const config = this.servers.mcpServers[serverName]!;
-    return filterTools(result.tools, config.allowedTools, config.disabledTools);
+    return this.withRetry(
+      async () => {
+        const client = await this.getClient(serverName);
+        const result = await this.withTimeout(client.listTools(), `listTools(${serverName})`);
+        const config = this.servers.mcpServers[serverName]!;
+        return filterTools(result.tools, config.allowedTools, config.disabledTools);
+      },
+      `listTools(${serverName})`,
+      serverName,
+    );
   }
 
   /** List tools across all configured servers */
@@ -156,8 +209,17 @@ export class ServerManager {
     toolName: string,
     args: Record<string, unknown> = {},
   ): Promise<unknown> {
-    const client = await this.getClient(serverName);
-    return client.callTool({ name: toolName, arguments: args });
+    return this.withRetry(
+      async () => {
+        const client = await this.getClient(serverName);
+        return this.withTimeout(
+          client.callTool({ name: toolName, arguments: args }),
+          `callTool(${serverName}/${toolName})`,
+        );
+      },
+      `callTool(${serverName}/${toolName})`,
+      serverName,
+    );
   }
 
   /** Get the schema for a specific tool */

package/src/commands/add.ts

@@ -0,0 +1,137 @@
+import type { Command } from "commander";
+import type { ServerConfig } from "../config/schemas.ts";
+import { loadRawServers, saveServers } from "../config/loader.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-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;
+          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`);
+
+        // 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

@@ -4,6 +4,7 @@ import { isHttpServer } from "../config/schemas.ts";
 import { saveAuth } from "../config/loader.ts";
 import { McpOAuthProvider, runOAuthFlow } from "../client/oauth.ts";
 import { startSpinner } from "../output/spinner.ts";
+import { runIndex } from "./index.ts";
 
 export function registerAuthCommand(program: Command) {
   program
@@ -11,54 +12,61 @@ export function registerAuthCommand(program: Command) {
     .description("authenticate with an HTTP MCP server")
     .option("-s, --status", "check auth status and token TTL")
     .option("-r, --refresh", "force token refresh")
-    .action(async (server: string, options: { status?: boolean; refresh?: boolean }) => {
-      const { config, formatOptions } = await getContext(program);
+    .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 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,
-      });
+        const provider = new McpOAuthProvider({
+          serverName: server,
+          configDir: config.configDir,
+          auth: config.auth,
+        });
 
-      if (options.status) {
-        showStatus(server, provider);
-        return;
-      }
+        if (options.status) {
+          showStatus(server, provider);
+          return;
+        }
+
+        if (options.refresh) {
+          const spinner = 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;
+        }
 
-      if (options.refresh) {
-        const spinner = startSpinner(`Refreshing token for "${server}"…`, formatOptions);
+        // Default: full OAuth flow
+        const spinner = startSpinner(`Authenticating with "${server}"…`, formatOptions);
         try {
-          await provider.refreshIfNeeded(serverConfig.url);
-          spinner.success(`Token refreshed for "${server}"`);
+          await runOAuthFlow(serverConfig.url, provider);
+          spinner.success(`Authenticated with "${server}"`);
         } catch (err) {
-          spinner.error(`Refresh failed: ${err instanceof Error ? err.message : err}`);
+          spinner.error(`Authentication failed: ${err instanceof Error ? err.message : err}`);
           process.exit(1);
         }
-        return;
-      }
 
-      // Default: full OAuth flow
-      const spinner = 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) {

package/src/commands/index.ts

@@ -1,20 +1,47 @@
 import type { Command } from "commander";
-import { dim } from "ansis";
+import { dim, 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 { startSpinner } from "../output/spinner.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 = 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`);
+
+    if (process.stderr.isTTY) {
+      process.stderr.write(dim(`Saved to ${config.configDir}/search.json\n`));
+    }
+  } 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 }) => {
-      const { config, manager, formatOptions } = await getContext(program);
-
       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");
@@ -22,32 +49,16 @@ export function registerIndexCommand(program: Command) {
           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;
       }
 
-      const spinner = 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`);
-
-        if (process.stderr.isTTY) {
-          process.stderr.write(dim(`Saved to ${config.configDir}/search.json\n`));
-        }
-      } catch (err) {
-        spinner.error("Indexing failed");
-        console.error(formatError(String(err), formatOptions));
-        process.exit(1);
-      } finally {
-        await manager.close();
-      }
+      await runIndex(program);
     });
 }

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/search.ts

@@ -1,6 +1,8 @@
 import type { Command } from "commander";
+import { yellow } from "ansis";
 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 { startSpinner } from "../output/spinner.ts";
 
@@ -19,6 +21,15 @@ export function registerSearchCommand(program: Command) {
         process.exit(1);
       }
 
+      const stale = getStaleServers(config.searchIndex, config.servers);
+      if (stale.length > 0) {
+        process.stderr.write(
+          yellow(
+            `Warning: index has tools for removed servers: ${stale.join(", ")}. Run: mcpcli index\n`,
+          ),
+        );
+      }
+
       const spinner = startSpinner("Searching...", formatOptions);
 
       try {

package/src/config/loader.ts

@@ -112,7 +112,45 @@ export async function saveAuth(configDir: string, auth: AuthFile): Promise<void>
   await Bun.write(join(configDir, "auth.json"), JSON.stringify(auth, null, 2) + "\n");
 }
 
+/** Load search.json from the config directory */
+export async function loadSearchIndex(configDir: string): Promise<SearchIndex> {
+  const raw = await readJsonFile(join(configDir, "search.json"));
+  return raw !== undefined ? validateSearchIndex(raw) : { ...EMPTY_SEARCH_INDEX };
+}
+
 /** Save search.json to the config directory */
 export async function saveSearchIndex(configDir: string, index: SearchIndex): Promise<void> {
   await Bun.write(join(configDir, "search.json"), JSON.stringify(index, null, 2) + "\n");
 }
+
+/** Save servers.json to the config directory */
+export async function saveServers(configDir: string, servers: ServersFile): Promise<void> {
+  await Bun.write(join(configDir, "servers.json"), JSON.stringify(servers, null, 2) + "\n");
+}
+
+/** Load servers.json without env interpolation (preserves ${VAR} placeholders) */
+export async function loadRawServers(
+  configFlag?: string,
+): Promise<{ configDir: string; servers: ServersFile }> {
+  let configDir = resolveConfigDir(configFlag);
+
+  if (!(await hasServersFile(configDir))) {
+    const cwd = process.cwd();
+    if (await hasServersFile(cwd)) {
+      configDir = cwd;
+    }
+  }
+
+  const serversPath = join(configDir, "servers.json");
+  const raw = await readJsonFile(serversPath);
+  const servers = raw !== undefined ? validateServersFile(raw) : EMPTY_SERVERS;
+
+  return { configDir, servers };
+}
+
+/** Load auth.json without loading the full config */
+export async function loadRawAuth(configDir: string): Promise<AuthFile> {
+  const authPath = join(configDir, "auth.json");
+  const raw = await readJsonFile(authPath);
+  return raw !== undefined ? validateAuthFile(raw) : EMPTY_AUTH;
+}

package/src/context.ts

@@ -18,17 +18,26 @@ export async function getContext(program: Command): Promise<AppContext> {
     configFlag: opts.config as string | undefined,
   });
 
-  const verbose = !!(opts.verbose as boolean | undefined);
+  const verbose = !!(
+    (opts.verbose as boolean | undefined) ||
+    process.env.MCP_DEBUG === "1" ||
+    process.env.MCP_DEBUG === "true"
+  );
   const showSecrets = !!(opts.showSecrets as boolean | undefined);
   const concurrency = Number(process.env.MCP_CONCURRENCY ?? 5);
-  const manager = new ServerManager(
-    config.servers,
-    config.configDir,
-    config.auth,
+  const timeout = Number(process.env.MCP_TIMEOUT ?? 1800) * 1000;
+  const maxRetries = Number(process.env.MCP_MAX_RETRIES ?? 3);
+
+  const manager = new ServerManager({
+    servers: config.servers,
+    configDir: config.configDir,
+    auth: config.auth,
     concurrency,
     verbose,
     showSecrets,
-  );
+    timeout,
+    maxRetries,
+  });
 
   const formatOptions: FormatOptions = {
     json: opts.json as boolean | undefined,

package/src/search/staleness.ts

@@ -0,0 +1,8 @@
+import type { SearchIndex, ServersFile } from "../config/schemas.ts";
+
+/** Return server names that appear in the index but not in the current config */
+export function getStaleServers(index: SearchIndex, servers: ServersFile): string[] {
+  const configured = new Set(Object.keys(servers.mcpServers));
+  const indexed = new Set(index.tools.map((t) => t.server));
+  return [...indexed].filter((s) => !configured.has(s));
+}