mcp-server-diff 2.1.0 → 2.1.6

package/README.md

@@ -1,10 +1,13 @@
 # MCP Server Diff
 
 [![GitHub Marketplace](https://img.shields.io/badge/Marketplace-MCP%20Server%20Diff-blue?logo=github)](https://github.com/marketplace/actions/mcp-server-diff)
+[![npm version](https://img.shields.io/npm/v/mcp-server-diff)](https://www.npmjs.com/package/mcp-server-diff)
 [![GitHub release](https://img.shields.io/github/v/release/SamMorrowDrums/mcp-server-diff)](https://github.com/SamMorrowDrums/mcp-server-diff/releases)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-A GitHub Action for diffing [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server **public interfaces** between versions. This action compares the current branch against a baseline to surface any changes to your server's exposed tools, resources, prompts, and capabilities—helping you document API evolution and catch unintended modifications.
+A GitHub Action for diffing [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server **public interfaces** between versions. Compares the current branch against a baseline to surface any changes to your server's exposed tools, resources, prompts, and capabilities.
+
+> **Also available as a standalone CLI** — see [CLI Documentation](#cli-tool) or install with `npx mcp-server-diff`
 
 ## Overview
 
@@ -496,6 +499,118 @@ jobs:
 - Ensure the server binds to `0.0.0.0` or `127.0.0.1`, not just `localhost` on some systems
 - Check firewall or container networking if running in Docker
 
+---
+
+## CLI Tool
+
+The CLI lets you diff any two MCP servers directly from your terminal—useful for local development, CI pipelines, or comparing servers across different implementations.
+
+### Installation
+
+```bash
+# Run directly with npx (no install required)
+npx mcp-server-diff --help
+
+# Or install globally
+npm install -g mcp-server-diff
+```
+
+### Basic Usage
+
+```bash
+# Compare two local stdio servers
+npx mcp-server-diff -b "python -m mcp_server" -t "node dist/stdio.js"
+
+# Compare local server vs remote HTTP endpoint
+npx mcp-server-diff -b "go run ./cmd/server stdio" -t "https://mcp.example.com/api"
+
+# Output formats
+npx mcp-server-diff -b "..." -t "..." -o diff      # Raw diff hunks only
+npx mcp-server-diff -b "..." -t "..." -o json      # Full JSON with details
+npx mcp-server-diff -b "..." -t "..." -o markdown  # Formatted report
+npx mcp-server-diff -b "..." -t "..." -o summary   # One-line summary (default)
+```
+
+### HTTP Headers & Authentication
+
+For authenticated HTTP endpoints, pass headers with `-H` (target) or `--base-header`:
+
+```bash
+# Direct header value for target
+npx mcp-server-diff -b "./server" -t "https://api.example.com/mcp" \
+  -H "Authorization: Bearer your-token-here"
+
+# Read from environment variable (keeps secrets out of shell history)
+export MCP_TOKEN="your-secret-token"
+npx mcp-server-diff -b "./server" -t "https://api.example.com/mcp" \
+  -H "Authorization: Bearer env:MCP_TOKEN"
+
+# Prompt for secret interactively (hidden input, named "token")
+npx mcp-server-diff -b "./server" -t "https://api.example.com/mcp" \
+  -H "Authorization: Bearer secret:token"
+
+# Headers for both sides (e.g., comparing two authenticated servers)
+npx mcp-server-diff \
+  -b "https://api.example.com/v1/mcp" --base-header "Authorization: Bearer secret:v1token" \
+  -t "https://api.example.com/v2/mcp" -H "Authorization: Bearer secret:v2token"
+```
+
+### Config File
+
+For complex comparisons or multiple targets, use a config file:
+
+```bash
+npx mcp-server-diff -c servers.json -o diff
+```
+
+```json
+{
+  "base": {
+    "name": "python-server",
+    "transport": "stdio",
+    "start_command": "python -m mcp_server"
+  },
+  "targets": [
+    {
+      "name": "typescript-server",
+      "transport": "stdio",
+      "start_command": "node dist/stdio.js"
+    },
+    {
+      "name": "remote-server",
+      "transport": "streamable-http",
+      "server_url": "https://mcp.example.com/api",
+      "headers": {
+        "Authorization": "Bearer token"
+      }
+    }
+  ]
+}
+```
+
+### CLI Options Reference
+
+| Option | Description |
+|--------|-------------|
+| `-b, --base <cmd\|url>` | Base server command (stdio) or URL (http) |
+| `-t, --target <cmd\|url>` | Target server command (stdio) or URL (http) |
+| `-H, --header <header>` | HTTP header for target (repeatable) |
+| `--base-header <header>` | HTTP header for base server (repeatable) |
+| `--target-header <header>` | HTTP header for target (same as `-H`) |
+| `-c, --config <file>` | Config file with base and targets |
+| `-o, --output <format>` | Output: `diff`, `json`, `markdown`, `summary` (default) |
+| `-v, --verbose` | Verbose output |
+| `-q, --quiet` | Quiet mode (only output result) |
+| `-h, --help` | Show help |
+| `--version` | Show version |
+
+**Header value patterns:**
+- `Bearer your-token` — literal value
+- `Bearer env:VAR_NAME` — read from environment variable  
+- `Bearer secret:name` — prompt once for "name", reuse if used multiple times
+
+---
+
 ## License
 
 MIT License. See [LICENSE](LICENSE) for details.

package/dist/cli/index.js

@@ -38918,6 +38918,8 @@ var __webpack_exports__ = {};
 var external_node_util_ = __nccwpck_require__(7975);
 // EXTERNAL MODULE: external "fs"
 var external_fs_ = __nccwpck_require__(9896);
+;// CONCATENATED MODULE: external "readline"
+const external_readline_namespaceObject = __WEBPACK_EXTERNAL_createRequire(import.meta.url)("readline");
 ;// CONCATENATED MODULE: ./node_modules/zod/v4/core/core.js
 /** A special constant with type `never` */
 const NEVER = Object.freeze({
@@ -56353,6 +56355,13 @@ const log = {
 
 
 
+/**
+ * Check if an error is "Method not found" (-32601)
+ */
+function isMethodNotFound(error) {
+    const errorStr = String(error);
+    return errorStr.includes("-32601") || errorStr.includes("Method not found");
+}
 /**
  * Probes an MCP server and returns capability snapshots
  */
@@ -56425,7 +56434,12 @@ async function probeServer(options) {
                 log.info(`  Listed ${result.tools.tools.length} tools`);
             }
             catch (error) {
-                log.warning(`  Failed to list tools: ${error}`);
+                if (isMethodNotFound(error)) {
+                    log.info("  Server does not implement tools/list");
+                }
+                else {
+                    log.warning(`  Failed to list tools: ${error}`);
+                }
             }
         }
         else {
@@ -56439,7 +56453,12 @@ async function probeServer(options) {
                 log.info(`  Listed ${result.prompts.prompts.length} prompts`);
             }
             catch (error) {
-                log.warning(`  Failed to list prompts: ${error}`);
+                if (isMethodNotFound(error)) {
+                    log.info("  Server does not implement prompts/list");
+                }
+                else {
+                    log.warning(`  Failed to list prompts: ${error}`);
+                }
             }
         }
         else {
@@ -56453,16 +56472,26 @@ async function probeServer(options) {
                 log.info(`  Listed ${result.resources.resources.length} resources`);
             }
             catch (error) {
-                log.warning(`  Failed to list resources: ${error}`);
+                if (isMethodNotFound(error)) {
+                    log.info("  Server does not implement resources/list");
+                }
+                else {
+                    log.warning(`  Failed to list resources: ${error}`);
+                }
             }
-            // Also get resource templates
+            // Also try resource templates - some servers support resources but not templates
             try {
                 const templatesResult = await client.listResourceTemplates();
                 result.resourceTemplates = templatesResult;
                 log.info(`  Listed ${result.resourceTemplates.resourceTemplates.length} resource templates`);
             }
             catch (error) {
-                log.warning(`  Failed to list resource templates: ${error}`);
+                if (isMethodNotFound(error)) {
+                    log.info("  Server does not implement resources/templates/list");
+                }
+                else {
+                    log.warning(`  Failed to list resource templates: ${error}`);
+                }
             }
         }
         else {
@@ -56831,6 +56860,7 @@ function diffsToMap(diffs) {
 
 
 
+
 /**
  * Parse command line arguments
  */
@@ -56839,6 +56869,9 @@ function parseCliArgs() {
         options: {
             base: { type: "string", short: "b" },
             target: { type: "string", short: "t" },
+            header: { type: "string", short: "H", multiple: true },
+            "base-header": { type: "string", multiple: true },
+            "target-header": { type: "string", multiple: true },
             config: { type: "string", short: "c" },
             output: { type: "string", short: "o", default: "summary" },
             verbose: { type: "boolean", short: "v", default: false },
@@ -56864,14 +56897,18 @@ USAGE:
   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
+  -b, --base <command>       Base server command (stdio) or URL (http)
+  -t, --target <command>     Target server command (stdio) or URL (http)
+  -H, --header <header>      HTTP header for target (repeatable)
+      --base-header <header> HTTP header for base server (repeatable)
+      --target-header <hdr>  HTTP header for target server (repeatable, same as -H)
+                             Values support: env:VAR_NAME, secret:name, "Bearer secret:token"
+  -c, --config <file>        Config file with base and targets
+  -o, --output <format>      Output format: diff, 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:
   {
@@ -56890,6 +56927,7 @@ CONFIG FILE FORMAT:
   }
 
 OUTPUT FORMATS:
+  diff      - Raw diff output only
   summary   - One line per comparison (default)
   json      - Raw JSON with full diff details
   markdown  - Formatted markdown report
@@ -56906,6 +56944,18 @@ EXAMPLES:
 
   # Output raw JSON for CI
   mcp-server-diff -c servers.json -o json -q
+
+  # Compare with HTTP headers (for authenticated endpoints)
+  mcp-server-diff -b "go run ./cmd/server stdio" -t "https://api.example.com/mcp" \\
+    -H "Authorization: Bearer token" -o diff
+
+  # Use environment variable for secret (keeps token out of shell history)
+  mcp-server-diff -b "./server" -t "https://api.example.com/mcp" \\
+    -H "Authorization: env:MY_API_TOKEN"
+
+  # Prompt for secret interactively (hidden input)
+  mcp-server-diff -b "./server" -t "https://api.example.com/mcp" \\
+    -H "Authorization: secret:"
 `);
 }
 /**
@@ -56925,12 +56975,13 @@ function loadConfig(configPath) {
 /**
  * Create a server config from a command string
  */
-function commandToConfig(command, name) {
+function commandToConfig(command, name, headers) {
     if (command.startsWith("http://") || command.startsWith("https://")) {
         return {
             name,
             transport: "streamable-http",
             server_url: command,
+            headers,
         };
     }
     return {
@@ -56939,6 +56990,132 @@ function commandToConfig(command, name) {
         start_command: command,
     };
 }
+/**
+ * Parse header strings into a record
+ * Accepts formats: "Header: value" or "Header=value"
+ * Special value patterns:
+ *   env:VAR_NAME - reads from environment variable
+ *   secret:name - prompts for secret (name is the prompt label)
+ *   "Bearer secret:token" - prefix + secret (prompts for "token", prepends "Bearer ")
+ */
+function parseHeaders(headerStrings, secretValues) {
+    const headers = {};
+    if (!headerStrings)
+        return headers;
+    for (const h of headerStrings) {
+        const colonIdx = h.indexOf(":");
+        const eqIdx = h.indexOf("=");
+        const sepIdx = colonIdx > 0 ? colonIdx : eqIdx;
+        if (sepIdx > 0) {
+            const key = h.substring(0, sepIdx).trim();
+            let value = h.substring(sepIdx + 1).trim();
+            // Check for env: prefix to read from environment variable
+            if (value.startsWith("env:")) {
+                const envVar = value.substring(4);
+                const envValue = process.env[envVar];
+                if (!envValue) {
+                    throw new Error(`Environment variable ${envVar} not set (referenced in header ${key})`);
+                }
+                value = envValue;
+            }
+            else if (value.includes("secret:")) {
+                // Replace secret:name with the prompted value
+                const secretMatch = value.match(/secret:(\w+)/);
+                if (secretMatch) {
+                    const secretName = secretMatch[1];
+                    if (secretValues?.has(secretName)) {
+                        value = value.replace(`secret:${secretName}`, secretValues.get(secretName));
+                    }
+                    else {
+                        throw new Error(`Secret value for "${secretName}" not collected`);
+                    }
+                }
+            }
+            headers[key] = value;
+        }
+    }
+    return headers;
+}
+/**
+ * Find secrets that need prompts, returns array of {name, label} objects
+ */
+function findSecrets(headerStrings) {
+    const secrets = [];
+    if (!headerStrings)
+        return secrets;
+    for (const h of headerStrings) {
+        const secretMatch = h.match(/secret:(\w+)/);
+        if (secretMatch) {
+            const name = secretMatch[1];
+            // Don't add duplicates
+            if (!secrets.find((s) => s.name === name)) {
+                secrets.push({ name, label: name });
+            }
+        }
+    }
+    return secrets;
+}
+/**
+ * Prompt for a secret value with hidden input
+ */
+async function promptSecret(prompt) {
+    return new Promise((resolve) => {
+        const rl = external_readline_namespaceObject.createInterface({
+            input: process.stdin,
+            output: process.stdout,
+        });
+        // Hide input by using raw mode if available
+        if (process.stdin.isTTY) {
+            process.stdout.write(`${prompt}: `);
+            process.stdin.setRawMode(true);
+            process.stdin.resume();
+            let value = "";
+            const onData = (char) => {
+                const c = char.toString();
+                if (c === "\n" || c === "\r") {
+                    process.stdin.setRawMode(false);
+                    process.stdin.removeListener("data", onData);
+                    rl.close();
+                    process.stdout.write("\n");
+                    resolve(value);
+                }
+                else if (c === "\u0003") {
+                    // Ctrl+C
+                    process.exit(1);
+                }
+                else if (c === "\u007F" || c === "\b") {
+                    // Backspace
+                    if (value.length > 0) {
+                        value = value.slice(0, -1);
+                    }
+                }
+                else {
+                    value += c;
+                }
+            };
+            process.stdin.on("data", onData);
+        }
+        else {
+            // Non-TTY: just read the line (won't be hidden)
+            rl.question(`${prompt}: `, (answer) => {
+                rl.close();
+                resolve(answer);
+            });
+        }
+    });
+}
+/**
+ * Prompt for secret values with hidden input
+ */
+async function promptSecrets(secrets) {
+    const values = new Map();
+    if (secrets.length === 0)
+        return values;
+    for (const { name, label } of secrets) {
+        values.set(name, await promptSecret(`Enter ${label}`));
+    }
+    return values;
+}
 /**
  * Probe a server and return results
  */
@@ -57027,6 +57204,23 @@ async function runComparisons(config) {
     }
     return results;
 }
+/**
+ * Output raw diff only
+ */
+function outputDiff(results) {
+    for (const result of results) {
+        if (result.diffs.length > 0) {
+            if (results.length > 1) {
+                console.log(`# ${result.target}`);
+            }
+            for (const { endpoint, diff } of result.diffs) {
+                console.log(`## ${endpoint}`);
+                console.log(diff);
+                console.log("");
+            }
+        }
+    }
+}
 /**
  * Output results in summary format
  */
@@ -57133,7 +57327,7 @@ async function main() {
         process.exit(0);
     }
     if (values.version) {
-        console.log("mcp-server-diff v2.1.0");
+        console.log("mcp-server-diff v2.1.1");
         process.exit(0);
     }
     // Set up logger - CLI uses console logger by default
@@ -57148,9 +57342,21 @@ async function main() {
         config = loadConfig(values.config);
     }
     else if (values.base && values.target) {
+        // Combine -H and --target-header for target, use --base-header for base
+        const baseHeaderStrings = values["base-header"];
+        const targetHeaderStrings = [
+            ...(values.header || []),
+            ...(values["target-header"] || []),
+        ];
+        // Find all secrets needed from both header sets
+        const allHeaderStrings = [...(baseHeaderStrings || []), ...targetHeaderStrings];
+        const secrets = findSecrets(allHeaderStrings);
+        const secretValues = await promptSecrets(secrets);
+        const baseHeaders = parseHeaders(baseHeaderStrings, secretValues);
+        const targetHeaders = parseHeaders(targetHeaderStrings.length > 0 ? targetHeaderStrings : undefined, secretValues);
         config = {
-            base: commandToConfig(values.base, "base"),
-            targets: [commandToConfig(values.target, "target")],
+            base: commandToConfig(values.base, "base", baseHeaders),
+            targets: [commandToConfig(values.target, "target", targetHeaders)],
         };
     }
     else {
@@ -57161,6 +57367,9 @@ async function main() {
     const results = await runComparisons(config);
     const outputFormat = values.output || "summary";
     switch (outputFormat) {
+        case "diff":
+            outputDiff(results);
+            break;
         case "json":
             outputJson(results);
             break;

package/dist/index.js

@@ -56605,6 +56605,13 @@ const log = {
 
 
 
+/**
+ * Check if an error is "Method not found" (-32601)
+ */
+function isMethodNotFound(error) {
+    const errorStr = String(error);
+    return errorStr.includes("-32601") || errorStr.includes("Method not found");
+}
 /**
  * Probes an MCP server and returns capability snapshots
  */
@@ -56677,7 +56684,12 @@ async function probeServer(options) {
                 log.info(`  Listed ${result.tools.tools.length} tools`);
             }
             catch (error) {
-                log.warning(`  Failed to list tools: ${error}`);
+                if (isMethodNotFound(error)) {
+                    log.info("  Server does not implement tools/list");
+                }
+                else {
+                    log.warning(`  Failed to list tools: ${error}`);
+                }
             }
         }
         else {
@@ -56691,7 +56703,12 @@ async function probeServer(options) {
                 log.info(`  Listed ${result.prompts.prompts.length} prompts`);
             }
             catch (error) {
-                log.warning(`  Failed to list prompts: ${error}`);
+                if (isMethodNotFound(error)) {
+                    log.info("  Server does not implement prompts/list");
+                }
+                else {
+                    log.warning(`  Failed to list prompts: ${error}`);
+                }
             }
         }
         else {
@@ -56705,16 +56722,26 @@ async function probeServer(options) {
                 log.info(`  Listed ${result.resources.resources.length} resources`);
             }
             catch (error) {
-                log.warning(`  Failed to list resources: ${error}`);
+                if (isMethodNotFound(error)) {
+                    log.info("  Server does not implement resources/list");
+                }
+                else {
+                    log.warning(`  Failed to list resources: ${error}`);
+                }
             }
-            // Also get resource templates
+            // Also try resource templates - some servers support resources but not templates
             try {
                 const templatesResult = await client.listResourceTemplates();
                 result.resourceTemplates = templatesResult;
                 log.info(`  Listed ${result.resourceTemplates.resourceTemplates.length} resource templates`);
             }
             catch (error) {
-                log.warning(`  Failed to list resource templates: ${error}`);
+                if (isMethodNotFound(error)) {
+                    log.info("  Server does not implement resources/templates/list");
+                }
+                else {
+                    log.warning(`  Failed to list resource templates: ${error}`);
+                }
             }
         }
         else {

package/package.json

@@ -1,11 +1,16 @@
 {
   "name": "mcp-server-diff",
-  "version": "2.1.0",
+  "version": "2.1.6",
   "description": "Diff MCP server public interfaces - CLI tool and GitHub Action",
   "main": "dist/index.js",
   "bin": {
     "mcp-server-diff": "dist/cli/index.js"
   },
+  "files": [
+    "dist/",
+    "README.md",
+    "LICENSE"
+  ],
   "type": "module",
   "scripts": {
     "build": "npm run build:action && npm run build:cli",

package/.github/dependabot.yml

@@ -1,21 +0,0 @@
-version: 2
-updates:
-  - package-ecosystem: "github-actions"
-    directory: "/"
-    schedule:
-      interval: "weekly"
-    commit-message:
-      prefix: "ci"
-    labels:
-      - "dependencies"
-      - "github-actions"
-
-  - package-ecosystem: "npm"
-    directory: "/probe"
-    schedule:
-      interval: "weekly"
-    commit-message:
-      prefix: "deps"
-    labels:
-      - "dependencies"
-      - "javascript"

package/.github/workflows/ci.yml

@@ -1,51 +0,0 @@
-name: CI
-
-on:
-  push:
-    branches: [main]
-  pull_request:
-    branches: [main]
-
-permissions:
-  contents: read
-
-jobs:
-  test:
-    runs-on: ubuntu-latest
-    strategy:
-      matrix:
-        node-version: [20, 22]
-
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-
-      - name: Setup Node.js ${{ matrix.node-version }}
-        uses: actions/setup-node@v6
-        with:
-          node-version: ${{ matrix.node-version }}
-          cache: 'npm'
-
-      - name: Install dependencies
-        run: npm ci
-
-      - name: Type Check
-        run: npm run typecheck
-
-      - name: Lint
-        run: npm run lint
-
-      - name: Check Formatting
-        run: npm run format:check
-
-      - name: Run Tests
-        run: npm test
-
-      - name: Build
-        run: npm run build
-
-      - name: Verify dist is up to date
-        if: matrix.node-version == 20
-        run: |
-          # Check if dist files are up to date
-          git diff --exit-code dist/ || (echo "::error::dist/ is out of date. Run 'npm run build' and commit the changes." && exit 1)