reaatech/mcp-schema-evolution

# mcp-schema-evolution [](https://github.com/reaatech/mcp-schema-evolution/actions/workflows/ci.yml) [](LICENSE) [](https://www.typescriptlang.org/) 将Protocol Buffers风格的演化规则引入MCP工具模式。比较不同版本间的`Tool[]`快照，将每个变更分类为破坏性或非破坏性，并在CI中强制执行演化策略——防止您的消费者代码中断。 ## 功能 - **模式比对** — 比较两个`Tool[]`快照，检测新增、删除、更改和重命名的字段，支持递归嵌套模式 - **变更分类** — 每个变更都被分类为`breaking`（破坏性）、`non-breaking`（非破坏性）或`patch`（补丁），并附带严重程度和迁移指导 - **字段重命名检测** — 基于启发式方法的相似性评分，支持可配置的置信度阈值 - **CI验证** — 在CI中验证快照；对于未确认的破坏性变更将失败，使用管道分隔的确认文件 - **PR报告** — 为Pull Request评论生成格式化的Markdown报告 - **CLI** — 单个`mcp-evolution diff`命令，支持人类可读和JSON输出模式 - **基于Result的错误处理** — 所有公共API均返回`Result`（永不抛出异常） ## 安装 ### 使用软件包 软件包发布在`@reaatech`作用域下，可以单独安装： ``` # 核心库 — diffing, classification, rename detection pnpm add @reaatech/mcp-schema-evolution # CLI — 从命令行进行快照 diff pnpm add @reaatech/mcp-schema-evolution-cli # CI 集成 — 在 pull requests 中验证快照 pnpm add -D @reaatech/mcp-schema-evolution-ci ``` ## 快速开始 ### 库 API ``` import { diffToolSnapshots, loadToolsFromFile } from "@reaatech/mcp-schema-evolution"; const v1 = loadToolsFromFile("snapshots/v1.json"); const v2 = loadToolsFromFile("snapshots/v2.json"); if (v1.ok && v2.ok) { const result = diffToolSnapshots(v1.value, v2.value); if (result.ok) { const breaking = result.value.filter((c) => c.type === "breaking"); const nonBreaking = result.value.filter((c) => c.type === "non-breaking"); console.log( `${result.value.length} changes: ${breaking.length} breaking, ${nonBreaking.length} non-breaking` ); for (const change of result.value) { console.log(`[${change.severity}] ${change.toolName}: ${change.description}`); if (change.migration) { console.log(` → ${change.migration.suggestion}`); } } } } ``` ### CLI ``` mcp-evolution diff tools.v1.json tools.v2.json mcp-evolution diff tools.v1.json tools.v2.json --json ``` ### CI 验证 ``` npx mcp-evolution-ci --base snapshots/base.json --head snapshots/head.json --format github-markdown ``` ``` import { validateSnapshot, formatReport } from "@reaatech/mcp-schema-evolution-ci"; const result = validateSnapshot({ baseSnapshot: "snapshots/base.json", headSnapshot: "snapshots/head.json", policy: { failOnBreaking: true, acknowledgmentFile: ".schema-breaking-allowed" }, }); if (!result.ok) { console.log(formatReport(result, { format: "github-markdown" })); process.exit(1); } ``` ## 软件包 | 软件包 | 描述 | | :--- | :--- | | [`@reaatech/mcp-schema-evolution`](./packages/core) | 模式比对、变更分类、字段重命名检测 | | [`@reaatech/mcp-schema-evolution-cli`](./packages/cli) | `mcp-evolution` 命令行接口 | | [`@reaatech/mcp-schema-evolution-ci`](./packages/ci) | 基于确认的策略执行的CI验证 | ## 变更分类参考 | 变更 | 分类 | 严重程度 | | :--- | :--- | :--- | | 移除一个工具 | `breaking` | `high` | | 移除一个必填字段 | `breaking` | `high` | | 添加一个必填字段（无默认值） | `breaking` | `high` | | 重命名一个字段（未使用包装器） | `breaking` | `high` | | 缩小类型范围（`string` → `integer`） | `breaking` | `high` | | 收紧约束（`minLength` 增加） | `breaking` | `high` | | 移除枚举值 | `breaking` | `high` | | 字段变为必填 | `breaking` | `high` | | 添加一个可选字段 | `non-breaking` | `medium` | | 添加一个带默认值的字段 | `non-breaking` | `medium` | | 扩大类型范围（`integer` → `number`） | `non-breaking` | `medium` | | 添加枚举值 | `non-breaking` | `medium` | | 放宽约束 | `non-breaking` | `medium` | | 添加一个新工具 | `non-breaking` | `low` | | 弃用一个字段 | `non-breaking` | `medium` | | 仅文档变更 | `patch` | `low` | | 默认值变更 | `patch` | `low` | ## 确认破坏性变更 当破坏性变更是有意为之，请创建一个 `.schema-breaking-allowed` 文件： ``` # 格式：TOOL_NAME|CHANGE_CATEGORY|DESCRIPTION search|field_removed|Removed deprecated "query" param — replaced by "q" in v1.2.0 *|field_added|New required "trace_id" field added for observability ``` 以 `#` 开头的行将被忽略。使用 `*` 作为通配符来匹配任何工具或类别。 ## 文档 - [ARCHITECTURE.md](./ARCHITECTURE.md) — 系统设计、包关系和数据流 - [AGENTS.md](./AGENTS.md) — AI 代理的编码规范和开发指南 - [CONTRIBUTING.md](./CONTRIBUTING.md) — 贡献流程和发布流程 - [DEV_PLAN.md](./DEV_PLAN.md) — 开发路线图和计划功能 ## 许可证 [MIT](LICENSE) © [reaatech](https://github.com/reaatech)

标签：API 设计, CI/CD 集成, CLI 工具, Java RMI, MCP 工具模式, MITM代理, Protobuf, PR 报告, TypeScript, 向后兼容, 向后兼容性, 字段重命名检测, 安全可观测性, 安全插件, 工具模式管理, 差异分析, 弃用管理, 数据管道, 更改日志生成, 模式比较, 模式演进, 模式验证, 版本控制, 破坏性变更检测, 自动化攻击, 软件工程