SamMorrowDrums MCP-server-diff

MCP服务器差异

](https://github.com/marketplace/actions/mcp-server-diff) ](https://www.npmjs.com/package/mcp-server-diff) ](https://github.com/SamMorrowDrums/mcp-server-diff/releases) 

GitHub上的差异化操作 模型上下文协议（MCP） 服务器 公共接口 版本之间。将当前分支与基线进行比较，以显示对服务器公开的工具、资源、提示和功能的任何更改。

也可作为独立CLI提供 --看 CLI文档 或安装 npx mcp-server-diff

概述

MCP服务器公开 公共接口 AI助手：工具（及其输入模式）、资源、提示和服务器功能。随着服务器的发展，此界面的更改值得跟踪。此操作通过以下方式自动进行公共接口比较：

1. 从当前分支和基线（合并库、标记或指定引用）构建MCP服务器
2. 查询两个版本的完整公共界面（工具、资源、提示、功能）
3. 生成一份差异报告，准确显示发生了什么变化
4. 直接在GitHub的工作摘要中显示结果

这是 不 关于测试内部逻辑或正确性——这是关于对服务器内容的可见性 _广告_ 客户。

快速开始

创建 .github/workflows/mcp-diff.yml 在您的存储库中：

name: MCP Server Diff

on:
  pull_request:
    branches: [main]
  push:
    branches: [main]
    tags: ['v*']

permissions:
  contents: read

jobs:
  mcp-diff:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: SamMorrowDrums/mcp-server-diff@v2
        with:
          setup_node: true
          install_command: npm ci
          build_command: npm run build
          start_command: node dist/stdio.js

语言示例

Node.js/TypeScript

- uses: SamMorrowDrums/mcp-server-diff@v2
  with:
    setup_node: true
    node_version: '22'
    install_command: npm ci
    build_command: npm run build
    start_command: node dist/stdio.js

python

- uses: SamMorrowDrums/mcp-server-diff@v2
  with:
    setup_python: true
    python_version: '3.12'
    install_command: pip install -e .
    start_command: python -m my_mcp_server

去

- uses: SamMorrowDrums/mcp-server-diff@v2
  with:
    setup_go: true
    install_command: go mod download
    build_command: go build -o bin/server ./cmd/stdio
    start_command: ./bin/server

锈

- uses: SamMorrowDrums/mcp-server-diff@v2
  with:
    setup_rust: true
    install_command: cargo fetch
    build_command: cargo build --release
    start_command: ./target/release/my-mcp-server

C网

- uses: SamMorrowDrums/mcp-server-diff@v2
  with:
    setup_dotnet: true
    dotnet_version: '9.0.x'
    install_command: dotnet restore
    build_command: dotnet build -c Release
    start_command: dotnet run --no-build -c Release

自定义设置

如果您需要对环境设置（缓存、特定注册表等）进行更多控制，请在调用操作之前进行自己的设置：

steps:
  - uses: actions/checkout@v4
    with:
      fetch-depth: 0

  - uses: actions/setup-node@v4
    with:
      node-version: '22'
      cache: 'npm'
      registry-url: 'https://npm.pkg.github.com'

  - uses: SamMorrowDrums/mcp-server-diff@v2
    with:
      install_command: npm ci
      build_command: npm run build
      start_command: node dist/stdio.js

测试多种运输方式

使用以下命令在一次运行中测试stdio和HTTP传输 configurations 输入：

- uses: SamMorrowDrums/mcp-server-diff@v2
  with:
    setup_node: true
    install_command: npm ci
    build_command: npm run build
    configurations: |
      [
        {
          "name": "stdio",
          "transport": "stdio",
          "start_command": "node dist/stdio.js"
        },
        {
          "name": "streamable-http",
          "transport": "streamable-http",
          "start_command": "node dist/http.js",
          "server_url": "http://localhost:3000/mcp"
        }
      ]

输入参考

语言设置（可选）

所需输入

服务器配置

要么 start_command （用于stdio）或 server_url （对于HTTP）必须提供，除非使用 configurations.

比较配置

配置对象架构

使用时 configurations，每个对象支持：

与外部服务器进行比较

当与外部服务器（例如Docker镜像、远程服务）进行比较时，请使用 base_start_command 为基线指定不同的命令。这将跳过该配置的git checkout，直接探测指定的服务器：

configurations: |
  [
    {
      "name": "compare-versions",
      "transport": "stdio",
      "start_command": "docker run -i ghcr.io/example/mcp-server:v2.0.0",
      "base_start_command": "docker run -i ghcr.io/example/mcp-server:v1.0.0"
    }
  ]

这有助于：

• 版本比较：将新版本与旧版本进行比较
• 黄金参考测试：将您的本地代码与已知的良好参考进行比较
• 交叉实施测试：比较同一服务器的不同实现
• 自检CI：通过比较两个已知的不同服务器来验证该操作是否检测到差异

对于HTTP传输，请使用 base_server_url 旁边 base_start_command:

configurations: |
  [
    {
      "name": "http-comparison",
      "transport": "streamable-http",
      "start_command": "docker run -p 3000:3000 myserver:latest",
      "server_url": "http://localhost:3000/mcp",
      "base_start_command": "docker run -p 3001:3000 myserver:v1.0.0",
      "base_server_url": "http://localhost:3001/mcp"
    }
  ]

运作原理

执行流程

1. 基线检测：确定比较参考：

- 对于pull请求：将base与目标分支合并 - 对于标签推送：之前的标签（例如。， v1.1.0 与 v1.0.0) - 明确：使用 compare_ref 如果提供

