@evantahler/mcpx 0.15.0

package/src/output/logger.ts

@@ -0,0 +1,173 @@
+import { createSpinner } from "nanospinner";
+import { dim, yellow, red } from "ansis";
+import type { FormatOptions } from "./formatter.ts";
+
+/** MCP log levels ordered by severity (RFC 5424) */
+const LOG_LEVELS = [
+  "debug",
+  "info",
+  "notice",
+  "warning",
+  "error",
+  "critical",
+  "alert",
+  "emergency",
+] as const;
+
+type LogLevel = (typeof LOG_LEVELS)[number];
+
+function logLevelIndex(level: string): number {
+  const idx = LOG_LEVELS.indexOf(level as LogLevel);
+  return idx === -1 ? 0 : idx;
+}
+
+function colorForLevel(level: string): (s: string) => string {
+  switch (level) {
+    case "debug":
+      return dim;
+    case "warning":
+      return yellow;
+    case "error":
+    case "critical":
+    case "alert":
+    case "emergency":
+      return red;
+    default:
+      return (s: string) => s;
+  }
+}
+
+export interface Spinner {
+  update(text: string): void;
+  success(text?: string): void;
+  error(text?: string): void;
+  stop(): void;
+}
+
+class Logger {
+  private static instance: Logger;
+  private activeSpinner: ReturnType<typeof createSpinner> | null = null;
+  private formatOptions: FormatOptions = {};
+
+  private constructor() {}
+
+  static getInstance(): Logger {
+    if (!Logger.instance) {
+      Logger.instance = new Logger();
+    }
+    return Logger.instance;
+  }
+
+  /** Set format options (called once during context setup) */
+  configure(options: FormatOptions): void {
+    this.formatOptions = options;
+  }
+
+  /** Whether interactive output is suppressed (JSON mode or non-TTY stderr) */
+  private isSilent(): boolean {
+    return !!this.formatOptions.json || !(process.stderr.isTTY ?? false);
+  }
+
+  /** Write a line to stderr, pausing any active spinner around the write */
+  private writeStderr(msg: string): void {
+    if (this.activeSpinner) {
+      this.activeSpinner.clear();
+      process.stderr.write(msg + "\n");
+      this.activeSpinner.render();
+    } else {
+      process.stderr.write(msg + "\n");
+    }
+  }
+
+  /** Info-level message (dim text on stderr). Suppressed in JSON/non-TTY mode. */
+  info(msg: string): void {
+    if (this.isSilent()) return;
+    this.writeStderr(dim(msg));
+  }
+
+  /** Warning message (yellow text on stderr). Suppressed in JSON/non-TTY mode. */
+  warn(msg: string): void {
+    if (this.isSilent()) return;
+    this.writeStderr(yellow(msg));
+  }
+
+  /** Error message (red text on stderr). Always writes. */
+  error(msg: string): void {
+    this.writeStderr(red(msg));
+  }
+
+  /** Debug/verbose message (dim text on stderr). Only when verbose is enabled. */
+  debug(msg: string): void {
+    if (!this.formatOptions.verbose || this.isSilent()) return;
+    this.writeStderr(dim(msg));
+  }
+
+  /** Write a raw string to stderr. Spinner-aware but no formatting or newline added. */
+  writeRaw(msg: string): void {
+    if (this.activeSpinner) {
+      this.activeSpinner.clear();
+      process.stderr.write(msg);
+      this.activeSpinner.render();
+    } else {
+      process.stderr.write(msg);
+    }
+  }
+
+  /** Display a structured server log message. Suppressed if below configured log level. */
+  logServerMessage(
+    serverName: string,
+    params: { level: string; logger?: string; data: unknown },
+  ): void {
+    const minLevel = this.formatOptions.logLevel ?? "warning";
+    if (logLevelIndex(params.level) < logLevelIndex(minLevel)) return;
+
+    if (this.formatOptions.json) {
+      // JSON mode: structured object to stderr
+      const obj = { server: serverName, ...params };
+      process.stderr.write(JSON.stringify(obj) + "\n");
+      return;
+    }
+
+    if (!(process.stderr.isTTY ?? false)) return;
+
+    const prefix = params.logger ? `[${serverName}/${params.logger}]` : `[${serverName}]`;
+    const dataStr = typeof params.data === "string" ? params.data : JSON.stringify(params.data);
+    const line = `${prefix} ${params.level}: ${dataStr}`;
+    const color = colorForLevel(params.level);
+    this.writeStderr(color(line));
+  }
+
+  /** Start a spinner. Returns the Spinner interface. */
+  startSpinner(text: string, options?: FormatOptions): Spinner {
+    const opts = options ?? this.formatOptions;
+
+    // No spinner in JSON/piped/verbose mode — verbose writeRaw output conflicts with spinner rendering
+    if (opts.json || opts.verbose || !(process.stderr.isTTY ?? false)) {
+      return { update() {}, success() {}, error() {}, stop() {} };
+    }
+
+    const spinner = createSpinner(text, { stream: process.stderr }).start();
+    this.activeSpinner = spinner;
+
+    return {
+      update: (text: string) => {
+        spinner.update({ text });
+      },
+      success: (text?: string) => {
+        spinner.success({ text });
+        this.activeSpinner = null;
+      },
+      error: (text?: string) => {
+        spinner.error({ text });
+        this.activeSpinner = null;
+      },
+      stop: () => {
+        spinner.stop();
+        this.activeSpinner = null;
+      },
+    };
+  }
+}
+
+/** The singleton logger instance */
+export const logger = Logger.getInstance();

