mcp-server-diff 2.1.0 → 2.1.6

package/src/cli.ts

@@ -1,421 +0,0 @@
-/**
- * MCP Server Diff - CLI Entry Point
- *
- * Standalone CLI for diffing MCP server public interfaces.
- * Can compare any two servers or multiple servers against a base.
- */
-
-import { parseArgs } from "node:util";
-import * as fs from "fs";
-import { probeServer } from "./probe.js";
-import { compareProbeResults, extractCounts, type DiffResult } from "./diff.js";
-import { ConsoleLogger, QuietLogger, setLogger, log } from "./logger.js";
-import type { ProbeResult, PrimitiveCounts } from "./types.js";
-
-interface ServerConfig {
-  name: string;
-  transport: "stdio" | "streamable-http";
-  start_command?: string;
-  server_url?: string;
-  headers?: Record<string, string>;
-  env_vars?: Record<string, string>;
-}
-
-interface DiffConfig {
-  base: ServerConfig;
-  targets: ServerConfig[];
-}
-
-interface ComparisonResult {
-  base: string;
-  target: string;
-  hasDifferences: boolean;
-  diffs: DiffResult[];
-  baseCounts: PrimitiveCounts;
-  targetCounts: PrimitiveCounts;
-  error?: string;
-}
-
-/**
- * Parse command line arguments
- */
-function parseCliArgs() {
-  const { values, positionals } = parseArgs({
-    options: {
-      base: { type: "string", short: "b" },
-      target: { type: "string", short: "t" },
-      config: { type: "string", short: "c" },
-      output: { type: "string", short: "o", default: "summary" },
-      verbose: { type: "boolean", short: "v", default: false },
-      quiet: { type: "boolean", short: "q", default: false },
-      help: { type: "boolean", short: "h", default: false },
-      version: { type: "boolean", default: false },
-    },
-    allowPositionals: true,
-    strict: true,
-  });
-
-  return { values, positionals };
-}
-
-/**
- * Print help message
- */
-function printHelp(): void {
-  console.log(`
-mcp-server-diff - Diff MCP server public interfaces
-
-USAGE:
-  mcp-server-diff [OPTIONS]
-  mcp-server-diff --base "python -m server" --target "node dist/stdio.js"
-  mcp-server-diff --config servers.json
-
-OPTIONS:
-  -b, --base <command>     Base server command (stdio) or URL (http)
-  -t, --target <command>   Target server command (stdio) or URL (http)
-  -c, --config <file>      Config file with base and targets
-  -o, --output <format>    Output format: json, markdown, summary (default: summary)
-  -v, --verbose            Verbose output
-  -q, --quiet              Quiet mode (only output diffs)
-  -h, --help               Show this help
-      --version            Show version
-
-CONFIG FILE FORMAT:
-  {
-    "base": {
-      "name": "python-server",
-      "transport": "stdio",
-      "start_command": "python -m mcp_server"
-    },
-    "targets": [
-      {
-        "name": "typescript-server",
-        "transport": "stdio",
-        "start_command": "node dist/stdio.js"
-      }
-    ]
-  }
-
-OUTPUT FORMATS:
-  summary   - One line per comparison (default)
-  json      - Raw JSON with full diff details
-  markdown  - Formatted markdown report
-
-EXAMPLES:
-  # Compare two stdio servers
-  mcp-server-diff -b "python -m server" -t "node dist/index.js"
-
-  # Compare against HTTP server
-  mcp-server-diff -b "python -m server" -t "http://localhost:3000/mcp"
-
-  # Use config file for multiple comparisons
-  mcp-server-diff -c servers.json -o markdown
-
-  # Output raw JSON for CI
-  mcp-server-diff -c servers.json -o json -q
-`);
-}
-
-/**
- * Load and parse config file
- */
-function loadConfig(configPath: string): DiffConfig {
-  const content = fs.readFileSync(configPath, "utf-8");
-  const config = JSON.parse(content) as DiffConfig;
-
-  if (!config.base) {
-    throw new Error("Config must have a 'base' server");
-  }
-  if (!config.targets || config.targets.length === 0) {
-    throw new Error("Config must have at least one 'target' server");
-  }
-
-  return config;
-}
-
-/**
- * Create a server config from a command string
- */
-function commandToConfig(command: string, name: string): ServerConfig {
-  if (command.startsWith("http://") || command.startsWith("https://")) {
-    return {
-      name,
-      transport: "streamable-http",
-      server_url: command,
-    };
-  }
-
-  return {
-    name,
-    transport: "stdio",
-    start_command: command,
-  };
-}
-
-/**
- * Probe a server and return results
- */
-async function probeServerConfig(config: ServerConfig): Promise<ProbeResult> {
-  if (config.transport === "stdio") {
-    if (!config.start_command) {
-      throw new Error(`No start_command for stdio server: ${config.name}`);
-    }
-
-    const parts = config.start_command.split(/\s+/);
-    const command = parts[0];
-    const args = parts.slice(1);
-
-    return await probeServer({
-      transport: "stdio",
-      command,
-      args,
-      envVars: config.env_vars,
-    });
-  } else {
-    if (!config.server_url) {
-      throw new Error(`No server_url for HTTP server: ${config.name}`);
-    }
-
-    return await probeServer({
-      transport: "streamable-http",
-      url: config.server_url,
-      headers: config.headers,
-      envVars: config.env_vars,
-    });
-  }
-}
-
-/**
- * Compare base against all targets
- */
-async function runComparisons(config: DiffConfig): Promise<ComparisonResult[]> {
-  const results: ComparisonResult[] = [];
-
-  log.info(`\n📍 Probing base: ${config.base.name}`);
-  let baseResult: ProbeResult;
-  try {
-    baseResult = await probeServerConfig(config.base);
-    if (baseResult.error) {
-      throw new Error(baseResult.error);
-    }
-  } catch (error) {
-    log.error(`Failed to probe base server: ${error}`);
-    return config.targets.map((target) => ({
-      base: config.base.name,
-      target: target.name,
-      hasDifferences: true,
-      diffs: [{ endpoint: "error", diff: `Base server probe failed: ${error}` }],
-      baseCounts: { tools: 0, prompts: 0, resources: 0, resourceTemplates: 0 },
-      targetCounts: { tools: 0, prompts: 0, resources: 0, resourceTemplates: 0 },
-      error: String(error),
-    }));
-  }
-
-  const baseCounts = extractCounts(baseResult);
-
-  for (const target of config.targets) {
-    log.info(`\n🎯 Probing target: ${target.name}`);
-
-    const result: ComparisonResult = {
-      base: config.base.name,
-      target: target.name,
-      hasDifferences: false,
-      diffs: [],
-      baseCounts,
-      targetCounts: { tools: 0, prompts: 0, resources: 0, resourceTemplates: 0 },
-    };
-
-    try {
-      const targetResult = await probeServerConfig(target);
-
-      if (targetResult.error) {
-        result.hasDifferences = true;
-        result.diffs = [{ endpoint: "error", diff: `Target probe failed: ${targetResult.error}` }];
-        result.error = targetResult.error;
-      } else {
-        result.targetCounts = extractCounts(targetResult);
-        result.diffs = compareProbeResults(baseResult, targetResult);
-        result.hasDifferences = result.diffs.length > 0;
-      }
-    } catch (error) {
-      result.hasDifferences = true;
-      result.diffs = [{ endpoint: "error", diff: `Target probe failed: ${error}` }];
-      result.error = String(error);
-    }
-
-    results.push(result);
-  }
-
-  return results;
-}
-
-/**
- * Output results in summary format
- */
-function outputSummary(results: ComparisonResult[]): void {
-  console.log("\n📊 Comparison Results:\n");
-
-  let hasAnyDiff = false;
-  for (const result of results) {
-    const status = result.hasDifferences ? "❌" : "✅";
-    const diffCount = result.diffs.length;
-    const counts = `(${result.targetCounts.tools}T/${result.targetCounts.prompts}P/${result.targetCounts.resources}R)`;
-
-    if (result.error) {
-      console.log(`${status} ${result.target} ${counts} - ERROR: ${result.error}`);
-    } else if (result.hasDifferences) {
-      console.log(`${status} ${result.target} ${counts} - ${diffCount} difference(s)`);
-      hasAnyDiff = true;
-    } else {
-      console.log(`${status} ${result.target} ${counts} - matches base`);
-    }
-  }
-
-  console.log("");
-  if (hasAnyDiff) {
-    console.log("Run with -o markdown or -o json for detailed diffs.");
-  }
-}
-
-/**
- * Output results in JSON format
- */
-function outputJson(results: ComparisonResult[]): void {
-  const output = {
-    timestamp: new Date().toISOString(),
-    results: results.map((r) => ({
-      base: r.base,
-      target: r.target,
-      hasDifferences: r.hasDifferences,
-      baseCounts: r.baseCounts,
-      targetCounts: r.targetCounts,
-      diffs: r.diffs,
-      error: r.error,
-    })),
-    summary: {
-      total: results.length,
-      matching: results.filter((r) => !r.hasDifferences).length,
-      different: results.filter((r) => r.hasDifferences).length,
-    },
-  };
-
-  console.log(JSON.stringify(output, null, 2));
-}
-
-/**
- * Output results in markdown format
- */
-function outputMarkdown(results: ComparisonResult[]): void {
-  const lines: string[] = [];
-
-  lines.push("# MCP Server Diff Report");
-  lines.push("");
-  lines.push(`**Generated:** ${new Date().toISOString()}`);
-  lines.push("");
-
-  lines.push("## Summary");
-  lines.push("");
-  lines.push("| Server | Tools | Prompts | Resources | Status |");
-  lines.push("|--------|-------|---------|-----------|--------|");
-
-  for (const result of results) {
-    const status = result.hasDifferences
-      ? result.error
-        ? "❌ Error"
-        : `⚠️ ${result.diffs.length} diff(s)`
-      : "✅ Match";
-    const c = result.targetCounts;
-    lines.push(`| ${result.target} | ${c.tools} | ${c.prompts} | ${c.resources} | ${status} |`);
-  }
-
-  lines.push("");
-
-  const diffsPresent = results.filter((r) => r.hasDifferences && r.diffs.length > 0);
-  if (diffsPresent.length > 0) {
-    lines.push("## Differences");
-    lines.push("");
-
-    for (const result of diffsPresent) {
-      lines.push(`### ${result.target}`);
-      lines.push("");
-
-      for (const { endpoint, diff } of result.diffs) {
-        lines.push(`**${endpoint}**`);
-        lines.push("");
-        lines.push("```diff");
-        lines.push(diff);
-        lines.push("```");
-        lines.push("");
-      }
-    }
-  } else {
-    lines.push("## ✅ All Servers Match");
-    lines.push("");
-    lines.push("No differences detected between base and target servers.");
-  }
-
-  console.log(lines.join("\n"));
-}
-
-/**
- * Main CLI entry point
- */
-async function main(): Promise<void> {
-  const { values } = parseCliArgs();
-
-  if (values.help) {
-    printHelp();
-    process.exit(0);
-  }
-
-  if (values.version) {
-    console.log("mcp-server-diff v2.1.0");
-    process.exit(0);
-  }
-
-  // Set up logger - CLI uses console logger by default
-  if (values.quiet) {
-    setLogger(new QuietLogger());
-  } else {
-    setLogger(new ConsoleLogger(values.verbose || false));
-  }
-
-  let config: DiffConfig;
-
-  if (values.config) {
-    config = loadConfig(values.config);
-  } else if (values.base && values.target) {
-    config = {
-      base: commandToConfig(values.base, "base"),
-      targets: [commandToConfig(values.target, "target")],
-    };
-  } else {
-    console.error("Error: Must provide --config or both --base and --target");
-    console.error("Run with --help for usage.");
-    process.exit(1);
-  }
-
-  const results = await runComparisons(config);
-
-  const outputFormat = values.output || "summary";
-  switch (outputFormat) {
-    case "json":
-      outputJson(results);
-      break;
-    case "markdown":
-      outputMarkdown(results);
-      break;
-    case "summary":
-    default:
-      outputSummary(results);
-      break;
-  }
-
-  const hasDiffs = results.some((r) => r.hasDifferences);
-  process.exit(hasDiffs ? 1 : 0);
-}
-
-main().catch((error) => {
-  console.error("Fatal error:", error);
-  process.exit(1);
-});