1. 构建基线：在基线ref处创建git工作树并构建服务器
2. 构建当前：从当前分支构建服务器
3. 一致性测试：向两台服务器发送MCP协议请求：

- initialize -服务器功能和元数据 - tools/list -可用工具及其模式 - resources/list -可用资源 - prompts/list -可用提示

1. 报告生成：生成带有差异的Markdown报告，作为工件上传并显示在作业摘要中

比较什么

该操作查询 公共接口 比较两个服务器版本的响应：

差异在报告中显示为统一差异。常见的变化包括：

• 添加了新的工具、资源或提示
• 架构更改（新参数、更新的描述）
• 功能更改（启用新功能）
• 版本字符串更新

运输支持

stdio运输

默认传输使用JSON-RPC通过stdin/stdout与服务器通信。对于stdio，每种配置都会生成一个新的服务器进程：

- uses: SamMorrowDrums/mcp-server-diff@v2
  with:
    setup_node: true
    install_command: npm ci
    build_command: npm run build
    start_command: node dist/stdio.js

可流式HTTP传输

对于HTTP服务器，您通常希望 启动服务器一次 并针对它测试多种配置。使用 start_command 在配置级别，该操作生成服务器，等待启动，探测它，然后在配置完成后终止它：

configurations: |
  [{
    "name": "http-server",
    "transport": "streamable-http",
    "start_command": "node dist/http.js",
    "server_url": "http://localhost:3000/mcp",
    "startup_wait_ms": 2000
  }]

每个配置服务器生命周期：如果您的用例要求每个配置都有一个新的服务器实例（例如，测试不同的标志或环境变量），请包括 start_command 在每种配置中，每个配置都会启动和停止自己的服务器进程。

用于多种配置的共享服务器：如果您希望一个HTTP服务器处理多个测试配置，请使用 pre_test_command/post_test_command 在第一个/最后一个配置上，或在之前的工作流步骤中启动服务器：

configurations: |
  [
    {
      "name": "config-a",
      "transport": "streamable-http",
      "server_url": "http://localhost:3000/mcp",
      "pre_test_command": "node dist/http.js &",
      "pre_test_wait_ms": 2000
    },
    {
      "name": "config-b",
      "transport": "streamable-http",
      "server_url": "http://localhost:3000/mcp"
    },
    {
      "name": "config-c",
      "transport": "streamable-http",
      "server_url": "http://localhost:3000/mcp",
      "post_test_command": "pkill -f 'node dist/http.js' || true"
    }
  ]

预先部署的服务器：对于已经运行的服务器（暂存、生产），完全省略生命周期命令：

- uses: SamMorrowDrums/mcp-server-diff@v2
  with:
    install_command: 'true'
    transport: streamable-http
    server_url: https://mcp.example.com/api

版本比较策略

拉取请求

在拉取请求时，该操作会自动与目标分支的合并库进行比较。这确切地显示了PR带来的变化。

标签发布

当被标签推送匹配触发时 v*，该动作会找到前一个标签并与之进行比较：

on:
  push:
    tags: ['v*']

# v1.2.0 will automatically compare against v1.1.0

明确基线

指定要比较的任何git ref：

- uses: SamMorrowDrums/mcp-server-diff@v2
  with:
    setup_node: true
    install_command: npm ci
    build_command: npm run build
    start_command: node dist/stdio.js
    compare_ref: v1.0.0

