mcp-server-diff 2.1.0

package/action.yml

@@ -0,0 +1,250 @@
+name: 'MCP Server Diff'
+description: 'Diff MCP server public interfaces between versions'
+author: 'Sam Morrow'
+branding:
+  icon: 'check-circle'
+  color: 'green'
+
+inputs:
+  # Language setup (optional convenience)
+  setup_node:
+    description: 'Set up Node.js environment'
+    required: false
+    default: 'false'
+  node_version:
+    description: 'Node.js version (default: 20)'
+    required: false
+    default: '20'
+  setup_python:
+    description: 'Set up Python environment'
+    required: false
+    default: 'false'
+  python_version:
+    description: 'Python version (default: 3.11)'
+    required: false
+    default: '3.11'
+  setup_go:
+    description: 'Set up Go environment'
+    required: false
+    default: 'false'
+  go_version:
+    description: 'Go version (default: read from go.mod)'
+    required: false
+    default: ''
+  setup_rust:
+    description: 'Set up Rust environment'
+    required: false
+    default: 'false'
+  rust_toolchain:
+    description: 'Rust toolchain (default: stable)'
+    required: false
+    default: 'stable'
+  setup_dotnet:
+    description: 'Set up .NET environment'
+    required: false
+    default: 'false'
+  dotnet_version:
+    description: '.NET version (default: 8.0.x)'
+    required: false
+    default: '8.0.x'
+
+  # Build configuration
+  install_command:
+    description: 'Command to install dependencies (optional if no install step needed)'
+    required: false
+    default: ''
+  build_command:
+    description: 'Command to build the MCP server (optional for interpreted languages)'
+    required: false
+    default: ''
+  start_command:
+    description: 'Command to start the MCP server (for stdio transport, or to start HTTP server)'
+    required: false
+    default: ''
+
+  # Transport configuration
+  transport:
+    description: 'Transport type: stdio or streamable-http'
+    required: false
+    default: 'stdio'
+  server_url:
+    description: 'Server URL for HTTP transport (e.g., http://localhost:3000/mcp)'
+    required: false
+    default: ''
+  configurations:
+    description: |
+      JSON array of test configurations for multiple transports/scenarios. 
+      Each object supports: name, transport, start_command, args, server_url, headers, env_vars, custom_messages.
+      
+      For HTTP transport, use start_command to have the action manage server lifecycle:
+        - start_command: Command to start the server (action spawns, probes, then kills it)
+        - startup_wait_ms: Milliseconds to wait for server startup (default: 2000)
+      
+      Or use pre/post commands for manual control:
+        - pre_test_command: Command to run before probing (e.g., start server in background)
+        - pre_test_wait_ms: Milliseconds to wait after pre_test_command
+        - post_test_command: Command to run after probing (e.g., kill server process)
+    required: false
+    default: ''
+  custom_messages:
+    description: 'JSON array of custom JSON-RPC messages to send. Each object: id (number), name (string), message (JSON-RPC object). Applied to all configurations unless overridden per-config.'
+    required: false
+    default: ''
+  headers:
+    description: 'HTTP headers to send with streamable-http requests. JSON object or newline-separated "Header: value" pairs. Applied to all HTTP configurations unless overridden per-config.'
+    required: false
+    default: ''
+
+  # Test configuration
+  compare_ref:
+    description: 'Git ref to compare against (auto-detects merge-base or previous tag if not set)'
+    required: false
+    default: ''
+  fail_on_error:
+    description: 'Fail the action if probe errors occur (not just API differences)'
+    required: false
+    default: 'true'
+  fail_on_diff:
+    description: 'Fail the action if API differences are detected (useful for release validation)'
+    required: false
+    default: 'false'
+  env_vars:
+    description: 'Environment variables (newline-separated KEY=VALUE pairs)'
+    required: false
+    default: ''
+  server_timeout:
+    description: 'Timeout in seconds to wait for server response'
+    required: false
+    default: '10'
+
+  # Shared HTTP server (starts once, tests all HTTP configurations against it)
+  http_start_command:
+    description: |
+      Command to start a shared HTTP server for all HTTP transport configurations.
+      When set, the server starts once before all HTTP tests and stops after they complete.
+      This is more efficient than starting/stopping per-configuration.
+      Per-config start_command is ignored when this is set.
+    required: false
+    default: ''
+  http_startup_wait_ms:
+    description: 'Milliseconds to wait for shared HTTP server to start (default: 2000)'
+    required: false
+    default: '2000'
+
+outputs:
+  status:
+    description: 'Test status (passed, differences, or error)'
+    value: ${{ steps.diff.outputs.status }}
+  report_path:
+    description: 'Path to the diff report'
+    value: 'mcp-diff-report/MCP_DIFF_REPORT.md'
+
+runs:
+  using: 'composite'
+  steps:
+    # Optional language setup
+    - name: Set up Node.js
+      if: inputs.setup_node == 'true'
+      uses: actions/setup-node@6044e13b5dc448c55e2357c09f80417699197238 # v6.2.0
+      with:
+        node-version: ${{ inputs.node_version }}
+
+    - name: Set up Python
+      if: inputs.setup_python == 'true'
+      uses: actions/setup-python@83679a892e2d95755f2dac6acb0bfd1e9ac5d548 # v6.1.0
+      with:
+        python-version: ${{ inputs.python_version }}
+
+    - name: Set up Go
+      if: inputs.setup_go == 'true'
+      uses: actions/setup-go@7a3fe6cf4cb3a834922a1244abfce67bcef6a0c5 # v6.2.0
+      with:
+        go-version: ${{ inputs.go_version || null }}
+        go-version-file: ${{ inputs.go_version == '' && 'go.mod' || null }}
+
+    - name: Set up Rust
+      if: inputs.setup_rust == 'true'
+      uses: dtolnay/rust-toolchain@f7ccc83f9ed1e5b9c81d8a67d7ad1a747e22a561 # master
+      with:
+        toolchain: ${{ inputs.rust_toolchain }}
+
+    - name: Set up .NET
+      if: inputs.setup_dotnet == 'true'
+      uses: actions/setup-dotnet@baa11fbfe1d6520db94683bd5c7a3818018e4309 # v5.1.0
+      with:
+        dotnet-version: ${{ inputs.dotnet_version }}
+
+    - name: Set environment variables
+      if: inputs.env_vars != ''
+      shell: bash
+      run: |
+        echo "${{ inputs.env_vars }}" >> $GITHUB_ENV
+
+    - name: Run MCP server diff
+      id: diff
+      shell: bash
+      env:
+        INPUT_INSTALL_COMMAND: ${{ inputs.install_command }}
+        INPUT_BUILD_COMMAND: ${{ inputs.build_command }}
+        INPUT_START_COMMAND: ${{ inputs.start_command }}
+        INPUT_SERVER_TIMEOUT: ${{ inputs.server_timeout }}
+        INPUT_COMPARE_REF: ${{ inputs.compare_ref }}
+        INPUT_FAIL_ON_ERROR: ${{ inputs.fail_on_error }}
+        INPUT_TRANSPORT: ${{ inputs.transport }}
+        INPUT_SERVER_URL: ${{ inputs.server_url }}
+        INPUT_CONFIGURATIONS: ${{ inputs.configurations }}
+        INPUT_CUSTOM_MESSAGES: ${{ inputs.custom_messages }}
+        INPUT_HEADERS: ${{ inputs.headers }}
+        INPUT_ENV_VARS: ${{ inputs.env_vars }}
+        INPUT_HTTP_START_COMMAND: ${{ inputs.http_start_command }}
+        INPUT_HTTP_STARTUP_WAIT_MS: ${{ inputs.http_startup_wait_ms }}
+        INPUT_SETUP_NODE: ${{ inputs.setup_node }}
+        INPUT_NODE_VERSION: ${{ inputs.node_version }}
+        INPUT_SETUP_PYTHON: ${{ inputs.setup_python }}
+        INPUT_PYTHON_VERSION: ${{ inputs.python_version }}
+        INPUT_SETUP_GO: ${{ inputs.setup_go }}
+        INPUT_GO_VERSION: ${{ inputs.go_version }}
+        INPUT_SETUP_RUST: ${{ inputs.setup_rust }}
+        INPUT_RUST_TOOLCHAIN: ${{ inputs.rust_toolchain }}
+        INPUT_SETUP_DOTNET: ${{ inputs.setup_dotnet }}
+        INPUT_DOTNET_VERSION: ${{ inputs.dotnet_version }}
+      run: |
+        node "${{ github.action_path }}/dist/index.js"
+
+    - name: Generate Job Summary
+      shell: bash
+      run: |
+        echo "# MCP Server Diff Report" >> $GITHUB_STEP_SUMMARY
+        echo "" >> $GITHUB_STEP_SUMMARY
+        if [ -n "${{ inputs.compare_ref }}" ]; then
+          echo "Comparing against: \`${{ inputs.compare_ref }}\`" >> $GITHUB_STEP_SUMMARY
+        elif [[ "${{ github.ref }}" == refs/tags/* ]]; then
+          echo "Comparing tag against previous tag (auto-detected)" >> $GITHUB_STEP_SUMMARY
+        else
+          echo "Comparing against merge-base with \`origin/main\`" >> $GITHUB_STEP_SUMMARY
+        fi
+        echo "" >> $GITHUB_STEP_SUMMARY
+        
+        if [ -f mcp-diff-report/MCP_DIFF_REPORT.md ]; then
+          tail -n +5 mcp-diff-report/MCP_DIFF_REPORT.md >> $GITHUB_STEP_SUMMARY
+        else
+          echo "Report file not found - check the workflow logs for errors" >> $GITHUB_STEP_SUMMARY
+        fi
+        
+        echo "" >> $GITHUB_STEP_SUMMARY
+        echo "---" >> $GITHUB_STEP_SUMMARY
+        echo "" >> $GITHUB_STEP_SUMMARY
+        
+        if [ "${{ steps.diff.outputs.status }}" = "passed" ]; then
+          echo "**No API changes detected** between the branches." >> $GITHUB_STEP_SUMMARY
+        else
+          echo "**API changes detected** — review above to confirm they are expected." >> $GITHUB_STEP_SUMMARY
+        fi
+
+    - name: Upload diff report
+      if: always()
+      uses: actions/upload-artifact@b7c566a772e6b6bfb58ed0dc250532a479d7789f # v6.0.0
+      with:
+        name: mcp-diff-report
+        path: mcp-diff-report/
+        if-no-files-found: ignore

package/dist/__tests__/fixtures/http-server.d.ts

@@ -0,0 +1,7 @@
+#!/usr/bin/env npx tsx
+/**
+ * Minimal MCP Server for integration testing (streamable-http transport)
+ *
+ * Run with: npx tsx http-server.ts <port>
+ */
+export {};

package/dist/__tests__/fixtures/stdio-server.d.ts

@@ -0,0 +1,7 @@
+#!/usr/bin/env npx tsx
+/**
+ * Minimal MCP Server for integration testing (stdio transport)
+ *
+ * This server exposes tools, prompts, and resources for testing the probe functionality.
+ */
+export {};

package/dist/cli/__tests__/fixtures/http-server.d.ts

@@ -0,0 +1,7 @@
+#!/usr/bin/env npx tsx
+/**
+ * Minimal MCP Server for integration testing (streamable-http transport)
+ *
+ * Run with: npx tsx http-server.ts <port>
+ */
+export {};

package/dist/cli/__tests__/fixtures/stdio-server.d.ts

@@ -0,0 +1,7 @@
+#!/usr/bin/env npx tsx
+/**
+ * Minimal MCP Server for integration testing (stdio transport)
+ *
+ * This server exposes tools, prompts, and resources for testing the probe functionality.
+ */
+export {};

package/dist/cli/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/cli/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/cli/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/cli/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 {};