Metadata-Version: 2.4
Name: pdf2zh-next-mcp
Version: 0.1.1
Summary: MCP server for PDF translation via pdf2zh-next with full-context LLM translation
Project-URL: Homepage, https://github.com/JaeHyeon-KAIST/pdf2zh-next-mcp
Project-URL: Repository, https://github.com/JaeHyeon-KAIST/pdf2zh-next-mcp
Project-URL: Issues, https://github.com/JaeHyeon-KAIST/pdf2zh-next-mcp/issues
Author-email: JaeHyeon <alvinlog@kaist.ac.kr>
License-Expression: MIT
License-File: LICENSE
Keywords: babeldoc,llm,mcp,pdf,pdf2zh,translation
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Text Processing :: Linguistic
Requires-Python: >=3.12
Requires-Dist: mcp[cli]>=1.0.0
Description-Content-Type: text/markdown

# pdf2zh-next-mcp

[![PyPI](https://img.shields.io/pypi/v/pdf2zh-next-mcp)](https://pypi.org/project/pdf2zh-next-mcp/)
[![License](https://img.shields.io/pypi/l/pdf2zh-next-mcp)](LICENSE)

MCP server for PDF translation using [pdf2zh-next](https://github.com/funstory-ai/BabelDOC) as the PDF processing backend.

Instead of translating each segment independently (which loses context), this server extracts all segments at once and lets the LLM translate them together — preserving terminology consistency and context across the entire document.

## How it works

```
┌─────────────────────────────────────────────────┐
│  MCP Client (Claude Desktop, Claude Code, etc.) │
│                                                  │
│  1. extract_segments  ──→  segments + formulas   │
│  2. LLM translates all segments at once          │
│  3. assemble_translated  ──→  final PDF          │
└─────────────────────────────────────────────────┘
```

The LLM sees every segment before translating — so terminology stays consistent, cross-page sentences flow naturally, and formula placeholders are preserved correctly.

## Prerequisites

[pdf2zh-next](https://github.com/funstory-ai/BabelDOC) must be installed separately:

```bash
uv tool install pdf2zh-next
```

Verify installation:

```bash
pdf2zh_next --version
```

> You need [uv](https://docs.astral.sh/uv/) to install both pdf2zh-next and this server.

## Installation

### From PyPI (recommended)

```bash
uv tool install pdf2zh-next-mcp
```

### From GitHub

```bash
uv tool install git+https://github.com/JaeHyeon-KAIST/pdf2zh-next-mcp
```

### From source

```bash
git clone https://github.com/JaeHyeon-KAIST/pdf2zh-next-mcp
cd pdf2zh-next-mcp
uv sync
```

## Setup

### Claude Code

```bash
claude mcp add pdf-translate -- pdf2zh-next-mcp
```

### Claude Desktop

Add to your Claude Desktop MCP config:

- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`

**If installed from PyPI or GitHub:**

```json
{
  "mcpServers": {
    "pdf-translate": {
      "command": "uvx",
      "args": ["pdf2zh-next-mcp"]
    }
  }
}
```

**If running from source:**

```json
{
  "mcpServers": {
    "pdf-translate": {
      "command": "uv",
      "args": [
        "run",
        "--directory", "/path/to/pdf2zh-next-mcp",
        "python", "-m", "pdf2zh_next_mcp.main"
      ]
    }
  }
}
```

> **Tip:** If Claude Desktop can't find `uvx`, use the absolute path (e.g., `/opt/homebrew/bin/uvx` on macOS, `C:\Users\you\.local\bin\uvx.exe` on Windows).

## Usage

### Basic mode (default)

Text-only translation. The LLM reads all segments first, identifies key terms, then translates with consistent terminology.

Just ask:

> "Translate this PDF to Korean: /path/to/paper.pdf"

Behind the scenes:
1. `extract_segments` analyzes the PDF layout and returns all text segments
2. The LLM translates everything at once (with full context)
3. `assemble_translated` injects translations and generates the final PDF

### Visual mode

Uses the attached PDF for visual context — the LLM can see figures, tables, and formulas. Also saves a terminology glossary.

1. **Attach the PDF to the chat** (drag-and-drop)
2. Ask: "Translate this PDF to Korean in visual mode"
3. The LLM creates a glossary, references the visuals, and translates all segments

Visual mode outputs:
- `*-mono.pdf` — translated PDF
- `*-dual.pdf` — bilingual side-by-side
- `*-glossary.json` — terminology glossary

## Troubleshooting

### `BabeldocError: cannot unpack non-iterable NoneType object`

BabelDOC needs CMap files for font character mapping. If its automatic download times out, install them manually:

```bash
cd ~/Downloads
curl -L https://github.com/funstory-ai/BabelDOC-Assets/archive/refs/heads/main.zip -o BabelDOC-Assets.zip
unzip BabelDOC-Assets.zip
mkdir -p ~/.cache/babeldoc/cmap
cp BabelDOC-Assets-main/cmap/*.json ~/.cache/babeldoc/cmap/
```

This is a one-time setup. The cache path is the same on all platforms.

## License

MIT
