# 🦉 Super MCP OCR for DeepSeek (teks-only LLM) [![M8ven Score](https://m8ven.ai/badge/mcp/slamsmart-super-mcp-ocr-deepseek-e9tfry)](https://m8ven.ai/mcp/slamsmart-super-mcp-ocr-deepseek-e9tfry)

Memberi **"mata"** ke model AI yang tidak punya vision (mis. **DeepSeek v4 Flash**, DeepSeek R1, atau LLM teks-only lain) — semua gambar & dokumen dibaca jadi **teks murni** yang bisa langsung dianalisa.

```
Gambar / PDF / Word / Excel / PPT
        │
        ▼
   [ MCP OCR Server ]  ──►  teks murni  ──►  LLM bisa baca & jawab
```

---

## ✨ Fitur

| Format | Cara baca |
|---|---|
| 🖼️ Gambar — png, jpg/jpeg, webp, bmp, gif, tif/tiff | OCR (RapidOCR + pre-process) |
| 📄 PDF | teks asli diekstrak; halaman **scan otomatis di-OCR** per halaman (max 25 hal) |
| 📝 Office — docx, xlsx/xlsm, pptx, rtf | ekstrak paragraf, tabel, slide |
| 📃 Teks — txt, md, csv, json, xml, log, yaml, toml, html | baca langsung |

**Tidak didukung:** `.doc` / `.xls` versi lama → simpan ulang sebagai `.docx` / `.xlsx`.

**Tool yang tersedia:**
- `read_document(file_path, mode, enhance)` — nama penuh (teks)
- `ocr_image(image_path, mode, enhance)` — alias kompatibel (teks)
- `read_colors(file_path, top_n=8, merge=true)` — 🎨 **ekstrak warna dominan dari gambar**
- `ocr.sh` — 🐧 CLI OCR tanpa Python (tesseract + poppler), buat mesin/sandbox tanpa env Python

---

## 🎨 Baca Warna dari Gambar (`read_colors`)

Model teks-only juga **tidak bisa melihat warna**. `read_colors` terjemahkan warna gambar jadi teks berstruktur — hex, rgb, nama, shade, persentase area, dan posisi region. Cocok buat: copy-paste screenshot halaman web, mau ganti warna desain, cari nilai hex yang dipakai.

```
read_colors(file_path="web-design.png")
read_colors(file_path="ui.png", top_n=12)        # lebih banyak warna
read_colors(file_path="ui.png", merge=false)     # tanpa gabung shade dekat
```

| Param | Nilai | Fungsi |
|---|---|---|
| `file_path` | path gambar lokal / URL | wajib |
| `top_n` | `8` (default) | jumlah warna teratas |
| `merge` | `true` (default) | gabung warna nyaris-sama (<30 delta) |

Contoh output:

```
[COLORS] web-design.png — 1280x800px — top 6 warna dominan
1. #FFFFFF  rgb(255, 255, 255)  ~white (light)  53.1%  posisi: background
2. #1F2937  rgb(31, 41, 55)  ~custom (dark)  19.8%  posisi: header/navbar
3. #3B82F6  rgb(59, 130, 246)  ~custom (dark)  6.5%  posisi: accent/panel
```

Region label: `background`, `header/navbar`, `footer`, `sidebar`, `panel/card`, `accent/button/text`, `band`. Nilai hex sudah siap tempel ke CSS/Tailwind. Warna tanpa nama umum (Tailwind dll) dilabel `~custom` — pakai hex/rgb-nya.

> **Flow copas web:** gambar di-paste di chat → `extract-pasted-image.py` → `read_colors(...)` → dapat hex → edit warna.

---

## 🎯 Kenapa ini penting?

Banyak LLM yang **murah/cepat hanya teks-only** — mereka menolak gambar (`Cannot read image / model does not support image input`). Padahal pengguna sering paste **screenshot error, stack trace, scan dokumen, proposal PDF**.

Skill ini menjembatani: **file → OCR → teks → LLM**, tanpa perlu model vision yang mahal.

---

## 🧭 Dua Jalur: Vision vs OCR

| Situasi | Jalur | Kenapa |
|---|---|---|
| Tool/model-nya **punya vision** (mis. Hermes `vision_analyze`, GPT-4o, Gemini) | **Vision** | bisa "ngerti" gambar: layout, grafik, diagram, UI — bukan cuma teks |
| Model teks-only (DeepSeek v4 Flash / R1) | **OCR (repo ini)** | file → teks murni → bisa dianalisa |
| Butuh teks **presisi** (invoice, angka, stack trace, scan) | **OCR** | teks verbatim; model vision bisa halusinasi angka |
| Mesin **tanpa Python** (sandbox, CI, server polos) | **CLI `ocr.sh`** | tesseract + poppler, nol dependensi Python |

Aturan praktis: **vision dulu kalau ada** → kalau angka/teks harus persis atau vision tidak ada, jatuh ke **OCR**. Untuk dokumen penting, jalankan keduanya lalu bandingkan.

