# 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의 외부 스크립트 메커니즘만 활용.

## 파일 구조

```
src/pdf2zh_next_mcp/
├── __init__.py
├── main.py              # MCP 서버 (extract_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에서 세그먼트 순서 보장 + 파일 동시 쓰기 방지
- **`--debug`**: Pass 1에서 수식 힌트 추출용. translate_tracking.json 생성 후 정리
- **`shlex.quote()`**: CLI 커맨드 경로에 공백/백슬래시가 있어도 안전하게 처리

## 번역 모드

| | basic | visual |
|---|---|---|
| PDF 첨부 | 불필요 | 필요 (드래그앤드롭) |
| 차이점 | 텍스트만 | 그림/표/수식 시각 참조 가능 |
| 용어집 저장 | 안 함 | `{stem}-glossary.json` 저장 |
| 공통 | 전체 읽기 → 용어 파악 → 일관된 번역, 수식 힌트 포함 |

## 수식 힌트

`--debug`로 생성된 `~/.cache/babeldoc/working/{stem}/translate_tracking.json`에서
`{v0}` → 실제 수식 유니코드 매핑을 추출하여 instruction에 포함.
두 모드 모두 적용.

## 바이너리 탐색

`_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` (별도 설치)
