@evantahler/mcpcli 0.1.1

package/src/commands/call.ts

@@ -0,0 +1,104 @@
+import type { Command } from "commander";
+import { getContext } from "../context.ts";
+import {
+  formatCallResult,
+  formatError,
+  formatServerTools,
+  formatToolHelp,
+  formatValidationErrors,
+} from "../output/formatter.ts";
+import { startSpinner } from "../output/spinner.ts";
+import { validateToolInput } from "../validation/schema.ts";
+
+export function registerCallCommand(program: Command) {
+  program
+    .command("call <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 {
+        // No args + interactive terminal → show tool help with example payload
+        const hasArgs = !!argsStr;
+        const hasStdin = !process.stdin.isTTY;
+        if (!hasArgs && !hasStdin) {
+          const toolSchema = await manager.getToolSchema(server, tool);
+          if (toolSchema) {
+            console.log(formatToolHelp(server, toolSchema, formatOptions));
+            await manager.close();
+            return;
+          }
+        }
+
+        // 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 = startSpinner(`Calling ${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/src/commands/index.ts

@@ -0,0 +1,53 @@
+import type { Command } from "commander";
+import { dim } from "ansis";
+import { getContext } from "../context.ts";
+import { buildSearchIndex } from "../search/indexer.ts";
+import { saveSearchIndex } from "../config/loader.ts";
+import { formatError } from "../output/formatter.ts";
+import { startSpinner } from "../output/spinner.ts";
+
+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 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}`);
+        }
+        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();
+      }
+    });
+}

package/src/commands/info.ts

@@ -0,0 +1,42 @@
+import type { Command } from "commander";
+import { getContext } from "../context.ts";
+import { formatServerTools, formatToolSchema, formatError } from "../output/formatter.ts";
+import { startSpinner } from "../output/spinner.ts";
+
+export function registerInfoCommand(program: Command) {
+  program
+    .command("info <target>")
+    .description("show tools for a server, or schema for a specific tool")
+    .action(async (target: string) => {
+      const { manager, formatOptions } = await getContext(program);
+      const spinner = startSpinner(`Connecting to ${target}...`, formatOptions);
+      try {
+        // Parse "server/tool" or "server tool" format
+        const slashIndex = target.indexOf("/");
+        if (slashIndex !== -1) {
+          const serverName = target.slice(0, slashIndex);
+          const toolName = target.slice(slashIndex + 1);
+          const tool = await manager.getToolSchema(serverName, toolName);
+          spinner.stop();
+          if (!tool) {
+            console.error(
+              formatError(`Tool "${toolName}" not found on server "${serverName}"`, formatOptions),
+            );
+            process.exit(1);
+          }
+          console.log(formatToolSchema(serverName, tool, formatOptions));
+        } else {
+          // Just a server name — list its tools
+          const tools = await manager.listTools(target);
+          spinner.stop();
+          console.log(formatServerTools(target, 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/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 { startSpinner } from "../output/spinner.ts";
+
+export function registerListCommand(program: Command) {
+  program.action(async () => {
+    const { manager, formatOptions } = await getContext(program);
+    const spinner = 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/src/commands/search.ts

@@ -0,0 +1,37 @@
+import type { Command } from "commander";
+import { getContext } from "../context.ts";
+import { search } from "../search/index.ts";
+import { formatError, formatSearchResults } from "../output/formatter.ts";
+import { startSpinner } from "../output/spinner.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 spinner = 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/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;
+}

package/src/config/loader.ts

@@ -0,0 +1,118 @@
+import { join, resolve } from "path";
+import { homedir } from "os";
+import { interpolateEnv } from "./env.ts";
+import {
+  type Config,
+  type ServersFile,
+  type AuthFile,
+  type SearchIndex,
+  validateServersFile,
+  validateAuthFile,
+  validateSearchIndex,
+} from "./schemas.ts";
+
+const DEFAULT_CONFIG_DIR = join(homedir(), ".config", "mcpcli");
+
+const EMPTY_SERVERS: ServersFile = { mcpServers: {} };
+const EMPTY_AUTH: AuthFile = {};
+const EMPTY_SEARCH_INDEX: SearchIndex = {
+  version: 1,
+  indexed_at: "",
+  embedding_model: "claude",
+  tools: [],
+};
+
+/** Read and parse a JSON file, returning undefined if it doesn't exist */
+async function readJsonFile(path: string): Promise<unknown | undefined> {
+  const file = Bun.file(path);
+  if (!(await file.exists())) return undefined;
+  const text = await file.text();
+  return JSON.parse(text);
+}
+
+/** Resolve the config directory from options, env, cwd, or default */
+function resolveConfigDir(configFlag?: string): string {
+  // 1. -c / --config flag
+  if (configFlag) return resolve(configFlag);
+
+  // 2. MCP_CONFIG_PATH env var
+  const envPath = process.env.MCP_CONFIG_PATH;
+  if (envPath) return resolve(envPath);
+
+  // 3. ./servers.json exists in cwd → use cwd
+  // (checked at load time, not here — we return the candidate dir)
+
+  // 4. Default ~/.config/mcpcli/
+  return DEFAULT_CONFIG_DIR;
+}
+
+/** Check if servers.json exists in the given directory */
+async function hasServersFile(dir: string): Promise<boolean> {
+  return Bun.file(join(dir, "servers.json")).exists();
+}
+
+export interface LoadConfigOptions {
+  configFlag?: string;
+}
+
+/** Load and validate all config files */
+export async function loadConfig(options: LoadConfigOptions = {}): Promise<Config> {
+  // Resolve config directory
+  let configDir = resolveConfigDir(options.configFlag);
+
+  // If the resolved dir doesn't have servers.json, check cwd
+  if (!(await hasServersFile(configDir))) {
+    const cwd = process.cwd();
+    if (await hasServersFile(cwd)) {
+      configDir = cwd;
+    }
+  }
+
+  // Ensure config directory exists
+  await Bun.write(join(configDir, ".keep"), "").catch(() => {});
+  // Remove the .keep file, it was just to ensure the dir
+  Bun.file(join(configDir, ".keep"))
+    .exists()
+    .then((exists) => {
+      if (exists) Bun.write(join(configDir, ".keep"), "");
+    });
+
+  // Load servers.json
+  const serversPath = join(configDir, "servers.json");
+  const rawServers = await readJsonFile(serversPath);
+  let servers: ServersFile;
+  if (rawServers === undefined) {
+    servers = EMPTY_SERVERS;
+  } else {
+    servers = validateServersFile(rawServers);
+    // Interpolate env vars in server configs
+    servers = {
+      mcpServers: Object.fromEntries(
+        Object.entries(servers.mcpServers).map(([name, config]) => [name, interpolateEnv(config)]),
+      ),
+    };
+  }
+
+  // Load auth.json
+  const authPath = join(configDir, "auth.json");
+  const rawAuth = await readJsonFile(authPath);
+  const auth: AuthFile = rawAuth !== undefined ? validateAuthFile(rawAuth) : EMPTY_AUTH;
+
+  // Load search.json
+  const searchPath = join(configDir, "search.json");
+  const rawSearch = await readJsonFile(searchPath);
+  const searchIndex: SearchIndex =
+    rawSearch !== undefined ? validateSearchIndex(rawSearch) : EMPTY_SEARCH_INDEX;
+
+  return { configDir, servers, auth, searchIndex };
+}
+
+/** Save auth.json to the config directory */
+export async function saveAuth(configDir: string, auth: AuthFile): Promise<void> {
+  await Bun.write(join(configDir, "auth.json"), JSON.stringify(auth, null, 2) + "\n");
+}
+
+/** 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");
+}

package/src/config/schemas.ts

@@ -0,0 +1,137 @@
+import type { Tool } from "@modelcontextprotocol/sdk/types.js";
+import type {
+  OAuthTokens,
+  OAuthClientInformation,
+  OAuthClientInformationMixed,
+} from "@modelcontextprotocol/sdk/shared/auth.js";
+
+// Re-export SDK types we use throughout the codebase
+export type { Tool, OAuthTokens, OAuthClientInformation, OAuthClientInformationMixed };
+
+// --- Server config (our format, not MCP spec) ---
+
+/** Stdio MCP server config */
+export interface StdioServerConfig {
+  command: string;
+  args?: string[];
+  env?: Record<string, string>;
+  cwd?: string;
+  allowedTools?: string[];
+  disabledTools?: string[];
+}
+
+/** HTTP MCP server config */
+export interface HttpServerConfig {
+  url: string;
+  headers?: Record<string, string>;
+  allowedTools?: string[];
+  disabledTools?: string[];
+}
+
+export type ServerConfig = StdioServerConfig | HttpServerConfig;
+
+export function isStdioServer(config: ServerConfig): config is StdioServerConfig {
+  return "command" in config;
+}
+
+export function isHttpServer(config: ServerConfig): config is HttpServerConfig {
+  return "url" in config;
+}
+
+/** Top-level servers.json shape */
+export interface ServersFile {
+  mcpServers: Record<string, ServerConfig>;
+}
+
+// --- Auth storage (wraps SDK's OAuthTokens with our persistence fields) ---
+
+/** Per-server auth entry stored in auth.json */
+export interface AuthEntry {
+  tokens: OAuthTokens;
+  expires_at?: string;
+  client_info?: OAuthClientInformationMixed;
+  complete?: boolean;
+}
+
+/** Top-level auth.json shape */
+export type AuthFile = Record<string, AuthEntry>;
+
+// --- Search index (entirely our format) ---
+
+/** A single tool entry in the search index */
+export interface IndexedTool {
+  server: string;
+  tool: string;
+  description: string;
+  input_schema?: Tool["inputSchema"];
+  scenarios: string[];
+  keywords: string[];
+  embedding: number[];
+}
+
+/** Top-level search.json shape */
+export interface SearchIndex {
+  version: number;
+  indexed_at: string;
+  embedding_model: string;
+  tools: IndexedTool[];
+}
+
+// --- Combined config ---
+
+/** Validated config returned by loadConfig */
+export interface Config {
+  configDir: string;
+  servers: ServersFile;
+  auth: AuthFile;
+  searchIndex: SearchIndex;
+}
+
+// --- Validation ---
+
+/** Validate that a parsed object looks like a valid servers.json */
+export function validateServersFile(data: unknown): ServersFile {
+  if (typeof data !== "object" || data === null) {
+    throw new Error("servers.json must be a JSON object");
+  }
+
+  const obj = data as Record<string, unknown>;
+  if (typeof obj.mcpServers !== "object" || obj.mcpServers === null) {
+    throw new Error('servers.json must have a "mcpServers" object');
+  }
+
+  const servers = obj.mcpServers as Record<string, unknown>;
+  for (const [name, config] of Object.entries(servers)) {
+    if (typeof config !== "object" || config === null) {
+      throw new Error(`Server "${name}" must be an object`);
+    }
+    const c = config as Record<string, unknown>;
+    const hasCommand = typeof c.command === "string";
+    const hasUrl = typeof c.url === "string";
+    if (!hasCommand && !hasUrl) {
+      throw new Error(`Server "${name}" must have either "command" (stdio) or "url" (http)`);
+    }
+  }
+
+  return data as ServersFile;
+}
+
+/** Validate auth.json — lenient, just check shape */
+export function validateAuthFile(data: unknown): AuthFile {
+  if (typeof data !== "object" || data === null) {
+    throw new Error("auth.json must be a JSON object");
+  }
+  return data as AuthFile;
+}
+
+/** Validate search.json — lenient, just check shape */
+export function validateSearchIndex(data: unknown): SearchIndex {
+  if (typeof data !== "object" || data === null) {
+    throw new Error("search.json must be a JSON object");
+  }
+  const obj = data as Record<string, unknown>;
+  if (!Array.isArray(obj.tools)) {
+    throw new Error('search.json must have a "tools" array');
+  }
+  return data as SearchIndex;
+}

package/src/context.ts

@@ -0,0 +1,41 @@
+import type { Command } from "commander";
+import { loadConfig, type LoadConfigOptions } from "./config/loader.ts";
+import { ServerManager } from "./client/manager.ts";
+import type { Config } from "./config/schemas.ts";
+import type { FormatOptions } from "./output/formatter.ts";
+
+export interface AppContext {
+  config: Config;
+  manager: ServerManager;
+  formatOptions: FormatOptions;
+}
+
+/** Build the app context from the root commander program options */
+export async function getContext(program: Command): Promise<AppContext> {
+  const opts = program.opts();
+
+  const config = await loadConfig({
+    configFlag: opts.config as string | undefined,
+  });
+
+  const verbose = !!(opts.verbose as boolean | undefined);
+  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,
+    concurrency,
+    verbose,
+    showSecrets,
+  );
+
+  const formatOptions: FormatOptions = {
+    json: opts.json as boolean | undefined,
+    withDescriptions: opts.withDescriptions as boolean | undefined,
+    verbose,
+    showSecrets,
+  };
+
+  return { config, manager, formatOptions };
+}