# books-word-converter

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Node](https://img.shields.io/badge/node-%3E%3D20-green.svg)](https://nodejs.org)
[![MCP](https://img.shields.io/badge/MCP-2024--11--05-blue.svg)](https://modelcontextprotocol.io)

**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

| Capability | Detail |
|---|---|
| `scan_books_directory` | Inventory a folder: file count, total size, per-file pages. |
| `convert_book_to_word` | PDF → `.docx` + `.md` with RTL Arabic layout (Amiri, verses ﴿﴾, poetry, tables). |
| `batch_convert_folder` | Sequential low-memory batch + TIMESTAMPED ZIP every N books + `batch_resume.json` state. |
| `get_batch_status` | Resume progress and bundle index. |
| CLI `batch-runner.js` | Same engine from terminal, no MCP client required. |

## 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)

```bash
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):

```json
{
  "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`)

```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)

```bash
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

| Endpoint | Method | Notes |
|---|---|---|
| `/api/health` | GET | `200` JSON, no cookie gate |
| `/api/convert-pdf` | POST | `{ pdfBase64, filename, options: { direction: "rtl" } }` → `{ success, data: { markdown } }` |
| `/api/cli/download/{mcp-server,batch-runner-js,mcpServer,cmd}` | GET | `302` → file (iframe gate) |

`/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`](https://github.com/abedmohamed258/SKILLS)): 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

| Symptom | Cause / Fix |
|---|---|
| `ERR_MODULE_NOT_FOUND pdf-lib` | Run `npm install` in the clone root (deps were not vendored in the download zip). |
| `Unexpected token '<' … not valid JSON` (CLI) | Old `302 __cookie_check.html` — the `/api/` cookie bypass was missing. Update to ≥ 1.1.0 / current `ais-dev` deployment. |
| `opencode mcp list` shows stale `failed` | `opencode reload` (config was edited after the last session). |
| `Connection closed` on MCP | Node < 20, or `package.json` missing `"type":"module"`. |

## License

MIT — see [LICENSE](LICENSE).