@evantahler/mcpx 0.15.0

package/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(), ".mcpx");
+
+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 ~/.mcpx/
+  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/src/config/schemas.ts

@@ -0,0 +1,152 @@
+import type { Tool, Resource, Prompt } 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,
+  Resource,
+  Prompt,
+  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>;
+  transport?: "sse" | "streamable-http";
+  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)`);
+    }
+    if (hasUrl && c.transport !== undefined) {
+      if (c.transport !== "sse" && c.transport !== "streamable-http") {
+        throw new Error(
+          `Server "${name}" has invalid transport "${c.transport}" — must be "sse" or "streamable-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,62 @@
+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 logLevel = (opts.logLevel as string | undefined) ?? "warning";
+
+  const json = !!(opts.json as boolean | undefined);
+  // Commander's --no-interactive sets opts.interactive = false (default true)
+  const noInteractive = opts.interactive === false;
+
+  const manager = new ServerManager({
+    servers: config.servers,
+    configDir: config.configDir,
+    auth: config.auth,
+    concurrency,
+    verbose,
+    showSecrets,
+    timeout,
+    maxRetries,
+    logLevel,
+    json,
+    noInteractive,
+  });
+
+  const formatOptions: FormatOptions = {
+    json: opts.json as boolean | undefined,
+    withDescriptions: opts.withDescriptions as boolean | undefined,
+    verbose,
+    showSecrets,
+    logLevel,
+  };
+
+  logger.configure(formatOptions);
+
+  return { config, manager, formatOptions };
+}

package/src/lib/input.ts

@@ -0,0 +1,36 @@
+/**
+ * Shared helpers for parsing JSON arguments and reading from stdin.
+ */
+
+/** Parse a JSON string as a key-value object, optionally coercing all values to strings. */
+export function parseJsonArgs(
+  str: string,
+  opts?: { coerceToString?: boolean },
+): Record<string, unknown> {
+  try {
+    const parsed = JSON.parse(str);
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+      throw new Error("Arguments must be a JSON object");
+    }
+    if (opts?.coerceToString) {
+      return Object.fromEntries(Object.entries(parsed).map(([k, v]) => [k, String(v)]));
+    }
+    return parsed as Record<string, unknown>;
+  } catch (err) {
+    if (err instanceof SyntaxError) {
+      throw new Error(`Invalid JSON: ${err.message}`);
+    }
+    throw err;
+  }
+}
+
+/** Read all data from stdin until EOF. */
+export 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("");
+}