books-word-converter

MCP server for massive PDF book conversion (150+ books, 10+ GB) to Word and Markdown.

Converts entire libraries locally through a free Model Context Protocol (MCP) server: no browser memory leaks, no tab crashes, < 80 MB RAM, automatic resume, scheduled ZIP bundles (every 15 books). All AI calls happen server-side — you never need a local Gemini API key.

Works from OpenCode, Claude Desktop, Cursor, Antigravity, Windsurf (any MCP client over stdio).

What it does

Related MCP server: MarkItDown MCP Server

Architecture

Your machine (MCP server + CLI)
  │  POST /api/convert-pdf  (base64 chunks, 2–4 pages)
  ▼
AI Studio converter (ai-studio server-side)
  │  Gemini OCR → Markdown (RTL, tables, verses)
  ▼
Local rebuild:  DOCX (docx)  +  .md  +  ZIP bundles (jszip)

• Health: GET /api/health → 200 {"status":"ok","mcpSupported":true,"cliSupported":true}

• CORS: Access-Control-Allow-Origin: * + OPTIONS → 204 (any external client).

• Retry: exponential backoff, small chunks (10 pages → 6 on QA failure).

Quick start

Prerequisites

• Node.js ≥ 20

• Free AI Studio account (server-side key — zero local keys needed)

Install (MCP host)

git clone https://github.com/abedmohamed258/books-word-converter.git
cd books-word-converter
npm install        # pdf-lib + docx + jszip

OpenCode

In ~/.config/opencode/opencode.json (V2):

{
  "mcp": {
    "servers": {
      "books-word-converter": {
        "type": "local",
        "command": ["node", "/absolute/path/to/books-word-converter/mcp-server.js"],
        "disabled": false
      }
    }
  }
}

Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "books-word-converter": {
      "command": "node",
      "args": ["/absolute/path/to/books-word-converter/mcp-server.js"],
      "env": {
        "CONVERTER_SERVER_URL": "https://ais-dev-wpsct27fdufcpry5x6ikjn-685461883733.europe-west2.run.app"
      }
    }
  }
}

CLI (no MCP client)

node batch-runner.js --input="D:/books" --output="D:/output" --bundle-size=15 \
  --server="https://ais-dev-wpsct27fdufcpry5x6ikjn-685461883733.europe-west2.run.app"

MCP tools are then available automatically: scan_books_directory, convert_book_to_word, batch_convert_folder, get_batch_status.

Server

/api/* bypass the AI-Studio cookie/iframe check; CORS is * with 204 preflight.

Quality notes

• Quranic verses are returned verbatim with tashkeel (﴿﴾) — no summarizing.

• Poetry, tables (| … |), and footnotes (١) preserved.

• QA gate (qa_gates.py in arabic-pdf-to-book): page ratio ≥ 85%, chars/page ≥ 250, short lines ≤ 28%, duplicates ≤ 15%, tables equal columns.

• Local OCR fallback (Tesseract) for large / quota-exhausted runs.

Security

• No secrets in repo or config — server key stays server-side.

• node_modules/ and batch_resume.json are git-ignored.

• The server logs to stderr only; stdout is JSON-RPC-only.

Troubleshooting

License

MIT — see LICENSE.