### 👁️ Jalur Vision (kalau tool-nya ada)

Contoh di **Hermes** — terbukti jalan walaupun model utamanya teks-only, karena Hermes merutekan gambarnya ke model vision:

```
vision_analyze(image_url="/path/foto.png", question="Baca semua teks & jelaskan isinya")
vision_analyze(image_url="https://contoh.com/grafik.png", question="Apa tren grafik ini?")
```

Menerima path lokal, URL `http(s)`, atau data URL. Pakai `question` yang spesifik; untuk teks panjang minta transkrip verbatim.

### 🐧 Jalur CLI `ocr.sh` (tanpa Python)

Untuk mesin tanpa env Python (`uv`/pip):

```bash
sudo apt-get install -y tesseract-ocr tesseract-ocr-ind tesseract-ocr-eng \
                        poppler-utils imagemagick
install -m 0755 ocr.sh /usr/local/bin/ocr     # atau ~/.local/bin/ocr

ocr foto.png                # teks ke stdout (default bahasa ind+eng)
ocr scan.pdf                # PDF digital → pdftotext; PDF scan → 300dpi → OCR/halaman
ocr a.png b.pdf c.jpg       # banyak file sekaligus
OCR_LANG=eng ocr chart.jpg  # ganti bahasa
```

Bedanya dengan server MCP: `ocr.sh` cuma output teks mentah, tanpa `read_colors`, tanpa mode `code`, dan **tidak** membaca docx/xlsx/pptx (untuk itu pakai `read_document`).

> ✅ Uji nyata di sandbox Linux: PNG teks Indonesia + angka, PDF image-only, dan gambar yang diblur + dikecilkan 60% (simulasi foto HP) — ketiganya kebaca persis.

### 🪶 Mode ringan: server auto-fallback ke tesseract

`server.py` **tidak wajib** RapidOCR/onnxruntime. Urutannya: **RapidOCR → tesseract → pesan error jelas**.

- RapidOCR tidak terpasang / error / hasil kosong → otomatis pakai CLI `tesseract`.
- `pypdfium2` tidak ada → PDF lewat poppler: `pdftotext` (PDF digital) atau `pdftoppm` + tesseract (halaman scan).
- Env: `MCP_OCR_ENGINE=auto|rapidocr|tesseract` dan `MCP_OCR_LANGS=ind+eng` (bahasa yang tidak terpasang otomatis dilewati).
- Header hasil menyebut mesinnya: `engine rapidocr` / `engine tesseract`.

```bash
sudo apt-get install -y tesseract-ocr tesseract-ocr-ind poppler-utils
pip install mcp pillow numpy           # cukup ini, tanpa onnxruntime (~ratusan MB)
python server.py --selftest scan.pdf   # -> engine tesseract
```

> ✅ Uji nyata (venv tanpa `rapidocr` & `pypdfium2`): gambar → `engine tesseract` (conf 0.95),
> PDF scan → `poppler + tesseract` per halaman, PDF digital → `pdftotext`. Semua exit code 0.

---

## 🚀 Cara Setup

### 1. Install dependensi

```bash
cd mcp-ocr
# pakai uv (disarankan)
uv sync

# atau pakai pip langsung
pip install -r pyproject.toml
```

Butuh **Python 3.10 – 3.13**. Dependensi utama:
`mcp`, `rapidocr-onnxruntime`, `Pillow`, `numpy`, `pypdfium2`, `python-docx`, `openpyxl`, `python-pptx`, `striprtf`.

> Model OCR RapidOCR (ONNX) di-download **otomatis saat pertama kali dipakai**.

### 2. Daftarkan sebagai MCP server

Tambahkan ke config MCP klien kamu (opencode, Claude Code, dst):

```json
{
  "mcpServers": {
    "ocr": {
      "command": "python",
      "args": ["/path/ke/server.py"],
      "env": { "PYTHONIOENCODING": "utf-8" }
    }
  }
}
```

### 3. Selftest (tanpa MCP)

```bash
python server.py --selftest                    # buat sample gambar lalu OCR
python server.py --selftest "folder/file"      # test file atau folder
```

---

## 📖 Cara Pakai

Panggil tool dari LLM:

```
read_document(file_path="C:/Users/.../test-failed-1.png")
read_document(file_path="proposal.pdf")
read_document(file_path="laporan-bug.docx", mode="text", enhance=true)
```

| Param | Nilai | Fungsi |
|---|---|---|
| `file_path` | path lokal / URL http(s) / file:// | wajib |
| `mode` | `auto` \| `text` \| `code` | urutan baris OCR (`code` terbaik utk stack trace) |
| `enhance` | `true` (default) | autocontrast + upscale teks kecil |

Hasilnya teks murni + metadata singkat, contoh:

```
[OCR] pasted-XXXX.png — 1658x605px — 21 baris — avg confidence 0.98 — 18.5s
----------------------------------------------------
Models
# Model Provider Source Input Output ...
1 cx/gpt-5.5 9router Codex 16.5M 685K ...
...
```

