mcp-server-diff 2.1.0

package/dist/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/eslint.config.mjs

@@ -0,0 +1,47 @@
+import eslint from "@eslint/js";
+import tseslint from "typescript-eslint";
+import prettier from "eslint-config-prettier";
+
+export default tseslint.config(
+  eslint.configs.recommended,
+  ...tseslint.configs.recommended,
+  prettier,
+  {
+    languageOptions: {
+      parserOptions: {
+        project: "./tsconfig.json",
+      },
+    },
+    rules: {
+      "@typescript-eslint/no-unused-vars": [
+        "error",
+        { argsIgnorePattern: "^_", varsIgnorePattern: "^_" },
+      ],
+      "@typescript-eslint/explicit-function-return-type": "off",
+      "@typescript-eslint/no-explicit-any": "warn",
+      "no-console": "warn",
+    },
+  },
+  {
+    // Test files don't need the project reference and need Jest globals
+    files: ["**/__tests__/**/*.ts", "**/*.test.ts"],
+    languageOptions: {
+      parserOptions: {
+        project: null,
+      },
+      globals: {
+        describe: "readonly",
+        it: "readonly",
+        expect: "readonly",
+        beforeEach: "readonly",
+        afterEach: "readonly",
+        beforeAll: "readonly",
+        afterAll: "readonly",
+        jest: "readonly",
+      },
+    },
+  },
+  {
+    ignores: ["dist/**", "node_modules/**", "*.js", "*.mjs"],
+  }
+);

package/jest.config.mjs

@@ -0,0 +1,26 @@
+/** @type {import('jest').Config} */
+export default {
+  preset: "ts-jest/presets/default-esm",
+  testEnvironment: "node",
+  extensionsToTreatAsEsm: [".ts"],
+  // Force exit after tests complete - needed because npx tsx leaves handles open
+  forceExit: true,
+  moduleNameMapper: {
+    "^(\\.{1,2}/.*)\\.js$": "$1",
+  },
+  transform: {
+    "^.+\\.tsx?$": [
+      "ts-jest",
+      {
+        useESM: true,
+        diagnostics: {
+          ignoreCodes: [151002],
+        },
+      },
+    ],
+  },
+  testMatch: ["**/__tests__/**/*.test.ts", "**/*.test.ts"],
+  collectCoverageFrom: ["src/**/*.ts", "!src/**/*.d.ts"],
+  coverageDirectory: "coverage",
+  coverageReporters: ["text", "lcov", "html"],
+};

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "mcp-server-diff",
+  "version": "2.1.0",
+  "description": "Diff MCP server public interfaces - CLI tool and GitHub Action",
+  "main": "dist/index.js",
+  "bin": {
+    "mcp-server-diff": "dist/cli/index.js"
+  },
+  "type": "module",
+  "scripts": {
+    "build": "npm run build:action && npm run build:cli",
+    "build:action": "ncc build src/index.ts -o dist --license licenses.txt --no-source-map-register",
+    "build:cli": "ncc build src/cli.ts -o dist/cli --license licenses.txt --no-source-map-register && node -e \"const fs=require('fs'); const p='dist/cli/index.js'; fs.writeFileSync(p, '#!/usr/bin/env node\\n' + fs.readFileSync(p))\"",
+    "lint": "eslint src/",
+    "lint:fix": "eslint src/ --fix",
+    "format": "prettier --write src/",
+    "format:check": "prettier --check src/",
+    "test": "node --experimental-vm-modules node_modules/jest/bin/jest.js",
+    "test:coverage": "npm test -- --coverage",
+    "typecheck": "tsc --noEmit",
+    "check": "npm run typecheck && npm run lint && npm run format:check && npm test",
+    "prepublishOnly": "npm run check && npm run build"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/SamMorrowDrums/mcp-server-diff.git"
+  },
+  "keywords": [
+    "cli",
+    "github-action",
+    "mcp",
+    "model-context-protocol",
+    "diff",
+    "api-changes"
+  ],
+  "author": "Sam Morrow",
+  "license": "MIT",
+  "dependencies": {
+    "@actions/core": "^1.11.1",
+    "@actions/exec": "^1.1.1",
+    "@actions/io": "^1.1.3",
+    "@modelcontextprotocol/sdk": "^1.13.2",
+    "diff": "^8.0.3",
+    "undici": "^6.23.0",
+    "zod": "^3.24.5"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.17.0",
+    "@types/diff": "^7.0.2",
+    "@types/jest": "^29.5.14",
+    "@types/node": "^22.0.0",
+    "@vercel/ncc": "^0.38.3",
+    "eslint": "^9.17.0",
+    "eslint-config-prettier": "^10.0.1",
+    "jest": "^29.7.0",
+    "prettier": "^3.4.2",
+    "ts-jest": "^29.2.5",
+    "typescript": "^5.6.0",
+    "typescript-eslint": "^8.19.1"
+  },
+  "overrides": {
+    "undici": "^6.23.0"
+  }
+}

package/src/__tests__/fixtures/http-server.ts