package/src/search/index.ts

@@ -0,0 +1,69 @@
+import type { SearchIndex } from "../config/schemas.ts";
+import { keywordSearch } from "./keyword.ts";
+import { semanticSearch } from "./semantic.ts";
+
+export interface SearchResult {
+  server: string;
+  tool: string;
+  description: string;
+  score: number;
+  matchType: "keyword" | "semantic" | "both";
+}
+
+export interface SearchOptions {
+  keywordOnly?: boolean;
+  semanticOnly?: boolean;
+  topK?: number;
+}
+
+/** Search tools using keyword and/or semantic matching */
+export async function search(
+  query: string,
+  index: SearchIndex,
+  options: SearchOptions = {},
+): Promise<SearchResult[]> {
+  const topK = options.topK ?? 10;
+  const results = new Map<string, SearchResult>();
+
+  const runKeyword = !options.semanticOnly;
+  const runSemantic = !options.keywordOnly;
+
+  // Keyword search
+  if (runKeyword) {
+    const matches = keywordSearch(query, index.tools);
+    for (const m of matches) {
+      const key = `${m.server}/${m.tool}`;
+      results.set(key, {
+        server: m.server,
+        tool: m.tool,
+        description: m.description,
+        score: m.score,
+        matchType: "keyword",
+      });
+    }
+  }
+
+  // Semantic search
+  if (runSemantic && index.tools.some((t) => t.embedding.length > 0)) {
+    const matches = await semanticSearch(query, index.tools, topK);
+    for (const m of matches) {
+      const key = `${m.server}/${m.tool}`;
+      const existing = results.get(key);
+      if (existing) {
+        // Combine scores: keyword 0.4 + semantic 0.6
+        existing.score = existing.score * 0.4 + m.score * 0.6;
+        existing.matchType = "both";
+      } else {
+        results.set(key, {
+          server: m.server,
+          tool: m.tool,
+          description: m.description,
+          score: m.score,
+          matchType: "semantic",
+        });
+      }
+    }
+  }
+
+  return [...results.values()].sort((a, b) => b.score - a.score).slice(0, topK);
+}

package/src/search/indexer.ts

