diffchunk

LLM이 대규모 diff 파일을 효율적으로 탐색할 수 있게 해주는 MCP 서버입니다. 전체 diff를 순차적으로 읽는 대신, LLM은 패턴 기반 탐색을 사용하여 관련 변경 사항으로 직접 이동할 수 있습니다.

문제점

대규모 diff는 LLM 컨텍스트 제한을 초과하며 관련 없는 변경 사항에 토큰을 낭비하게 합니다. 5만 줄 이상의 diff는 직접 처리할 수 없으며, 수동으로 분할하면 파일 간의 관계를 잃게 됩니다.

해결책

5가지 탐색 도구를 갖춘 MCP 서버:

• load_diff - 사용자 지정 설정으로 diff 파일 파싱 (선택 사항)

• list_chunks - 파일 매핑 및 파일별 줄 수를 포함한 청크 개요 표시 (자동 로드)

• get_chunk - 특정 청크 내용 검색 (자동 로드)

• find_chunks_for_files - 파일 패턴으로 청크 위치 찾기 (자동 로드)

• get_file_diff - 단일 파일에 대한 전체 diff 추출 (자동 로드)

설정

전제 조건: uvx 명령을 제공하는 uv(매우 빠른 Python 패키지 관리자)를 설치하세요.

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 사용 - file_details를 통한 파일별 줄 수를 포함하여 diff 구조와 전체 범위를 파악

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
)

형식 옵션

LLM 소비를 위해 출력을 변환하려면 get_chunk에서 format 매개변수를 사용하세요:

# 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를 사용하세요:

# 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)

• Unified diff 형식 (diff -u)

• 단일 diff 내 여러 파일

• 바이너리 파일 변경 표시기

성능

• 10만 줄 이상의 diff를 효율적으로 처리

• 메모리 효율적인 스트리밍

• 파일 변경 시 자동 재로드

문서

• 설계 - 아키텍처 및 구현 세부 정보

• 기여 - 기여 가이드라인 및 개발 설정

라이선스

MIT