---

## 🔗 Bonus: Baca gambar yang DI-PASTE langsung di chat

Ada satu masalah unik di **opencode**: gambar yang di-paste di kolom chat **tidak disimpan sebagai file** — opencode menyimpannya di database SQLite (`opencode.db`, tabel `part`) sebagai base64 data-URL. Model teks-only tidak bisa melihat bytes-nya.

Helper `extract-pasted-image.py` menjembatani ini:

```
User paste gambar di chat
        │
        ▼
[extract-pasted-image.py]  ──►  ambil gambar terbaru dari opencode.db
        │                          (base64 → file temp)
        ▼
[read_document]  ──►  OCR  ──►  teks  ──►  LLM jawab
```

### Pakai

```bash
python extract-pasted-image.py
# → {"paths": ["C:/.../pasted-XXXX.png"], "count": 1}
```

Lalu OCR hasilnya:
```
read_document(file_path="C:/.../pasted-XXXX.png")
```

Opsi:
| Flag | Fungsi |
|---|---|
| `--n <N>` | ekstrak N gambar terakhir (default 1) |
| `--session <id>` | filter session tertentu |
| `--outdir <dir>` | folder output (default temp) |
| `--db <path>` | lokasi `opencode.db` (auto-detect) |

> Butuh Python + stdlib saja (sqlite3, base64, json). Lokasi DB auto-detect dari `~/.local/share/opencode/` lalu `~/.config/opencode/`.

### Alur kerja agent (otomatis)

1. User paste gambar → model dapat error `Cannot read image`.
2. Agent jalankan `extract-pasted-image.py` → ambil file temp.
3. Agent panggil `read_document(file_path=<hasil>)` → teks.
4. Agent analisa & jawab. **Tanpa minta user simpan manual.**

---

## 🧩 Struktur Project

```
Super-MCP-OCR-Deepseek/
├── README.md                      ← dokumentasi ini
├── SKILL.md                       ← skill instruction (untuk agent)
├── server.py                      ← MCP OCR server (inti + read_colors)
├── ocr.sh                         ← CLI OCR tanpa Python (tesseract + poppler)
├── extract-pasted-image.py        ← helper gambar tempelan opencode
├── pyproject.toml                 ← dependensi
└── .python-version                ← versi Python
```

---

## 🧠 Alur Kerja Teknis (server.py)

1. **`_resolve_path`** — terima path lokal / URL http(s) / file:// → file lokal.
2. **Routing per ekstensi** — gambar → OCR; pdf → ekstrak+OCR; office → ekstrak; teks → baca.
3. **`_ocr_pil`** (gambar) — pre-process (grayscale + autocontrast + upscale teks kecil) → **RapidOCR ONNX**; kalau RapidOCR absent/error/hasilnya kosong → fallback CLI **`tesseract`** (TSV, conf ≥ 35). Mesin yang dipakai ditulis di header; paksa dengan `MCP_OCR_ENGINE`.
4. **`_read_pdf`** — `pypdfium2` bila ada (teks native per halaman, scan di-render lalu di-OCR); kalau tidak → poppler: `pdftotext`, atau `pdftoppm` + tesseract untuk halaman scan.
5. **`_extract_palette` / `_read_colors`** (gambar) — flatten RGBA→RGB → downscale → kuantisasi median-cut (PIL) → cluster warna dominan → gabung shade dekat → hitung % area + region.
6. **Confidence filter** — buang hasil OCR dengan skor < 0.35.
7. **Output** — header metadata + teks murni, siap dianalisa LLM.

### Kenapa preprocessing?

- Teks kecil (< 900px) di-**upscale** 2–3× agar OCR akurat.
- Gambar raksasa (> 3200px) di-**cap** agar tidak boros memory.
- **Autocontrast** meningkatkan kontras teks di screenshot gelap/terang.

---

## 🔧 Troubleshooting

| Masalah | Solusi |
|---|---|
| `API Error 500 max instances` / `401 Insufficient balance` | Masalah **kuota gateway model**, bukan MCP OCR. Top up saldo, lalu ulangi. |
| Tool tidak muncul di klien | Restart sesi / `mcp` reconnect. Cek `claude mcp get ocr` → harus `Connected`. |
| OCR hasil jelek | Pakai `mode="code"` untuk stack trace; cek file dinaikkan resolusi. |
| Tidak bisa install Python env (sandbox/CI) | Pakai CLI `ocr.sh` (tesseract + poppler), lihat bagian 🧭 Dua Jalur. |
| Model utama teks-only tapi tool vision ada | Pakai jalur Vision (`vision_analyze`) dulu, OCR sebagai pembanding/presisi. |
| `.doc`/`.xls` tidak terbaca | Simpan ulang sebagai `.docx`/`.xlsx`. |

---

## 📄 Lisensi

MIT — bebas dipakai, diubah, disebarluaskan.

Dibuat untuk mengaktifkan DeepSeek & LLM teks-only lainnya di ekosistem MCP (opencode, Claude Code, dll).