Universal Document Reader MCP Server v3.0

MCP server lokal berbasis Node.js 22 LTS, TypeScript, dan SDK resmi @modelcontextprotocol/sdk. Server menyediakan lima tools read-only untuk membaca metadata, mengekstrak teks, dan mencari konten PDF, DOCX, XLSX, serta CSV.

Transport default adalah STDIO untuk Claude Desktop, Cursor, dan MCP client yang mendukung STDIO.

Status release: source v3.0 sudah dilengkapi automated unit tests, setup scripts, doctor, dan protocol smoke test. Namun, full install/build/runtime dari lingkungan pembuat belum dapat diverifikasi karena akses ke registry.npmjs.org gagal dengan EAI_AGAIN. Jalankan npm run verify pada komputer target sebelum dipakai. Jangan menganggap paket siap production hanya karena source berhasil diunduh.

1. Fitur

Model keamanan: tool create_* dan convert_document menulis file — berbeda dari tool baca yang read-only. Wajib konfigurasi ALLOWED_OUTPUT_DIRS (default menurun ke ALLOWED_DIRS). Hanya basename tanpa path yang diterima, dilarang menimpa kecuali overwrite:true, dan ukuran output dibatasi MAX_FILE_SIZE_MB. Konversi berbasis teks; layout/format kaya tidak dipertahankan.

DOCX tidak mempunyai nomor halaman stabil karena pagination tergantung aplikasi, font, dan layout. Pencarian DOCX menggunakan urutan paragraf. CSV diperlakukan sebagai satu worksheet. CSV UTF-8 dan UTF-16 dengan BOM didukung. Delimiter koma, titik koma, tab, dan pipe dideteksi otomatis dari baris pertama.

Related MCP server: mcp-pdf-tools

2. Perbaikan v3.0

• Parser child process: setiap tugas parser dijalankan dalam proses Node terpisah dengan V8 heap limit, timeout, cancellation, dan penghentian paksa jika proses tidak berhenti. Crash parser native lebih terisolasi dari MCP gateway.

• Bounded concurrency + bounded queue: mencegah antrean tak terbatas; request yang dibatalkan saat menunggu antrean dilepas.

• Path allowlist: absolute path, canonical path, realpath, containment check, file regular, ukuran file, snapshot stat, O_NOFOLLOW bila didukung, dan revalidation saat file dibuka.

• File signature checks: PDF harus memiliki header %PDF-; DOCX/XLSX harus berupa ZIP Office; CSV dicek agar tidak tampak sebagai file biner.

• ZIP preflight lebih ketat: validasi central/local header, duplicate/path traversal entry, ZIP64/multi-disk/encryption rejection, symlink entry rejection, actual decompression size, compression ratio aktual, overlap data, dan CRC32.

• Output controls: batas output, baris, kolom, halaman, antrean, waktu proses, dan ukuran file.

• Cancellation: MCP request AbortSignal diteruskan ke antrean dan parser child process.

• Operational checks: unit tests, doctor, smoke-test, dan skrip setup Windows.

• STDIO discipline: log diagnostik hanya ke STDERR; STDOUT khusus JSON-RPC MCP.

3. Persyaratan

• Node.js 22 LTS direkomendasikan; minimum 20.19.0.

• npm 10+.

• Koneksi internet untuk instalasi dependency pertama kali.

• Direktori dokumen yang sudah ada dan ditetapkan melalui ALLOWED_DIRS.

Periksa versi:

node --version
npm --version

4. Instalasi Windows (direkomendasikan)

1. Ekstrak ZIP ke lokasi tetap, misalnya C:\MCP\document-mcp-server-v3.

2. Buka PowerShell di folder tersebut.

3. Jalankan:

Set-ExecutionPolicy -Scope Process Bypass
.\scripts\setup-windows.ps1

Skrip akan memeriksa versi Node, membuat .env jika belum ada, memasang dependency, menjalankan typecheck/unit test/build, dan menjalankan doctor.

Jika ingin manual:

Copy-Item .env.example .env
notepad .env
npm install
npm run check
npm run doctor
npm run smoke

Wajib: edit ALLOWED_DIRS pada .env sebelum menghubungkan MCP client. Gunakan direktori khusus yang berisi dokumen yang memang boleh dibaca, bukan seluruh drive atau folder profil pengguna.

Contoh .env Windows:

