@evantahler/mcpcli 0.1.1

package/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}`;
+}

package/src/output/spinner.ts

@@ -0,0 +1,39 @@
+import { createSpinner } from "nanospinner";
+import type { FormatOptions } from "./formatter.ts";
+
+export interface Spinner {
+  update(text: string): void;
+  success(text?: string): void;
+  error(text?: string): void;
+  stop(): void;
+}
+
+/** Create a spinner that only renders in interactive mode */
+export function startSpinner(text: string, options: FormatOptions): Spinner {
+  // No spinner in JSON/piped mode
+  if (options.json || !(process.stderr.isTTY ?? false)) {
+    return {
+      update() {},
+      success() {},
+      error() {},
+      stop() {},
+    };
+  }
+
+  const spinner = createSpinner(text, { stream: process.stderr }).start();
+
+  return {
+    update(text: string) {
+      spinner.update({ text });
+    },
+    success(text?: string) {
+      spinner.success({ text });
+    },
+    error(text?: string) {
+      spinner.error({ text });
+    },
+    stop() {
+      spinner.stop();
+    },
+  };
+}

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,91 @@
+import type { ServerManager, ToolWithServer } from "../client/manager.ts";
+import type { SearchIndex, IndexedTool } from "../config/schemas.ts";
+import { generateEmbedding } from "./semantic.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) {
+      process.stderr.write(`warning: ${err.server}: ${err.message}\n`);
+    }
+  }
+
+  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);
+}