# 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

## 배포

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

# 패키지 설치
uv tool install .
```

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