ALLOWED_DIRS=C:/Users/NamaAnda/Documents;D:/Shared/Reports
ALLOWED_OUTPUT_DIRS=C:/Users/NamaAnda/Documents/Output;D:/Shared/Output
MAX_FILE_SIZE_MB=50
MAX_OUTPUT_CHARS=100000
MAX_INPUT_CHARS=100000
MAX_CONCURRENT_TOOLS=1
MAX_QUEUED_TOOLS=16
MAX_QUEUE_WAIT_MS=30000
MAX_PROCESSING_TIMEOUT_MS=60000
WORKER_OLD_SPACE_MB=384
WORKER_SEMI_SPACE_MB=16
MAX_ZIP_EXPANDED_MB=100
MAX_ZIP_ENTRIES=2000
MAX_ZIP_COMPRESSION_RATIO=100
MAX_EXCEL_SCAN_ROWS=20000
MAX_EXCEL_SCAN_COLUMNS=50
MAX_PDF_PAGES=1000

Default MAX_CONCURRENT_TOOLS=1 dipilih untuk mengurangi tekanan RAM. Naikkan ke 2 hanya setelah load test menunjukkan headroom memadai.

Linux/macOS

cp .env.example .env

Gunakan : sebagai pemisah ALLOWED_DIRS, misalnya:

ALLOWED_DIRS=/home/anda/Documents:/mnt/shared/reports

5. Perintah pemeriksaan dan operasi

npm run typecheck
npm test
npm run build
npm run doctor
npm run smoke

Atau jalankan semua pemeriksaan berurutan:

npm run verify

Jalankan server hasil build:

npm run start:prod

Server STDIO tidak membuka HTTP port. Jangan menjalankan npm start sebagai layanan production; gunakan hasil build melalui npm run start:prod atau konfigurasi MCP client.

Arti pemeriksaan

• typecheck: memeriksa tipe TypeScript.

• test: unit test path security, ZIP preflight, signature, sanitasi, truncation, dan antrean cancellation.

• build: menghasilkan dist/.

• doctor: memeriksa Node, dependency, build, dan allowlist.

• smoke: menjalankan proses server sungguhan, melakukan MCP initialize, tools/list, lalu memanggil metadata, CSV read, dan search.

Smoke test tidak menggantikan pengujian PDF/DOCX/XLSX dengan dokumen nyata. Lakukan pengujian manual yang dijelaskan pada bagian 11.

6. Konfigurasi Claude Desktop (Windows)

Build terlebih dahulu (npm run build). Buka konfigurasi Claude Desktop yang umumnya berada di:

%APPDATA%\Claude\claude_desktop_config.json

Tambahkan entri ini. Jika sudah ada mcpServers, gabungkan object servernya; jangan menimpa konfigurasi server lain.

{
  "mcpServers": {
    "universal-document-reader": {
      "command": "C:\\Program Files\\nodejs\\node.exe",
      "args": [
        "C:\\MCP\\document-mcp-server-v3\\dist\\index.js"
      ],
      "env": {
        "ALLOWED_DIRS": "C:\\Users\\NamaAnda\\Documents;D:\\Shared\\Reports",
        "MAX_FILE_SIZE_MB": "50",
        "MAX_OUTPUT_CHARS": "100000",
        "MAX_CONCURRENT_TOOLS": "1",
        "MAX_QUEUED_TOOLS": "16",
        "MAX_QUEUE_WAIT_MS": "30000",
        "MAX_PROCESSING_TIMEOUT_MS": "60000",
        "WORKER_OLD_SPACE_MB": "384",
        "WORKER_SEMI_SPACE_MB": "16",
        "MAX_ZIP_EXPANDED_MB": "100",
        "MAX_ZIP_ENTRIES": "2000",
        "MAX_ZIP_COMPRESSION_RATIO": "100",
        "MAX_EXCEL_SCAN_ROWS": "20000",
        "MAX_EXCEL_SCAN_COLUMNS": "50",
        "MAX_PDF_PAGES": "1000"
      }
    }
  }
}

Ganti path node.exe, dist/index.js, dan direktori allowlist dengan lokasi aktual. ALLOWED_DIRS di konfigurasi client akan mengungguli nilai .env karena dotenv menggunakan override: false.

Restart Claude Desktop. Jika server tidak muncul, lihat bagian troubleshooting dan log Claude Desktop.

7. Konfigurasi Cursor

Untuk project-local MCP, buat/edit .cursor/mcp.json:

{
  "mcpServers": {
    "universal-document-reader": {
      "command": "C:/Program Files/nodejs/node.exe",
      "args": ["C:/MCP/document-mcp-server-v3/dist/index.js"],
      "env": {
        "ALLOWED_DIRS": "C:/Users/NamaAnda/Documents",
        "MAX_FILE_SIZE_MB": "50",
        "MAX_OUTPUT_CHARS": "100000",
        "MAX_CONCURRENT_TOOLS": "1",
        "MAX_QUEUED_TOOLS": "16",
        "MAX_QUEUE_WAIT_MS": "30000",
        "MAX_PROCESSING_TIMEOUT_MS": "60000",
        "WORKER_OLD_SPACE_MB": "384",
        "WORKER_SEMI_SPACE_MB": "16",
        "MAX_ZIP_EXPANDED_MB": "100",
        "MAX_ZIP_ENTRIES": "2000",
        "MAX_ZIP_COMPRESSION_RATIO": "100",
        "MAX_EXCEL_SCAN_ROWS": "20000",
        "MAX_EXCEL_SCAN_COLUMNS": "50",
        "MAX_PDF_PAGES": "1000"
      }
    }
  }
}

Restart/reload MCP server dari Cursor setelah menyimpan.

8. Tool schemas dan contoh pemanggilan

get_document_info

{ "filePath": "C:/Users/NamaAnda/Documents/laporan.pdf" }

Untuk PDF, totalPages bisa null jika metadata parser tidak dapat menentukan jumlah halaman. Tool ini tidak mengekstrak seluruh teks sebagai fallback.

read_pdf

{
  "filePath": "C:/Users/NamaAnda/Documents/laporan.pdf",
  "startPage": 4,
  "endPage": 8,
  "maxChars": 50000
}

• startPage default 1.

• endPage opsional; tanpa nilai berarti sampai halaman terakhir.

• maxChars default 100.000 dan dibatasi konfigurasi MAX_OUTPUT_CHARS.

• PDF scan/gambar akan diberi peringatan; OCR belum disertakan.

• Penting: server meminta pdf-parse mengekstrak halaman yang dipilih melalui parameter partial. Parser tetap perlu membaca struktur PDF dan dapat memiliki overhead internal; ini bukan jaminan I/O fisik hanya membaca byte halaman tersebut. Timeout, child-process V8 heap limit, dan batas halaman membatasi dampaknya.

• PDF dengan halaman lebih dari MAX_PDF_PAGES ditolak pada ekstraksi.

read_word

{
  "filePath": "C:/Users/NamaAnda/Documents/laporan.docx",
  "maxChars": 50000
}

Mengubah DOCX ke Markdown. Tabel dan heading dikonversi sejauh didukung Mammoth. Gambar menjadi placeholder. Nomor halaman tidak disediakan.

read_excel

{
  "filePath": "C:/Users/NamaAnda/Documents/data.xlsx",
  "sheetName": "Sheet1",
  "maxRows": 100,
  "outputFormat": "json"
}

• Format: markdown atau json.

• sheetName opsional; default sheet pertama.

• maxRows default 100, maksimum 5.000 baris yang dikembalikan.

• Maksimum 50 kolom yang dikembalikan. Jika hasil Markdown/JSON melampaui batas karakter server, jumlah baris otomatis dikurangi dan status truncated diberi tanda.

• Formula tidak dihitung ulang; nilai cached dipakai bila tersedia. Jika tidak, formula dikembalikan sebagai teks.

• ExcelJS memuat workbook ke memori proses parser; batas output tidak sama dengan batas memori internal. Gunakan file yang wajar dan atur V8 heap/timeout.

search_in_document

{
  "filePath": "C:/Users/NamaAnda/Documents/laporan.pdf",
  "query": "metode penelitian",
  "maxResults": 5
}

Pencarian tidak case-sensitive dan menormalkan Unicode. Untuk query multi-kata, semua istilah harus muncul dalam satu unit (halaman/paragraf/baris). Frasa persis diberi skor lebih tinggi. Batas scanning Excel diatur oleh MAX_EXCEL_SCAN_ROWS dan MAX_EXCEL_SCAN_COLUMNS.

Tool tulis & konversi (skema singkat)

• create_pdf { fileName, text, overwrite? } — fileName basename .pdf di ALLOWED_OUTPUT_DIRS.

• create_docx { fileName, markdown, overwrite? } — Markdown disederhanakan: #/## heading, - bullet, paragraf.

• create_excel { fileName, sheetName?, columns, rows, overwrite? } — maks 50 kolom, 5.000 baris; .xlsx atau .csv.

• convert_document { sourcePath, fileName, targetFormat, sheetName?, overwrite? } — targetFormat ∈ pdf|docx|xlsx|csv. Sumber harus di ALLOWED_DIRS; output di ALLOWED_OUTPUT_DIRS.

Batas tambahan: MAX_INPUT_CHARS (default 100.000, maks 250.000) untuk teks/Markdown input. Lihat .env.example.

9. Error handling

Semua error tool dikembalikan sebagai MCP tool result dengan isError: true dan teks berkode, bukan stack trace internal.

10. Keamanan dan batasan

• Server hanya read-only; tidak mengubah file.