package/src/diff.ts

@@ -1,252 +0,0 @@
-/**
- * Core diffing logic for MCP servers
- *
- * Pure functions for comparing probe results - no I/O side effects.
- */
-
-import type { ProbeResult, PrimitiveCounts } from "./types.js";
-import { probeResultToFiles } from "./probe.js";
-
-export interface DiffResult {
-  endpoint: string;
-  diff: string;
-}
-
-export interface ComparisonResult {
-  baseName: string;
-  targetName: string;
-  hasDifferences: boolean;
-  diffs: DiffResult[];
-  baseCounts: PrimitiveCounts;
-  targetCounts: PrimitiveCounts;
-  baseError?: string;
-  targetError?: string;
-}
-
-/**
- * Extract primitive counts from a probe result
- */
-export function extractCounts(result: ProbeResult): PrimitiveCounts {
-  return {
-    tools: result.tools?.tools?.length || 0,
-    prompts: result.prompts?.prompts?.length || 0,
-    resources: result.resources?.resources?.length || 0,
-    resourceTemplates: result.resourceTemplates?.resourceTemplates?.length || 0,
-  };
-}
-
-/**
- * Compare two probe results and return structured diff results
- */
-export function compareProbeResults(
-  baseResult: ProbeResult,
-  targetResult: ProbeResult
-): DiffResult[] {
-  const baseFiles = probeResultToFiles(baseResult);
-  const targetFiles = probeResultToFiles(targetResult);
-  const diffs: DiffResult[] = [];
-
-  const allEndpoints = new Set([...baseFiles.keys(), ...targetFiles.keys()]);
-
-  for (const endpoint of allEndpoints) {
-    const baseContent = baseFiles.get(endpoint);
-    const targetContent = targetFiles.get(endpoint);
-
-    if (!targetContent && baseContent) {
-      diffs.push({
-        endpoint,
-        diff: `Endpoint removed in target (was present in base)`,
-      });
-    } else if (targetContent && !baseContent) {
-      diffs.push({
-        endpoint,
-        diff: `Endpoint added in target (not present in base)`,
-      });
-    } else if (baseContent !== targetContent) {
-      const diff = generateJsonDiff(endpoint, baseContent || "", targetContent || "");
-      if (diff) {
-        diffs.push({ endpoint, diff });
-      }
-    }
-  }
-
-  return diffs;
-}
-
-/**
- * Generate semantic JSON diff
- */
-export function generateJsonDiff(name: string, base: string, target: string): string | null {
-  try {
-    const baseObj = JSON.parse(base);
-    const targetObj = JSON.parse(target);
-
-    const differences = findJsonDifferences(baseObj, targetObj, "");
-
-    if (differences.length === 0) {
-      return null;
-    }
-
-    const diffLines = [`--- base/${name}.json`, `+++ target/${name}.json`, ""];
-    diffLines.push(...differences);
-
-    return diffLines.join("\n");
-  } catch {
-    // Fallback for non-JSON
-    if (base === target) return null;
-    return `--- base/${name}\n+++ target/${name}\n- ${base}\n+ ${target}`;
-  }
-}
-
-/**
- * Recursively find differences between two JSON objects
- */
-export function findJsonDifferences(base: unknown, target: unknown, path: string): string[] {
-  const diffs: string[] = [];
-
-  if (base === null || base === undefined) {
-    if (target !== null && target !== undefined) {
-      diffs.push(`+ ${path || "root"}: ${formatValue(target)}`);
-    }
-    return diffs;
-  }
-
-  if (target === null || target === undefined) {
-    diffs.push(`- ${path || "root"}: ${formatValue(base)}`);
-    return diffs;
-  }
-
-  if (typeof base !== typeof target) {
-    diffs.push(`- ${path || "root"}: ${formatValue(base)}`);
-    diffs.push(`+ ${path || "root"}: ${formatValue(target)}`);
-    return diffs;
-  }
-
-  if (Array.isArray(base) && Array.isArray(target)) {
-    return compareArrays(base, target, path);
-  }
-
-  if (typeof base === "object" && typeof target === "object") {
-    const baseObj = base as Record<string, unknown>;
-    const targetObj = target as Record<string, unknown>;
-    const allKeys = new Set([...Object.keys(baseObj), ...Object.keys(targetObj)]);
-
-    for (const key of allKeys) {
-      const newPath = path ? `${path}.${key}` : key;
-
-      if (!(key in baseObj)) {
-        diffs.push(`+ ${newPath}: ${formatValue(targetObj[key])}`);
-      } else if (!(key in targetObj)) {
-        diffs.push(`- ${newPath}: ${formatValue(baseObj[key])}`);
-      } else {
-        diffs.push(...findJsonDifferences(baseObj[key], targetObj[key], newPath));
-      }
-    }
-    return diffs;
-  }
-
-  if (base !== target) {
-    diffs.push(`- ${path}: ${formatValue(base)}`);
-    diffs.push(`+ ${path}: ${formatValue(target)}`);
-  }
-
-  return diffs;
-}
-
-/**
- * Compare arrays by finding items by their identity
- */
-function compareArrays(base: unknown[], target: unknown[], path: string): string[] {
-  const diffs: string[] = [];
-
-  const baseItems = new Map<string, { item: unknown; index: number }>();
-  const targetItems = new Map<string, { item: unknown; index: number }>();
-
-  base.forEach((item, index) => {
-    const key = getItemKey(item, index);
-    baseItems.set(key, { item, index });
-  });
-
-  target.forEach((item, index) => {
-    const key = getItemKey(item, index);
-    targetItems.set(key, { item, index });
-  });
-
-  // Find removed items
-  for (const [key, { item }] of baseItems) {
-    if (!targetItems.has(key)) {
-      diffs.push(`- ${path}[${key}]: ${formatValue(item)}`);
-    }
-  }
-
-  // Find added items
-  for (const [key, { item }] of targetItems) {
-    if (!baseItems.has(key)) {
-      diffs.push(`+ ${path}[${key}]: ${formatValue(item)}`);
-    }
-  }
-
-  // Find modified items
-  for (const [key, { item: baseItem }] of baseItems) {
-    const targetEntry = targetItems.get(key);
-    if (targetEntry) {
-      diffs.push(...findJsonDifferences(baseItem, targetEntry.item, `${path}[${key}]`));
-    }
-  }
-
-  return diffs;
-}
-
-/**
- * Get a unique key for an array item
- */
-function getItemKey(item: unknown, index: number): string {
-  if (item === null || item === undefined || typeof item !== "object") {
-    return `#${index}`;
-  }
-
-  const obj = item as Record<string, unknown>;
-
-  if (typeof obj.name === "string") return obj.name;
-  if (typeof obj.uri === "string") return obj.uri;
-  if (typeof obj.uriTemplate === "string") return obj.uriTemplate;
-  if (typeof obj.method === "string") return obj.method;
-
-  return `#${index}`;
-}
-
-/**
- * Format a value for display in diff output
- */
-export function formatValue(value: unknown): string {
-  if (value === null) return "null";
-  if (value === undefined) return "undefined";
-
-  if (typeof value === "string") {
-    if (value.length > 100) {
-      return JSON.stringify(value.slice(0, 100) + "...");
-    }
-    return JSON.stringify(value);
-  }
-
-  if (typeof value === "object") {
-    const json = JSON.stringify(value);
-    if (json.length > 200) {
-      return json.slice(0, 200) + "...";
-    }
-    return json;
-  }
-
-  return String(value);
-}
-
-/**
- * Convert DiffResult array to Map for backward compatibility
- */
-export function diffsToMap(diffs: DiffResult[]): Map<string, string> {
-  const map = new Map<string, string>();
-  for (const { endpoint, diff } of diffs) {
-    map.set(endpoint, diff);
-  }
-  return map;
-}