pdf2zh-next-mcp: Instructions file for Claude Code

pdf2zh-next-mcp

PDF 번역 MCP 서버. pdf2zh-next(BabelDOC)의 CLITranslator를 활용한 2-pass 아키텍처.

아키텍처

LLM (Claude Desktop / Claude Code)
  │
  ├─ extract_segments 호출
  │     └─ Pass 1: pdf2zh_next --clitranslator → collect.py가 세그먼트 수집
  │     └─ 세그먼트 JSON + 번역 instruction 반환
  │
  ├─ LLM이 전체 세그먼트를 한 번에 번역 (컨텍스트 유지)
  │
  └─ assemble_translated 호출
        └─ Pass 2: pdf2zh_next --clitranslator → lookup.py가 번역 주입
        └─ mono/dual PDF 생성

핵심: pdf2zh-next 코드를 수정하지 않고 CLITranslator의 외부 스크립트 메커니즘만 활용.

세션 디렉토리: 출력 디렉토리(또는 PDF 부모 디렉토리)에 pdf2zh-sessions-{session_id}/ 생성. 완료 후 자동 삭제.

파일 구조

src/pdf2zh_next_mcp/
├── __init__.py
├── main.py              # MCP 서버 (extract_segments + save_translated_segments + assemble_translated)
└── scripts/
    ├── collect.py        # Pass 1: stdin → segments.json에 누적, stdout → 원문 반환
    └── lookup.py         # Pass 2: stdin → translations.json에서 조회, stdout → 번역문 반환

주요 설계 결정

• CLI 호출: pdf2zh-next는 내부적으로 subprocess isolation 사용. 라이브러리 임포트 대신 CLI가 더 깔끔
• --ignore-cache: 두 패스 모두. Pass 1은 세그먼트 빠짐없이 수집, Pass 2는 사전 번역 강제 사용
• --pool-max-workers 1: Pass 1에서 세그먼트 순서 보장 + 파일 동시 쓰기 방지
• shlex.quote(): CLI 커맨드 경로에 공백/백슬래시가 있어도 안전하게 처리
• --debug 미사용: --debug는 수식 힌트(translate_tracking.json)를 제공하지만 ~20배 속도 저하 유발 (3.5MB PDF → 571MB 디버그 출력). 수식 플레이스홀더는 대부분 참조번호라 힌트 없이도 번역 품질 차이 미미.

바이너리 탐색

_find_pdf2zh_binary() / _find_python_binary():

1. uv tool 설치 경로 (macOS/Linux: ~/.local/share/uv/tools/, Windows: %APPDATA%\uv\data\tools\)
2. shutil.which() fallback

배포

# 개발 모드
uv run python src/pdf2zh_next_mcp/main.py

# 패키지 설치
uv tool install .

필수 전제: uv tool install pdf2zh-next (별도 설치)