@@ -0,0 +1,92 @@
+import type { ServerManager, ToolWithServer } from "../client/manager.ts";
+import type { SearchIndex, IndexedTool } from "../config/schemas.ts";
+import { generateEmbedding } from "./semantic.ts";
+import { logger } from "../output/logger.ts";
+
+/** Extract keywords from a tool name by splitting on separators and camelCase */
+export function extractKeywords(name: string): string[] {
+  // Split on underscores, hyphens, dots
+  const parts = name.split(/[_\-.]+/);
+
+  // Also split camelCase
+  const words: string[] = [];
+  for (const part of parts) {
+    words.push(...part.replace(/([a-z])([A-Z])/g, "$1 $2").split(/\s+/));
+  }
+
+  return words.map((w) => w.toLowerCase()).filter((w) => w.length > 1);
+}
+
+/** Generate scenario phrases from tool name and description */
+export function generateScenarios(name: string, description: string): string[] {
+  const scenarios: string[] = [];
+
+  // Use description as-is if short enough
+  if (description && description.length < 200) {
+    scenarios.push(description);
+  }
+
+  // Extract action + noun from tool name (e.g., "SendMessage" → "send a message")
+  const keywords = extractKeywords(name);
+  if (keywords.length >= 2) {
+    scenarios.push(keywords.join(" "));
+  }
+
+  return scenarios;
+}
+
+/** Build an IndexedTool from a tool with server info */
+async function indexTool(t: ToolWithServer): Promise<IndexedTool> {
+  const description = t.tool.description ?? "";
+  const keywords = extractKeywords(t.tool.name);
+  const scenarios = generateScenarios(t.tool.name, description);
+
+  // Build text for embedding: combine name, description, and scenarios
+  const embeddingText = [t.tool.name, description, ...scenarios].filter(Boolean).join(" ");
+  const embedding = await generateEmbedding(embeddingText);
+
+  return {
+    server: t.server,
+    tool: t.tool.name,
+    description,
+    input_schema: t.tool.inputSchema,
+    scenarios,
+    keywords,
+    embedding,
+  };
+}
+
+export interface IndexProgress {
+  total: number;
+  current: number;
+  tool: string;
+}
+
+/** Build a search index from all configured servers */
+export async function buildSearchIndex(
+  manager: ServerManager,
+  onProgress?: (progress: IndexProgress) => void,
+): Promise<SearchIndex> {
+  const { tools, errors } = await manager.getAllTools();
+
+  if (errors.length > 0) {
+    for (const err of errors) {
+      logger.warn(`${err.server}: ${err.message}`);
+    }
+  }
+
+  const indexed: IndexedTool[] = [];
+
+  for (let i = 0; i < tools.length; i++) {
+    const t = tools[i]!;
+    onProgress?.({ total: tools.length, current: i + 1, tool: `${t.server}/${t.tool.name}` });
+    indexed.push(await indexTool(t));
+  }
+
+  return {
+    version: 1,
+    indexed_at: new Date().toISOString(),
+    embedding_model: "Xenova/all-MiniLM-L6-v2",
+    tools: indexed,
+  };
+}

package/src/search/keyword.ts

