mcp-server-diff 2.1.0

package/dist/cli/types.d.ts

@@ -0,0 +1,134 @@
+/**
+ * Type definitions for MCP Conformance Action
+ */
+export interface TestConfiguration {
+    name: string;
+    transport: "stdio" | "streamable-http";
+    start_command?: string;
+    args?: string;
+    server_url?: string;
+    headers?: Record<string, string>;
+    env_vars?: string;
+    custom_messages?: CustomMessage[];
+    /** Command to run before starting the MCP server for this config */
+    pre_test_command?: string;
+    /** Milliseconds to wait after pre_test_command before starting the server */
+    pre_test_wait_ms?: number;
+    /** Milliseconds to wait for HTTP server to start (when using start_command with HTTP transport) */
+    startup_wait_ms?: number;
+    /** Command to run after stopping the MCP server for this config (cleanup) */
+    post_test_command?: string;
+}
+export interface CustomMessage {
+    id: number;
+    name: string;
+    message: Record<string, unknown>;
+}
+export interface ActionInputs {
+    setupNode: boolean;
+    nodeVersion: string;
+    setupPython: boolean;
+    pythonVersion: string;
+    setupGo: boolean;
+    goVersion: string;
+    setupRust: boolean;
+    rustToolchain: string;
+    setupDotnet: boolean;
+    dotnetVersion: string;
+    installCommand: string;
+    buildCommand: string;
+    startCommand: string;
+    transport: "stdio" | "streamable-http";
+    serverUrl: string;
+    headers: Record<string, string>;
+    configurations: TestConfiguration[];
+    customMessages: CustomMessage[];
+    compareRef: string;
+    failOnError: boolean;
+    failOnDiff: boolean;
+    envVars: string;
+    serverTimeout: number;
+    httpStartCommand: string;
+    httpStartupWaitMs: number;
+}
+export interface ProbeResult {
+    initialize: InitializeInfo | null;
+    tools: ToolsResult | null;
+    prompts: PromptsResult | null;
+    resources: ResourcesResult | null;
+    resourceTemplates: ResourceTemplatesResult | null;
+    customResponses: Map<string, unknown>;
+    error?: string;
+}
+export interface InitializeInfo {
+    serverInfo?: {
+        name: string;
+        version: string;
+    };
+    capabilities?: Record<string, unknown>;
+}
+export interface ToolsResult {
+    tools: Array<{
+        name: string;
+        description?: string;
+        inputSchema?: Record<string, unknown>;
+    }>;
+}
+export interface PromptsResult {
+    prompts: Array<{
+        name: string;
+        description?: string;
+        arguments?: Array<{
+            name: string;
+            description?: string;
+            required?: boolean;
+        }>;
+    }>;
+}
+export interface ResourcesResult {
+    resources: Array<{
+        uri: string;
+        name: string;
+        description?: string;
+        mimeType?: string;
+    }>;
+}
+export interface ResourceTemplatesResult {
+    resourceTemplates: Array<{
+        uriTemplate: string;
+        name: string;
+        description?: string;
+        mimeType?: string;
+    }>;
+}
+/** Counts of MCP primitives discovered */
+export interface PrimitiveCounts {
+    tools: number;
+    prompts: number;
+    resources: number;
+    resourceTemplates: number;
+}
+export interface TestResult {
+    configName: string;
+    transport: string;
+    branchTime: number;
+    baseTime: number;
+    hasDifferences: boolean;
+    diffs: Map<string, string>;
+    /** Primitive counts from current branch */
+    branchCounts?: PrimitiveCounts;
+    /** Primitive counts from base ref */
+    baseCounts?: PrimitiveCounts;
+    /** Error message if probing failed */
+    error?: string;
+}
+export interface ConformanceReport {
+    generatedAt: string;
+    currentBranch: string;
+    compareRef: string;
+    results: TestResult[];
+    totalBranchTime: number;
+    totalBaseTime: number;
+    passedCount: number;
+    diffCount: number;
+}

package/dist/cli.d.ts

@@ -0,0 +1,7 @@
+/**
+ * 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.
+ */
+export {};

package/dist/diff.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Core diffing logic for MCP servers
+ *
+ * Pure functions for comparing probe results - no I/O side effects.
+ */
+import type { ProbeResult, PrimitiveCounts } from "./types.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 declare function extractCounts(result: ProbeResult): PrimitiveCounts;
+/**
+ * Compare two probe results and return structured diff results
+ */
+export declare function compareProbeResults(baseResult: ProbeResult, targetResult: ProbeResult): DiffResult[];
+/**
+ * Generate semantic JSON diff
+ */
+export declare function generateJsonDiff(name: string, base: string, target: string): string | null;
+/**
+ * Recursively find differences between two JSON objects
+ */
+export declare function findJsonDifferences(base: unknown, target: unknown, path: string): string[];
+/**
+ * Format a value for display in diff output
+ */
+export declare function formatValue(value: unknown): string;
+/**
+ * Convert DiffResult array to Map for backward compatibility
+ */
+export declare function diffsToMap(diffs: DiffResult[]): Map<string, string>;

package/dist/git.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Git utilities for MCP server diff
+ */
+export interface GitInfo {
+    currentBranch: string;
+    compareRef: string;
+}
+/**
+ * Get current branch name
+ */
+export declare function getCurrentBranch(): Promise<string>;
+/**
+ * Determine what ref to compare against
+ * Priority: 1) Explicit compare_ref, 2) Auto-detect previous tag, 3) Merge-base with main
+ */
+export declare function determineCompareRef(explicitRef?: string, githubRef?: string): Promise<string>;
+/**
+ * Create a worktree for the compare ref
+ */
+export declare function createWorktree(ref: string, path: string): Promise<boolean>;
+/**
+ * Remove a worktree
+ */
+export declare function removeWorktree(path: string): Promise<void>;
+/**
+ * Checkout a ref (fallback if worktree fails)
+ */
+export declare function checkout(ref: string): Promise<void>;
+/**
+ * Checkout previous branch/ref
+ */
+export declare function checkoutPrevious(): Promise<void>;
+/**
+ * Get a display-friendly name for a ref.
+ * Returns branch/tag name if available, otherwise the short SHA.
+ */
+export declare function getRefDisplayName(ref: string): Promise<string>;

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * MCP Server Diff - Main Entry Point
+ *
+ * Diffs MCP server public interfaces by comparing
+ * API responses between the current branch and a reference.
+ */
+export {};