uni-diff-patch 0.0.3

MCP server and CLI tool for generating valid unified diff patches deterministically

uni-diff-patch

MCP server + CLI tool for generating valid unified diff patches deterministically.

LLM provides content or search/replace pairs, the tool computes correct diffs via mpatch (Rust) — no more broken hunks, no more git apply failures.

---

MCP 服务器 + CLI 工具，确定性生成合法的 unified diff patch。

LLM 只需提供文件内容或搜索替换对，工具通过 mpatch (Rust) 计算正确的 diff — 不再有坏掉的 hunk，git apply 不再失败。

Install / 安装

uv add uni-diff-patch     # as dependency / 作为依赖
uvx uni-diff-patch --help  # run directly / 直接运行

CLI / 命令行

# Generate patch from JSON spec / 从 JSON spec 生成 patch
uni-diff-patch generate --spec changes.json -o output.diff

# Generate with work_dir (for absolute paths) / 指定工作目录（用于绝对路径）
uni-diff-patch generate --spec changes.json --work-dir /path/to/project

# Validate a patch / 验证 patch
uni-diff-patch validate output.diff
uni-diff-patch validate output.diff --git-check --work-dir /path/to/repo

# Start MCP server / 启动 MCP 服务器
uni-diff-patch serve

MCP Configuration / MCP 配置

{
  "mcpServers": {
    "uni-diff-patch": {
      "command": "uvx",
      "args": ["uni-diff-patch", "serve"]
    }
  }
}

JSON Spec Format / JSON Spec 格式

All modes are specified in a changes array. Each change requires file_path and mode.

所有模式通过 changes 数组指定，每个变更需要 file_path 和 mode。

file_content — Full new content / 完整新内容

Tool reads original from disk and diffs. / 工具从磁盘读取原文件并生成 diff。

{
  "changes": [{
    "file_path": "src/main.py",
    "mode": "file_content",
    "new_content": "def main():\n    print('hello')\n"
  }]
}

search_replace — Targeted replacements / 精准替换（最省 token）

{
  "changes": [{
    "file_path": "src/main.py",
    "mode": "search_replace",
    "replacements": [
      {"search": "print('hello')", "replace": "print('world')"},
      {"search": "old_func()", "replace": "new_func()", "line_hint": 42}
    ]
  }]
}

line_hint: approximate line number for disambiguation when search matches multiple locations.

line_hint：当 search 匹配多处时，用大致行号消歧（选最近的匹配）。

create_file — New file / 新建文件

{
  "changes": [{
    "file_path": "src/new_module.py",
    "mode": "create_file",
    "new_content": "# New module\ndef init():\n    pass\n"
  }]
}

delete_file — Remove file / 删除文件

{
  "changes": [{
    "file_path": "src/deprecated.py",
    "mode": "delete_file"
  }]
}

text_pair — Both old and new text / 直接传入新旧文本（不读磁盘）

{
  "changes": [{
    "file_path": "virtual/path.py",
    "mode": "text_pair",
    "old_text": "x = 1\n",
    "new_text": "x = 2\n"
  }]
}

rename_file — Rename/move / 重命名/移动文件

Optionally with content change. / 可同时修改内容。

{
  "changes": [{
    "file_path": "src/old_name.py",
    "mode": "rename_file",
    "new_path": "src/new_name.py",
    "new_content": "# Optional modified content\n"
  }]
}

chmod — Permission change / 权限变更

Optionally with content change. / 可同时修改内容。

{
  "changes": [{
    "file_path": "scripts/deploy.sh",
    "mode": "chmod",
    "old_mode": "100644",
    "new_mode": "100755"
  }]
}

Multi-file patch / 多文件合并 patch

{
  "changes": [
    {"file_path": "src/a.py", "mode": "file_content", "new_content": "..."},
    {"file_path": "src/b.py", "mode": "search_replace", "replacements": [{"search": "old", "replace": "new"}]},
    {"file_path": "src/c.py", "mode": "create_file", "new_content": "..."}
  ],
  "output_path": "changes.diff"
}

Optional Fields / 可选字段

Field / 字段	Default / 默认值	Description / 说明
encoding	"utf-8"	File encoding for disk-read modes / 磁盘读取模式的文件编码
context_lines	3	Context lines in diff / diff 中的上下文行数
output_path	—	Top-level, writes patch to file / 顶层字段，将 patch 写入文件

Development / 开发

uv sync
uv run pytest tests/ -v