@evantahler/mcpx 0.15.0

package/.claude/worktrees/elastic-jennings/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/.claude/worktrees/elastic-jennings/src/config/loader.ts

@@ -0,0 +1,156 @@
+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(), ".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 ~/.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");
+}
+
+/** 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/.claude/worktrees/elastic-jennings/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/.claude/worktrees/elastic-jennings/src/context.ts

@@ -0,0 +1,53 @@
+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";
+import { logger } from "./output/logger.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) ||
+    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 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,
+    withDescriptions: opts.withDescriptions as boolean | undefined,
+    verbose,
+    showSecrets,
+  };
+
+  logger.configure(formatOptions);
+
+  return { config, manager, formatOptions };
+}

package/.claude/worktrees/elastic-jennings/src/output/formatter.ts

@@ -0,0 +1,316 @@
+import { bold, cyan, dim, green, red, yellow } from "ansis";
+import type { Tool } from "../config/schemas.ts";
+import type { ToolWithServer } from "../client/manager.ts";
+import type { ValidationError } from "../validation/schema.ts";
+import type { SearchResult } from "../search/index.ts";
+
+export interface FormatOptions {
+  json?: boolean;
+  withDescriptions?: boolean;
+  verbose?: boolean;
+  showSecrets?: boolean;
+}
+
+/** Check if stdout is a TTY (interactive terminal) */
+export function isInteractive(options: FormatOptions): boolean {
+  if (options.json) return false;
+  return process.stdout.isTTY ?? false;
+}
+
+/** Format a list of tools with server names */
+export function formatToolList(tools: ToolWithServer[], options: FormatOptions): string {
+  if (!isInteractive(options)) {
+    if (options.withDescriptions) {
+      return JSON.stringify(
+        tools.map((t) => ({
+          server: t.server,
+          tool: t.tool.name,
+          description: t.tool.description ?? "",
+        })),
+        null,
+        2,
+      );
+    }
+    return JSON.stringify(
+      tools.map((t) => ({ server: t.server, tool: t.tool.name })),
+      null,
+      2,
+    );
+  }
+
+  if (tools.length === 0) {
+    return dim("No tools found");
+  }
+
+  // Calculate column widths
+  const maxServer = Math.max(...tools.map((t) => t.server.length));
+  const maxTool = Math.max(...tools.map((t) => t.tool.name.length));
+
+  return tools
+    .map((t) => {
+      const server = cyan(t.server.padEnd(maxServer));
+      const tool = bold(t.tool.name.padEnd(maxTool));
+      if (options.withDescriptions && t.tool.description) {
+        return `${server}  ${tool}  ${dim(t.tool.description)}`;
+      }
+      return `${server}  ${tool}`;
+    })
+    .join("\n");
+}
+
+/** Format tools for a single server */
+export function formatServerTools(
+  serverName: string,
+  tools: Tool[],
+  options: FormatOptions,
+): string {
+  if (!isInteractive(options)) {
+    return JSON.stringify(
+      {
+        server: serverName,
+        tools: tools.map((t) => ({ name: t.name, description: t.description ?? "" })),
+      },
+      null,
+      2,
+    );
+  }
+
+  if (tools.length === 0) {
+    return dim(`No tools found for ${serverName}`);
+  }
+
+  const header = cyan.bold(serverName);
+  const maxName = Math.max(...tools.map((t) => t.name.length));
+
+  const lines = tools.map((t) => {
+    const name = `  ${bold(t.name.padEnd(maxName))}`;
+    if (t.description) {
+      return `${name}  ${dim(t.description)}`;
+    }
+    return name;
+  });
+
+  return [header, ...lines].join("\n");
+}
+
+/** Format a tool schema */
+export function formatToolSchema(serverName: string, tool: Tool, options: FormatOptions): string {
+  if (!isInteractive(options)) {
+    return JSON.stringify(
+      {
+        server: serverName,
+        tool: tool.name,
+        description: tool.description ?? "",
+        inputSchema: tool.inputSchema,
+      },
+      null,
+      2,
+    );
+  }
+
+  const lines: string[] = [];
+  lines.push(`${cyan(serverName)}/${bold(tool.name)}`);
+
+  if (tool.description) {
+    lines.push(dim(tool.description));
+  }
+
+  lines.push("");
+  lines.push(bold("Input Schema:"));
+  lines.push(formatSchema(tool.inputSchema, 2));
+
+  return lines.join("\n");
+}
+
+/** Format a JSON schema as a readable parameter list */
+function formatSchema(schema: Tool["inputSchema"], indent: number): string {
+  const pad = " ".repeat(indent);
+  const properties = schema.properties ?? {};
+  const required = new Set(schema.required ?? []);
+
+  if (Object.keys(properties).length === 0) {
+    return `${pad}${dim("(no parameters)")}`;
+  }
+
+  return Object.entries(properties)
+    .map(([name, prop]) => {
+      const p = prop as Record<string, unknown>;
+      const type = (p.type as string) ?? "any";
+      const req = required.has(name) ? red("*") : "";
+      const desc = p.description ? `  ${dim(String(p.description))}` : "";
+      return `${pad}${green(name)}${req} ${dim(`(${type})`)}${desc}`;
+    })
+    .join("\n");
+}
+
+/** Format detailed tool help with example payload */
+export function formatToolHelp(serverName: string, tool: Tool, options: FormatOptions): string {
+  if (!isInteractive(options)) {
+    return JSON.stringify(
+      {
+        server: serverName,
+        tool: tool.name,
+        description: tool.description ?? "",
+        inputSchema: tool.inputSchema,
+        example: generateExample(tool.inputSchema),
+      },
+      null,
+      2,
+    );
+  }
+
+  const lines: string[] = [];
+  lines.push(`${cyan(serverName)}/${bold(tool.name)}`);
+
+  if (tool.description) {
+    lines.push(dim(tool.description));
+  }
+
+  lines.push("");
+  lines.push(bold("Parameters:"));
+  lines.push(formatSchema(tool.inputSchema, 2));
+
+  const example = generateExample(tool.inputSchema);
+  lines.push("");
+  lines.push(bold("Example:"));
+  lines.push(dim(`  mcpcli call ${serverName} ${tool.name} '${JSON.stringify(example)}'`));
+
+  return lines.join("\n");
+}
+
+/** Generate an example payload from a JSON schema */
+function generateExample(schema: Tool["inputSchema"]): Record<string, unknown> {
+  const properties = schema.properties ?? {};
+  const required = new Set(schema.required ?? []);
+  const example: Record<string, unknown> = {};
+
+  for (const [name, prop] of Object.entries(properties)) {
+    const p = prop as Record<string, unknown>;
+    // Include required fields and first few optional fields
+    if (required.has(name) || Object.keys(example).length < 3) {
+      example[name] = exampleValue(name, p);
+    }
+  }
+
+  return example;
+}
+
+function exampleValue(name: string, prop: Record<string, unknown>): unknown {
+  // Use enum first choice if available
+  if (Array.isArray(prop.enum) && prop.enum.length > 0) {
+    return prop.enum[0];
+  }
+
+  // Use default if provided
+  if (prop.default !== undefined) {
+    return prop.default;
+  }
+
+  const type = prop.type as string | undefined;
+  switch (type) {
+    case "string":
+      return `<${name}>`;
+    case "number":
+    case "integer":
+      return 0;
+    case "boolean":
+      return true;
+    case "array":
+      return [];
+    case "object":
+      return {};
+    default:
+      return `<${name}>`;
+  }
+}
+
+/** Format a tool call result */
+export function formatCallResult(result: unknown, _options: FormatOptions): string {
+  return JSON.stringify(parseNestedJson(result), null, 2);
+}
+
+/** Recursively parse JSON strings inside MCP content blocks */
+function parseNestedJson(value: unknown): unknown {
+  if (typeof value === "string") {
+    try {
+      return parseNestedJson(JSON.parse(value));
+    } catch {
+      return value;
+    }
+  }
+  if (Array.isArray(value)) {
+    return value.map(parseNestedJson);
+  }
+  if (typeof value === "object" && value !== null) {
+    return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, parseNestedJson(v)]));
+  }
+  return value;
+}
+
+/** Format validation errors for tool input */
+export function formatValidationErrors(
+  serverName: string,
+  toolName: string,
+  errors: ValidationError[],
+  options: FormatOptions,
+): string {
+  if (!isInteractive(options)) {
+    return JSON.stringify({
+      error: "validation",
+      server: serverName,
+      tool: toolName,
+      details: errors,
+    });
+  }
+
+  const header = `${red("error:")} invalid arguments for ${cyan(serverName)}/${bold(toolName)}`;
+  const details = errors.map((e) => `  ${yellow(e.path)}: ${e.message}`).join("\n");
+  return `${header}\n${details}`;
+}
+
+/** Format search results */
+export function formatSearchResults(results: SearchResult[], options: FormatOptions): string {
+  if (!isInteractive(options)) {
+    return JSON.stringify(results, null, 2);
+  }
+
+  if (results.length === 0) {
+    return dim("No matching tools found");
+  }
+
+  const maxServer = Math.max(...results.map((r) => r.server.length));
+  const maxTool = Math.max(...results.map((r) => r.tool.length));
+
+  // First line of description only for the main row
+  const firstLine = (s: string) => s.split("\n")[0] ?? "";
+
+  return results
+    .map((r) => {
+      const server = cyan(r.server.padEnd(maxServer));
+      const tool = bold(r.tool.padEnd(maxTool));
+      const score = yellow(r.score.toFixed(2).padStart(5));
+      const summary = firstLine(r.description);
+      const line = `${server}  ${tool}  ${score}  ${dim(summary)}`;
+
+      // Show remaining description lines indented below
+      const descLines = r.description.split("\n").slice(1);
+      const extra = descLines.filter((l) => l.trim()).length > 0;
+      if (!extra) return line;
+
+      const indent = " ".repeat(maxServer + maxTool + 12);
+      const rest = descLines
+        .filter((l) => l.trim())
+        .map((l) => `${indent}${dim(l.trim())}`)
+        .join("\n");
+      return `${line}\n${rest}`;
+    })
+    .join("\n");
+}
+
+/** Format an error message */
+export function formatError(message: string, options: FormatOptions): string {
+  if (!isInteractive(options)) {
+    return JSON.stringify({ error: message });
+  }
+  return `${red("error:")} ${message}`;
+}