🦉 Super MCP OCR for DeepSeek (teks-only LLM)

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

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

Tool yang tersedia (2 nama, fungsi sama):

• read_document(file_path, mode, enhance) — nama penuh

• ocr_image(image_path, mode, enhance) — alias kompatibel

Related MCP server: docling-mcp

🎯 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.

🚀 Cara Setup

1. Install dependensi

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

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

3. Selftest (tanpa MCP)

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)

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

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

Lalu OCR hasilnya:

read_document(file_path="C:/.../pasted-XXXX.png")

Opsi:

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)
├── 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 → susun hasil jadi baris visual (urut y lalu x).

4. Confidence filter — buang hasil OCR dengan skor < 0.35.

5. 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

📄 Lisensi

MIT — bebas dipakai, diubah, disebarluaskan.

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