@@ -0,0 +1,86 @@
+import picomatch from "picomatch";
+import type { IndexedTool } from "../config/schemas.ts";
+
+export interface KeywordMatch {
+  server: string;
+  tool: string;
+  description: string;
+  score: number;
+  matchedField: string;
+}
+
+interface FieldWeight {
+  field: string;
+  weight: number;
+  values: (t: IndexedTool) => string[];
+}
+
+const FIELDS: FieldWeight[] = [
+  { field: "name", weight: 1.0, values: (t) => [t.tool] },
+  { field: "keyword", weight: 0.8, values: (t) => t.keywords },
+  { field: "scenario", weight: 0.6, values: (t) => t.scenarios },
+  { field: "description", weight: 0.4, values: (t) => [t.description] },
+];
+
+/** Check if query looks like a glob pattern */
+function isGlob(query: string): boolean {
+  return /[*?[\]{}]/.test(query);
+}
+
+/** Search indexed tools by keyword/glob matching */
+export function keywordSearch(query: string, tools: IndexedTool[]): KeywordMatch[] {
+  const queryLower = query.toLowerCase();
+  const tokens = queryLower.split(/\s+/).filter(Boolean);
+
+  // If any token is a glob, use picomatch for name matching
+  const globTokens = tokens.filter(isGlob);
+  const textTokens = tokens.filter((t) => !isGlob(t));
+  const globMatcher = globTokens.length > 0 ? picomatch(globTokens, { nocase: true }) : null;
+
+  const results: KeywordMatch[] = [];
+
+  for (const tool of tools) {
+    let bestScore = 0;
+    let bestField = "";
+
+    // Glob matching against tool name
+    if (globMatcher && globMatcher(tool.tool)) {
+      bestScore = 1.0;
+      bestField = "name";
+    }
+
+    // Text token matching against all fields
+    if (textTokens.length > 0) {
+      for (const { field, weight, values } of FIELDS) {
+        const fieldValues = values(tool).map((v) => v.toLowerCase());
+        let matchCount = 0;
+
+        for (const token of textTokens) {
+          if (fieldValues.some((v) => v.includes(token))) {
+            matchCount++;
+          }
+        }
+
+        if (matchCount > 0) {
+          const score = (matchCount / textTokens.length) * weight;
+          if (score > bestScore) {
+            bestScore = score;
+            bestField = field;
+          }
+        }
+      }
+    }
+
+    if (bestScore > 0) {
+      results.push({
+        server: tool.server,
+        tool: tool.tool,
+        description: tool.description,
+        score: bestScore,
+        matchedField: bestField,
+      });
+    }
+  }
+
+  return results.sort((a, b) => b.score - a.score);
+}

package/src/search/semantic.ts

@@ -0,0 +1,75 @@
+import type { IndexedTool } from "../config/schemas.ts";
+
+export interface SemanticMatch {
+  server: string;
+  tool: string;
+  description: string;
+  score: number;
+}
+
+// Lazy-loaded pipeline singleton
+let pipelineInstance: ((text: string) => Promise<Float32Array>) | null = null;
+
+/** Get or create the embedding pipeline */
+async function getEmbedder(): Promise<(text: string) => Promise<Float32Array>> {
+  if (pipelineInstance) return pipelineInstance;
+
+  const { pipeline } = await import("@huggingface/transformers");
+  const extractor = await pipeline("feature-extraction", "Xenova/all-MiniLM-L6-v2", {
+    dtype: "fp32",
+  });
+
+  pipelineInstance = async (text: string): Promise<Float32Array> => {
+    const output = await extractor(text, { pooling: "mean", normalize: true });
+    // output.data is a Float32Array of the pooled embedding
+    return output.data as Float32Array;
+  };
+
+  return pipelineInstance;
+}
+
+/** Generate an embedding vector for text */
+export async function generateEmbedding(text: string): Promise<number[]> {
+  const embed = await getEmbedder();
+  const vec = await embed(text);
+  return Array.from(vec);
+}
+
+/** Cosine similarity between two vectors */
+export function cosineSimilarity(a: number[], b: number[]): number {
+  if (a.length !== b.length || a.length === 0) return 0;
+
+  let dot = 0;
+  let magA = 0;
+  let magB = 0;
+  for (let i = 0; i < a.length; i++) {
+    dot += a[i]! * b[i]!;
+    magA += a[i]! * a[i]!;
+    magB += b[i]! * b[i]!;
+  }
+
+  const denom = Math.sqrt(magA) * Math.sqrt(magB);
+  return denom === 0 ? 0 : dot / denom;
+}
+
+/** Search indexed tools by semantic similarity */
+export async function semanticSearch(
+  query: string,
+  tools: IndexedTool[],
+  topK = 10,
+): Promise<SemanticMatch[]> {
+  // Only search tools that have embeddings
+  const withEmbeddings = tools.filter((t) => t.embedding.length > 0);
+  if (withEmbeddings.length === 0) return [];
+
+  const queryEmbedding = await generateEmbedding(query);
+
+  const scored = withEmbeddings.map((tool) => ({
+    server: tool.server,
+    tool: tool.tool,
+    description: tool.description,
+    score: cosineSimilarity(queryEmbedding, tool.embedding),
+  }));
+
+  return scored.sort((a, b) => b.score - a.score).slice(0, topK);
+}

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));
+}

