日语教材数字化与MCP服务

benkyou

A Japanese textbook digitizer and MCP server. Converts physical textbook PDFs into structured Markdown lesson files, then exposes them to AI assistants (e.g. Claude Desktop) via the Model Context Protocol (MCP).

PDF → indexer/ (VLM OCR) → data/ (Markdown lessons) → MCP Server → Claude Desktop

Disclaimer: This project is mostly vibe-coded for personal use and still has plenty of rough edges. If you run into friction or have ideas for improving the experience, feel free to open an issue — feedback is welcome.

Prerequisites

• Python 3.12+
• uv — fast Python package manager
• OpenAI API key — required for the indexer only (not needed to run the MCP server if lesson data already exists)

Environment Setup

# Clone the repository
git clone <repo-url>
cd benkyou

# Install all dependencies
uv sync

Set your OpenAI API key before running the indexer:

export OPENAI_API_KEY=sk-...

Run the test suite:

uv run pytest tests/

Indexer: PDF → Markdown

The indexer is a one-time processing script with two sequential steps. Both are invoked through indexer/run.py.

Step 1 — Extract TOC

Renders all PDF pages to PNGs, sends the TOC pages to a vision model, and writes a toc.json file.

python indexer/run.py \
  --pdf inbox/book.pdf \
  --volume elementary-vol1 \
  --type textbook \
  --step toc \
  --toc-pages 3-5

After this completes, manually open data/<volume>/<type>/toc.json and set toc_confirmed to true before proceeding:

{
  "toc_confirmed": true,
  ...
}

Step 2 — Extract Lessons

Reads the confirmed TOC, then sends each lesson's page images to the VLM in parallel to produce structured Markdown lesson files.

python indexer/run.py \
  --pdf inbox/book.pdf \
  --volume elementary-vol1 \
  --type textbook \
  --step index
  --page-base 7 # number of pages before logical page 1 (e.g. cover, TOC pages); aligns PDF page numbers with the page numbers printed in the book

Repeat both steps with --type workbook for the workbook volume.

CLI Reference

Data Output Layout

data/
  manifest.json                  # Index of all processed volumes
  <volume>/
    <type>/
      _pages/                    # PNG renders of PDF pages (gitignore-able)
      toc.json                   # Human-confirmed TOC
      lesson_01.md               # Per-lesson Markdown with YAML frontmatter
      lesson_02.md
      ...

Demo

Browse a lesson — ask Claude to walk you through the lesson content, vocabulary, and grammar points:

Practice with workbook exercises — ask Claude to run through the workbook questions interactively:

Inline dictionary lookup — agent can look up any Japanese word on the spot via a bundled offline JMDict dictionary, so you never have to leave the conversation to check a word.

MCP Server

The MCP server exposes lesson data, dictionary lookup, and workflow-flow tools to any MCP-compatible client (Claude Desktop, Codex Desktop, Zed, Cursor, etc.) over stdio transport.

Starting the Server

# Default (looks for data/ in the current working directory)
uv run python -m mcp_server.server

# Recommended: use an absolute path to the data directory
uv run python -m mcp_server.server --data-dir /absolute/path/to/benkyou/data

Configuring Claude Desktop

Add the following to your Claude Desktop config file:

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

{
  "mcpServers": {
    "benkyou": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/benkyou",
        "run",
        "python",
        "-m",
        "mcp_server.server",
        "--data-dir",
        "/absolute/path/to/benkyou/data"
      ]
    }
  }
}

Replace /absolute/path/to/benkyou with your actual clone path. Restart Claude Desktop after saving.

For MCP clients other than Claude Desktop, see docs/mcp-clients.md.

Tool Reference

The MCP server exposes 8 tools and 2 prompts. See docs/api.md for full parameter documentation and examples.

Prompts (browse_lesson, practice_lesson): for clients that support MCP prompts as slash commands (e.g. Zed). Take volume and lesson supplied by the user — no discovery step needed.