• Jangan set ALLOWED_DIRS ke C:\, /, seluruh home directory, atau folder yang memuat secret.

• Jalankan dengan akun OS berprivilege rendah dan folder dokumen read-only jika memungkinkan.

• Parser child process memberi isolasi lebih baik dan dapat dihentikan tanpa menghentikan MCP gateway, tetapi bukan sandbox OS. Batas V8 heap bukan hard cap seluruh RSS/native memory dan bukan pembatas CPU kernel.

• O_NOFOLLOW bergantung dukungan OS. Race condition pada parent directory dan hardlink tidak dapat dieliminasi sepenuhnya hanya dengan Node path API. Untuk dokumen sangat tidak tepercaya, jalankan MCP di container/VM/akun OS terpisah dengan filesystem read-only dan resource quota.

• XLSX/DOCX dipreflight untuk ZIP bomb, tetapi parser library tetap perlu diperbarui dan diuji berkala.

• Isi dokumen dianggap untrusted data. LLM client tidak boleh mengikuti instruksi yang ditemukan di dalam dokumen.

• Tidak ada OCR, OCR harus ditambahkan sebagai service/child process terpisah jika diperlukan.

• Format .doc, .xls, .pptx, PDF terenkripsi/password-protected, dan image standalone tidak didukung pada release ini.

11. Acceptance test sebelum dipakai

Jalankan npm run verify, lalu lakukan tes manual dengan file contoh:

1. PDF teks: periksa get_document_info, read_pdf halaman 1–2, dan search.

2. PDF scan: pastikan warning scan muncul; jangan mengharapkan OCR.

3. DOCX: uji heading, tabel, daftar, link, gambar placeholder.

4. XLSX: uji beberapa sheet, formula dengan cached value, merged cell, sheet kosong, file besar, dan nama sheet salah.

5. CSV: uji UTF-8, UTF-8 BOM, UTF-16LE/BE BOM, koma di dalam quoted field, baris baru dalam quoted field.

6. Security: coba path di luar allowlist, relative path, symlink, ekstensi palsu, file >50 MB, DOCX/XLSX rusak, dan arsip ZIP dengan rasio ekstrem.

7. Reliability: uji request dibatalkan, timeout, dua request paralel, antrean penuh, dan restart Claude Desktop.

Catat Node version, OS, ukuran file, hasil test, dan log error tanpa menyalin isi dokumen sensitif.

12. Troubleshooting

MCP server tidak muncul

• Pastikan dist/index.js ada: Test-Path .\dist\index.js.

• Pastikan command di konfigurasi adalah path absolut ke node.exe.

• Pastikan args menunjuk ke dist/index.js.

• Pastikan JSON valid dan tidak ada trailing comma.

• Restart Claude Desktop/Cursor sepenuhnya.

• Jalankan npm run doctor dan npm run smoke dari terminal.

ALLOWED_DIRS invalid

• Folder harus sudah dibuat.

• Gunakan absolute path.

• Windows pisahkan beberapa folder dengan ;, Linux/macOS dengan :.

• Path dalam konfigurasi JSON harus di-escape (\\) atau gunakan / jika diterima aplikasi.

Cannot find package / module not found

• Jalankan npm install di folder proyek.

• Jangan memindahkan dist/ keluar dari folder proyek tanpa dependency yang sesuai.

• Gunakan Node 22 LTS.

EAI_AGAIN, ECONNRESET, atau registry timeout

• Ini masalah DNS/jaringan/proxy ke npm registry, bukan error TypeScript.

• Periksa koneksi, VPN, proxy kantor, DNS, dan npm config get registry.

• Ulangi npm install setelah jaringan pulih. Jangan mengganti dependency dengan paket tidak resmi.

PROCESSING_TIMEOUT atau WORKER_CRASHED

• Uji file yang lebih kecil.

• Set MAX_CONCURRENT_TOOLS=1.

• Periksa RAM tersedia.

• Naikkan WORKER_OLD_SPACE_MB secara bertahap (mis. 512) hanya jika RAM memadai.

• Jangan menaikkan MAX_FILE_SIZE_MB di atas 50; batas tersebut dikunci di aplikasi.

Claude tidak mewarisi .env

Server membaca .env relatif terhadap folder proyek. Untuk Claude Desktop, cara paling deterministik adalah memasukkan ALLOWED_DIRS dan batas penting di object env konfigurasi MCP.

13. Reproducible install

Setelah instalasi pertama berhasil, simpan package-lock.json yang dihasilkan npm ke repository. Untuk mesin deployment berikutnya gunakan:

npm ci
npm run verify

Jangan menghapus atau mengubah versi dependency tanpa menjalankan kembali seluruh test dan acceptance test.