diffchunk

MCP 服务器，使 LLM 能够高效地导航大型 diff 文件。LLM 无需按顺序读取整个 diff，而是可以使用基于模式的导航直接跳转到相关更改。

问题

大型 diff 超出了 LLM 的上下文限制，并在无关更改上浪费了 token。超过 5 万行的 diff 无法直接处理，而手动拆分会丢失文件之间的关联。

解决方案

MCP 服务器，包含 5 个导航工具：

• load_diff - 使用自定义设置解析 diff 文件（可选）

• list_chunks - 显示包含文件映射和每个文件行数的块概览（自动加载）

• get_chunk - 获取特定块的内容（自动加载）

• find_chunks_for_files - 通过文件模式定位块（自动加载）

• get_file_diff - 提取单个文件的完整 diff（自动加载）

设置

前提条件： 安装 uv（一种极快的 Python 包管理器），它提供了 uvx 命令。

添加到您的 MCP 客户端配置中：

{
  "mcpServers": {
    "diffchunk": {
      "command": "uvx",
      "args": ["--from", "diffchunk", "diffchunk-mcp"]
    }
  }
}

使用方法

您的 AI 助手现在可以处理以前在 Cline、Roocode、Cursor 和其他工具中导致失败的大型变更集。

与 AI 助手配合使用

配置完成后，您的 AI 助手可以使用 diffchunk 分析大型提交、分支或 diff。

以下是一些示例用例：

分支比较：

• “检查 develop 分支中不在 main 分支中的所有更改，查找是否有错误”

• “告诉我所有我尚未合并的更改”

• “staging 分支中添加了哪些新功能？”

• “总结过去 2 周内此仓库的所有更改”

代码审查：

• “使用 diffchunk 检查我的功能分支是否存在安全漏洞”

• “使用 diffchunk 在我合并到生产环境之前查找任何破坏性更改”

• “使用 diffchunk 审查这次大型重构以发现潜在问题”

更改分析：

• “使用 diffchunk 向我展示所有需要运行的数据库迁移”

• “使用 diffchunk 查找哪些 API 更改可能会影响我们的移动应用”

• “使用 diffchunk 分析最近添加的所有新依赖项”

直接文件分析：

• “使用 diffchunk 分析 /tmp/changes.diff 处的 diff 并查找任何错误”

• “创建我未提交更改的 diff 并进行审查”

• “将我的本地分支与 origin 进行比较并突出显示冲突”

提示：AI 助手规则

添加到您的 AI 助手自定义指令中以实现自动使用：

When reviewing large changesets or git commits, use diffchunk to handle large diff files.
Create temporary diff files and tracking files as needed and clean up after analysis.

工作原理

当您要求 AI 助手分析更改时，它会策略性地使用 diffchunk 的工具：

1. 创建 diff 文件（例如 git diff main..develop > /tmp/changes.diff），基于您的问题

2. 使用 list_chunks 获取 diff 结构和总范围的概览，包括通过 file_details 获取的每个文件行数

3. 使用 find_chunks_for_files 在您询问特定文件类型时定位相关部分

4. 使用 get_file_diff 获取特定文件的完整 diff，而无需加载整个块

5. 使用 get_chunk 检查特定部分，而无需将整个 diff 加载到上下文中

6. 系统地跟踪进度，通过大型变更集，逐块进行分析

7. 清理临时文件，在完成分析后

这使您的 AI 助手能够处理通常会导致其他工具崩溃的大型 diff，同时提供彻底的分析而不会丢失上下文。

工具使用模式

先概览：

list_chunks("/tmp/changes.diff")
# -> 5 chunks across 12 files, 3,847 total lines, ~15,420 tokens
# Each chunk includes token_count and file_details with per-file line counts
# Response includes total_token_count for context-budget planning

针对特定文件：

find_chunks_for_files("/tmp/changes.diff", "*.py")
# → [1, 3, 5] - Python file chunks

get_chunk("/tmp/changes.diff", 1)
# → Content of first Python chunk

单文件 diff：

get_file_diff("/tmp/changes.diff", "src/main.py")
# → Complete diff for src/main.py (header + all hunks)

# Glob patterns work when they match exactly one file
get_file_diff("/tmp/changes.diff", "*.config")
# → Complete diff for the single matching config file

系统分析：

# Process each chunk in sequence
get_chunk("/tmp/changes.diff", 1)
get_chunk("/tmp/changes.diff", 2)
# ... continue through all chunks

配置

路径要求

• 仅限绝对路径：/home/user/project/changes.diff

• 跨平台：Windows (C:\path) 和 Unix (/path)

• 主目录扩展：~/project/changes.diff

自动加载默认值

工具使用优化设置自动加载：

• max_chunk_lines: 1000

• skip_trivial: true (仅空格)

• skip_generated: true (锁文件、构建产物)

自定义设置

使用 load_diff 进行非默认行为：

load_diff(
    "/tmp/large.diff",
    max_chunk_lines=2000,
    include_patterns="*.py,*.js",
    exclude_patterns="*test*",
    context_lines=2
)

格式选项

在 get_chunk 上使用 format 参数来转换输出以供 LLM 使用：

# Default - raw diff output
get_chunk("/tmp/changes.diff", 1, format="raw")

# Annotated - structured with line numbers, file headers, hunk separation
get_chunk("/tmp/changes.diff", 1, format="annotated")

# Compact - token-efficient, only new hunks (context + added lines)
get_chunk("/tmp/changes.diff", 1, format="compact")

Annotated 格式 添加 ## File: 标题，带有新文件行号的 __new hunk__/__old hunk__ 部分，以及来自 @@ 标题的函数上下文。

Compact 格式 仅显示添加或保留的内容，完全省略删除的行和 __old hunk__ 部分。当您只需要查看最终状态时非常有用。

上下文缩减

在 load_diff 上使用 context_lines 以在加载时减少每个 hunk 的上下文行数：

# Keep only 2 lines of context around each change
load_diff("/tmp/large.diff", context_lines=2)

# Keep only changes, no context
load_diff("/tmp/large.diff", context_lines=0)

这与 format 结合使用 - 上下文在加载时减少，然后在显示时应用格式。

支持的格式

• Git diff 输出 (git diff, git show)

• 统一 diff 格式 (diff -u)

• 单个 diff 中的多个文件

• 二进制文件更改指示器

性能

• 高效处理 10 万行以上的 diff

• 内存高效流式传输

• 文件更改时自动重新加载

文档

• 设计 - 架构和实现细节

• 贡献 - 贡献指南和开发设置

许可证

MIT