变更失败（发布验证）

对于要确保没有API更改的发布工作流，请使用 fail_on_diff:

- uses: SamMorrowDrums/mcp-server-diff@v2
  with:
    setup_node: true
    install_command: npm ci
    build_command: npm run build
    start_command: node dist/stdio.js
    compare_ref: v1.0.0
    fail_on_diff: true  # Action fails if any API changes are detected

文物和报告

该操作产生：

1. 作业摘要：GitHub Actions UI中的内联Markdown报告，显示测试结果和差异
2. 人工制品: mcp-diff-report 工件包含 MCP_DIFF_REPORT.md 用于下载或进一步处理

输出示例

未检测到任何更改

当MCP服务器的公共接口在分支之间没有变化时：

📊 Comparison:
  Current: HEAD
  Compare: abc1234 (v1.0.0)

🧪 Running diff...

📊 Phase 3: Comparing results...
📋 Configuration stdio: ✅ No changes

✅ No API Changes - All configurations match the baseline.

检测到更改

当检测到更改时，该操作会显示语义差异，每个更改都有明确的路径：

📋 Configuration stdio: 3 change(s) found

生成的报告使用路径表示法准确显示了更改的内容：

--- base/tools.json
+++ branch/tools.json

+ tools[new_tool]: {"name": "new_tool", "description": "A newly added tool", ...}
- tools[old_tool].inputSchema.properties.name.description: "Old description"
+ tools[old_tool].inputSchema.properties.name.description: "Updated description"
- tools[calculator].inputSchema.properties.precision.type: "string"  
+ tools[calculator].inputSchema.properties.precision.type: "number"

--- base/resources.json
+++ branch/resources.json

+ resources[config://settings]: {"uri": "config://settings", "name": "Settings", ...}

每行显示：

• + 用于添加（新工具、资源或更改的值）
• - 用于删除（删除的项目或以前的值）
• 更改的完整路径： tools[tool_name].inputSchema.properties.param.type

这使得在不费力浏览整个JSON转储的情况下，很容易看到到底发生了什么变化

推荐工作流程

name: MCP Server Diff

on:
  workflow_dispatch:
  pull_request:
    branches: [main]
  push:
    branches: [main]
    tags: ['v*']

permissions:
  contents: read

jobs:
  mcp-diff:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: SamMorrowDrums/mcp-server-diff@v2
        with:
          setup_node: true
          install_command: npm ci
          build_command: npm run build
          configurations: |
            [
              {
                "name": "stdio",
                "transport": "stdio",
                "start_command": "node dist/stdio.js"
              },
              {
                "name": "streamable-http",
                "transport": "streamable-http",
                "start_command": "node dist/http.js",
                "server_url": "http://localhost:3000/mcp"
              }
            ]

故障排除

服务器无法启动

• 检查一下 start_command 在当地工作
• 增加 server_timeout 适用于启动速度较慢的服务器
• 验证所有依赖项是否已由安装 install_command

缺少基线

• 确保 fetch-depth: 0 在结账步骤中
• 对于新存储库，第一次运行可能会失败（不存在基线）

HTTP传输连接被拒绝

• 验证 server_url 匹配服务器的侦听地址
• 确保服务器绑定到 0.0.0.0 或 127.0.0.1，不仅 localhost 关于某些系统
• 如果在Docker中运行，请检查防火墙或容器网络

______________________________________________________________________

CLI工具

CLI允许您直接从终端区分任意两个MCP服务器，这对于本地开发、CI管道或比较不同实现中的服务器非常有用。

安装

# Run directly with npx (no install required)
npx mcp-server-diff --help

# Or install globally
npm install -g mcp-server-diff

基本用法

# 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标头和身份验证

对于经过身份验证的HTTP端点，传递带有 -H （目标）或 --base-header:

# 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"

配置文件

对于复杂的比较或多个目标，请使用配置文件：

npx mcp-server-diff -c servers.json -o diff

{
  "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选项参考

标题值模式：

• Bearer your-token --文字值
• Bearer env:VAR_NAME --从环境变量读取
• Bearer secret:name --提示“name”一次，如果多次使用则重用

______________________________________________________________________

许可证

MIT许可证。看 许可证 了解详情。

贡献

欢迎捐款。请阅读 贡献.md 作为指导方针。

相关资源

• 模型上下文协议规范
• MCP TypeScript SDK
• MCP Python SDK
• MCP Go SDK

示例配置

此操作在各种语言中的工作示例：

有关生产示例，请参见 .