AI导哈

MCP模式兼容性检查工具

一个用于比较MCP服务器模式变更并分类为BREAKING、WARN或SAFE的工具，帮助开发者在部署前识别潜在的破坏性变更。

  • by 0-co
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 0-co/mcp-compat

使用说明

mcp compat

在部署之前，要知道您是否正在破坏MCP用户。

mcp-compat 比较两个MCP服务器模式（之前/之后），并将每个更改分类为BREAKING、WARN或SAFE。把你的部署放在上面。

mcp-compat: schema compatibility report

  2 BREAKING changes, 1 SAFE change

  BREAKING  get_weather  Parameter 'units' type changed: string → integer
  BREAKING  list_items   Required parameter 'limit' removed
  SAFE      create_item  New optional parameter 'tags' added

  Run with --ci to fail CI on breaking changes

安装

pip install mcp-compat

没有外部依赖关系。Python 3.9+。

快速开始

# Compare two local schema files
mcp-compat before.json after.json

# Fail CI on breaking changes
mcp-compat before.json after.json --ci

# JSON output for scripting
mcp-compat before.json after.json --json

# Compare remote schemas
mcp-compat https://example.com/schema-v1.json https://example.com/schema-v2.json

输入是MCP工具对象的JSON数组（格式与 agent-friend grade):

[
  {
    "name": "get_weather",
    "description": "Get current weather",
    "inputSchema": {
      "type": "object",
      "properties": {
        "city": {"type": "string", "description": "City name"},
        "units": {"type": "string", "description": "Units", "default": "celsius"}
      },
      "required": ["city"]
    }
  }
]

更改分类

更改 严重性 原因
工具已删除 中断 所有调用者立即中断
删除必需参数 BREAKING 传递该参数的调用者遇到意外行为
添加了新的必需参数 BREAKING 省略该参数的调用者将收到错误
参数类型已更改 BREAKING 发送旧类型的调用者被拒绝
必需参数变为可选 BREAKING 删除调用者依赖的验证保证
可选参数变为必需 BREAKING 省略它的调用者现在失败
已删除可选参数 WARN 传递该参数的调用者可能会出现意外行为
工具已添加 SAFE 可添加，现有调用者不受影响
添加了新的可选参数 SAFE 现有调用者不受影响
描述已更改 SAFE 无功能影响
默认值已更改 SAFE 依赖旧默认值的调用者可能会看到行为更改（在敏感上下文中视为警告）

CI集成

添加到GitHub操作工作流：

- name: Check MCP schema compatibility
  run: |
    pip install mcp-compat
    mcp-compat schema-before.json schema-after.json --ci

或者在部署之前使用捕获模式 mcp-diff （来自同一生态系统）：

# Save current schema snapshot with mcp-diff
pip install mcp-diff
mcp-diff snapshot my-server.json

# After updating, compare and gate
mcp-compat schema-before.json schema-after.json --ci

JSON输出

mcp-compat before.json after.json --json

{
  "breaking_count": 1,
  "warn_count": 0,
  "safe_count": 2,
  "changes": [
    {
      "severity": "BREAKING",
      "tool": "get_weather",
      "message": "Parameter 'units' type changed: string → integer"
    },
    {
      "severity": "SAFE",
      "tool": "get_weather",
      "message": "New optional parameter 'format' added"
    }
  ]
}

MCP开发人员生命周期的一部分

agent-friend   lint schemas before publishing
mcp-patch      security audit (prompt injection, over-permission)
mcp-pytest     test tool behavior end-to-end
mcp-snoop      debug stdio traffic in real time
mcp-diff       detect schema changes between versions
mcp-compat     classify breaking changes  ← you are here

一切都在PyPI上。全部开源。所有外部依赖项均为零。

许可证

麻省理工学院

相关 MCP