package/src/validation/schema.ts

@@ -0,0 +1,103 @@
+import Ajv, { type ErrorObject } from "ajv";
+import type { Tool } from "../config/schemas.ts";
+
+const ajv = new Ajv({ allErrors: true, strict: false });
+
+// Cache compiled validators by a key of "server/tool"
+const validatorCache = new Map<string, ReturnType<typeof ajv.compile>>();
+
+export interface ValidationError {
+  path: string;
+  message: string;
+}
+
+export interface ValidationResult {
+  valid: boolean;
+  errors: ValidationError[];
+}
+
+/** Validate tool arguments against the tool's inputSchema */
+export function validateToolInput(
+  serverName: string,
+  tool: Tool,
+  input: Record<string, unknown>,
+): ValidationResult {
+  const schema = tool.inputSchema;
+  if (!schema || Object.keys(schema).length === 0) {
+    return { valid: true, errors: [] };
+  }
+
+  const cacheKey = `${serverName}/${tool.name}`;
+  let validate = validatorCache.get(cacheKey);
+
+  if (!validate) {
+    try {
+      validate = ajv.compile(schema);
+      validatorCache.set(cacheKey, validate);
+    } catch {
+      // If schema can't be compiled, skip validation
+      return { valid: true, errors: [] };
+    }
+  }
+
+  const valid = validate(input);
+  if (valid) {
+    return { valid: true, errors: [] };
+  }
+
+  const errors = (validate.errors ?? []).map(formatAjvError);
+  return { valid: false, errors };
+}
+
+/** Validate user-collected form data against an elicitation requestedSchema */
+export function validateElicitationResponse(
+  schema: Record<string, unknown>,
+  input: Record<string, unknown>,
+): ValidationResult {
+  const cacheKey = `__elicitation__${JSON.stringify(schema)}`;
+  let validate = validatorCache.get(cacheKey);
+
+  if (!validate) {
+    try {
+      validate = ajv.compile(schema);
+      validatorCache.set(cacheKey, validate);
+    } catch {
+      return { valid: true, errors: [] };
+    }
+  }
+
+  const valid = validate(input);
+  if (valid) {
+    return { valid: true, errors: [] };
+  }
+
+  const errors = (validate.errors ?? []).map(formatAjvError);
+  return { valid: false, errors };
+}
+
+function formatAjvError(err: ErrorObject): ValidationError {
+  const path = err.instancePath
+    ? err.instancePath.replace(/^\//, "").replace(/\//g, ".")
+    : "(root)";
+
+  switch (err.keyword) {
+    case "required": {
+      const field = (err.params as { missingProperty: string }).missingProperty;
+      return { path: field, message: `missing required field "${field}"` };
+    }
+    case "type": {
+      const expected = (err.params as { type: string }).type;
+      return { path, message: `must be ${expected}` };
+    }
+    case "enum": {
+      const allowed = (err.params as { allowedValues: unknown[] }).allowedValues;
+      return { path, message: `must be one of: ${allowed.join(", ")}` };
+    }
+    case "additionalProperties": {
+      const extra = (err.params as { additionalProperty: string }).additionalProperty;
+      return { path: extra, message: `unknown property "${extra}"` };
+    }
+    default:
+      return { path, message: err.message ?? "validation failed" };
+  }
+}