@@ -0,0 +1,103 @@
+#!/usr/bin/env npx tsx
+/**
+ * Minimal MCP Server for integration testing (streamable-http transport)
+ *
+ * Run with: npx tsx http-server.ts <port>
+ */
+
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+import * as http from "http";
+
+const server = new Server(
+  {
+    name: "test-http-server",
+    version: "1.0.0",
+  },
+  {
+    capabilities: {
+      tools: {},
+    },
+  }
+);
+
+// Define tools
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+  return {
+    tools: [
+      {
+        name: "echo",
+        description: "Echoes back the input",
+        inputSchema: {
+          type: "object" as const,
+          properties: {
+            message: { type: "string", description: "Message to echo" },
+          },
+          required: ["message"],
+        },
+      },
+    ],
+  };
+});
+
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const { name, arguments: args } = request.params;
+
+  if (name === "echo") {
+    return {
+      content: [{ type: "text", text: (args as { message: string }).message }],
+    };
+  }
+
+  throw new Error(`Unknown tool: ${name}`);
+});
+
+// Create HTTP server with streamable transport
+async function main() {
+  const httpServer = http.createServer();
+  const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined });
+
+  httpServer.on("request", async (req, res) => {
+    // Simple CORS support
+    res.setHeader("Access-Control-Allow-Origin", "*");
+    res.setHeader("Access-Control-Allow-Methods", "GET, POST, OPTIONS");
+    res.setHeader("Access-Control-Allow-Headers", "Content-Type");
+
+    if (req.method === "OPTIONS") {
+      res.writeHead(200);
+      res.end();
+      return;
+    }
+
+    if (req.url === "/mcp" || req.url?.startsWith("/mcp?")) {
+      await transport.handleRequest(req, res);
+    } else {
+      res.writeHead(404);
+      res.end("Not found");
+    }
+  });
+
+  await server.connect(transport);
+
+  // Use port 0 to let the OS assign a free port, unless specific port given
+  const requestedPort = parseInt(process.argv[2] || "0", 10);
+  httpServer.listen(requestedPort, () => {
+    const addr = httpServer.address();
+    const actualPort = typeof addr === "object" && addr ? addr.port : requestedPort;
+    // Output format that tests parse: "listening on port XXXXX"
+    console.log(`Test HTTP MCP server listening on port ${actualPort}`);
+  });
+
+  // Handle shutdown
+  process.on("SIGTERM", () => {
+    httpServer.close();
+    process.exit(0);
+  });
+  process.on("SIGINT", () => {
+    httpServer.close();
+    process.exit(0);
+  });
+}
+
+main().catch(console.error);

package/src/__tests__/fixtures/stdio-server.ts

@@ -0,0 +1,158 @@
+#!/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.
+ */
+
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  CallToolRequestSchema,
+  GetPromptRequestSchema,
+  ListPromptsRequestSchema,
+  ListResourcesRequestSchema,
+  ListToolsRequestSchema,
+  ReadResourceRequestSchema,
+} from "@modelcontextprotocol/sdk/types.js";
+
+const server = new Server(
+  {
+    name: "test-stdio-server",
+    version: "1.0.0",
+  },
+  {
+    capabilities: {
+      tools: {},
+      prompts: {},
+      resources: {},
+    },
+  }
+);
+
+// Define tools
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+  return {
+    tools: [
+      {
+        name: "greet",
+        description: "Greets a person by name",
+        inputSchema: {
+          type: "object" as const,
+          properties: {
+            name: { type: "string", description: "Name to greet" },
+          },
+          required: ["name"],
+        },
+      },
+      {
+        name: "add",
+        description: "Adds two numbers",
+        inputSchema: {
+          type: "object" as const,
+          properties: {
+            a: { type: "number", description: "First number" },
+            b: { type: "number", description: "Second number" },
+          },
+          required: ["a", "b"],
+        },
+      },
+    ],
+  };
+});
+
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const { name, arguments: args } = request.params;
+
+  if (name === "greet") {
+    return {
+      content: [{ type: "text", text: `Hello, ${(args as { name: string }).name}!` }],
+    };
+  }
+
+  if (name === "add") {
+    const { a, b } = args as { a: number; b: number };
+    // Return as embedded JSON to test normalization
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify({ result: a + b, operation: "add", inputs: { b, a } }),
+        },
+      ],
+    };
+  }
+
+  throw new Error(`Unknown tool: ${name}`);
+});
+
+// Define prompts
+server.setRequestHandler(ListPromptsRequestSchema, async () => {
+  return {
+    prompts: [
+      {
+        name: "code-review",
+        description: "Review code for issues",
+        arguments: [
+          { name: "code", description: "The code to review", required: true },
+          { name: "language", description: "Programming language", required: false },
+        ],
+      },
+    ],
+  };
+});
+
+server.setRequestHandler(GetPromptRequestSchema, async (request) => {
+  if (request.params.name === "code-review") {
+    const args = request.params.arguments || {};
+    return {
+      messages: [
+        {
+          role: "user" as const,
+          content: {
+            type: "text" as const,
+            text: `Please review this ${args.language || "code"}:\n\n${args.code}`,
+          },
+        },
+      ],
+    };
+  }
+  throw new Error(`Unknown prompt: ${request.params.name}`);
+});
+
+// Define resources
+server.setRequestHandler(ListResourcesRequestSchema, async () => {
+  return {
+    resources: [
+      {
+        uri: "test://readme",
+        name: "README",
+        description: "Project readme file",
+        mimeType: "text/plain",
+      },
+    ],
+  };
+});
+
+server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
+  if (request.params.uri === "test://readme") {
+    return {
+      contents: [
+        {
+          uri: "test://readme",
+          mimeType: "text/plain",
+          text: "# Test Server\n\nThis is a test MCP server.",
+        },
+      ],
+    };
+  }
+  throw new Error(`Unknown resource: ${request.params.uri}`);
+});
+
+// Start the server
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}
+
+main().catch(console.error);