Semamerge

SemaMerge

一个 MCP（Model Context Protocol）服务，可通过 AST 级分析检测 Git 分支之间的语义合并冲突。

当两个分支更改代码的方式导致 Git 可以顺利合并、但功能上却不兼容时，SemaMerge 会在合并破坏应用之前捕获问题。

可检测的冲突

冲突类型	示例
类型签名变更	分支 A 更改 getUser() 的返回类型，分支 B 调用 getUser().address
导出项被移除或重命名	分支 A 移除 export function validate()，分支 B 添加 import { validate }
参数变更	分支 A 为函数添加必需参数，分支 B 使用旧签名调用该函数
接口／契约破坏	分支 A 为接口添加必需字段，分支 B 实现该接口时未包含此字段
枚举／常量变更	分支 A 移除 Status.PENDING，分支 B 使用 Status.PENDING
导入路径变更	分支 A 移动文件，分支 B 从旧路径导入

安装

npx semamerge

或全局安装：

npm install -g semamerge

或克隆并从源代码构建：

git clone https://github.com/vineethwilson15/semamerge.git
cd semamerge
npm install
npm run build

MCP 工具

check_merge_safety

快速检查合并前的安全性。返回风险评分（安全／警告／危险）。

{
  "repoPath": "/path/to/repo",
  "sourceBranch": "feature-x",
  "targetBranch": "main"
}

analyze_branches

深入分析，并按文件列出所有语义冲突。

{
  "repoPath": "/path/to/repo",
  "branchA": "feature-x",
  "branchB": "feature-y",
  "baseBranch": "main"
}

list_semantic_changes

列出分支上的所有语义变更（函数、导出项、类型等）。

{
  "repoPath": "/path/to/repo",
  "branch": "feature-x",
  "baseBranch": "main"
}

analyze_file_pair

深入分析两个分支之间特定文件的语义差异。

{
  "repoPath": "/path/to/repo",
  "filePath": "src/utils.ts",
  "branchA": "feature-x",
  "branchB": "main"
}

配置

VS Code（Copilot）

在 VS Code 的 settings.json 中添加：

{
  "mcp": {
    "servers": {
      "semamerge": {
        "command": "node",
        "args": ["/path/to/semamerge/dist/index.js"]
      }
    }
  }
}

Claude Desktop

在 claude_desktop_config.json 中添加：

{
  "mcpServers": {
    "semamerge": {
      "command": "node",
      "args": ["/path/to/semamerge/dist/index.js"]
    }
  }
}

支持的语言

• TypeScript / JavaScript（.ts、.tsx、.js、.jsx、.mjs、.cjs）
• 计划支持 Python

工作原理

1. Git 层——使用 git show 读取分支中的文件内容，无需检出分支
2. AST 解析——使用 tree-sitter（WASM）将源代码解析为语法树
3. 语义提取——遍历 AST，提取函数签名、类型、导出项、导入项和枚举
4. 三方比较——计算从共同祖先到各分支的语义差异
5. 冲突检测——交叉比对变更，找出不兼容之处

开发

npm run build    # Compile TypeScript
npm run dev      # Watch mode
npm test         # Run tests

许可证

MIT