Agent pengkodean Anda sangat baik dalam menemukan hal‑hal di repositori, selama mereka berupa teks. Tanyakan kepada Claude Code atau Cursor apa yang dikatakan lembar data sensor tentang suhu operasi dan ia melakukan grep, tidak menemukan apa‑apa, dan entah menebak atau menyerah, karena lembar data tersebut berupa PDF dan catatan keputusan berupa file Word. GroupDocs.Search.Mcp berjalan secara lokal di Docker dan memberikan agen indeks teks penuh atas dokumen‑dokumen tersebut, dengan loop pencarian‑lalu‑baca yang sama yang sudah digunakannya untuk kode:

Indeks folder docs, lalu beri tahu saya apa yang dikatakan lembar data sensor tentang suhu operasi dan ADR mana yang memutuskan penyimpanan telemetri.

Versi langkah demi langkah dengan konfigurasi dan pemecahan masalah ada di dokumentasi: Cara Membiarkan Claude Code atau Cursor mencari PDF dan Dokumen Word dalam repositori.

Mengapa grep mengembalikan hasil kosong?

Karena PDF dan DOCX tidak menyimpan kata‑katasinya sebagai teks biasa. DOCX adalah arsip zip; PDF mengompresi aliran teksnya. Mencari satu byte demi satu byte tidak menemukan kata‑kata tersebut. Kami mengujinya dengan repositori kecil: satu lembar data PDF, sebuah catatan keputusan arsitektur, dan dokumen persyaratan dalam DOCX, serta sebuah file sumber.

$ grep -ri "TimescaleDB\|operating temperature\|I2C" docs/
$ grep -rn "datasheet" src/
src/sensor.py:1:MAX_TEMP_C = 85  # see docs/datasheet

Satu‑satunya temuan adalah komentar kode yang menunjuk ke dokumen yang tidak dapat dibaca agen. Itulah kesenjangan: alasan di balik sebuah konstanta, keputusan di balik sebuah desain, persyaratan di balik sebuah tes sering kali berada tepat di file‑file tersebut.

Apa yang berubah dengan indeks?

Agen mendapatkan alat pengambilan untuk dokumen. Daftarkan server dari root repositori, sehingga repositori dipasang sebagai folder penyimpanan:

claude mcp add groupdocs-search -- docker run --rm -i \
  -v "$(pwd)":/data ghcr.io/groupdocs-search/search-net-mcp:latest

Kemudian pertanyaan yang sama mengembalikan jawaban. Inilah yang dikembalikan server di repositori uji kami (jalur ditampilkan relatif terhadap root repositori):

-> add_to_index {"documentsPath":"docs","indexName":"gateway"}
<- Indexed 'docs' into index 'gateway': 3 document(s) added,
   3 in the index.

-> search {"query":"TimescaleDB","indexName":"gateway"}
<- documentsFound 1: docs/adr-007-telemetry-storage.docx

-> get_text_fragments {"query":"I2C","indexName":"gateway"}
<- === docs/requirements-v2.docx (1 occurrence(s)) ===
     …REQ-15: the I2C bus runs at 400 kHz.…
   === docs/tmp117-sensor-datasheet.pdf (1 occurrence(s)) ===
     …I2C address selection: ADD0 pin to GND gives 0x48…

Satu kueri menemukan persyaratan dan baris lembar data bersama‑sama, yang merupakan jenis referensi silang yang melelahkan dilakukan secara manual dan tidak mungkin dengan grep. Pada indeks kecil kami, pencarian kembali dalam 80 hingga 240 milidetik setelah panggilan pertama.

Loop yang sudah diketahui agen

user              agent                         Search MCP server
 |  "What does the datasheet say about I2C addresses?"         |
 |---------------->|                                           |
 |                 |-- search {"query":"I2C"} --------------->|
 |                 |<- requirements-v2.docx,                   |
 |                 |   tmp117-sensor-datasheet.pdf ------------|
 |                 |-- get_text_fragments {"query":"I2C"} --->|
 |                 |<- "...ADD0 pin to GND gives 0x48..." -----|
 |<- "0x48 with ADD0 to GND, 0x49 to V+ (datasheet, p.1);      |
 |    REQ-15 runs the bus at 400 kHz."                         |

search menjawab file mana, get_text_fragments mengembalikan baris yang cocok dengan beberapa kata konteks, dan agen mengutip keduanya. Ini adalah bentuk grep, diperluas ke 82 format: PDF, DOCX, XLSX, PPTX, HTML, Markdown, bahkan rangkaian email yang seseorang ekspor ke repo.

Beritahu agen kapan harus menggunakannya

Agen mengikuti instruksi proyek tentang kapan harus menggunakan alat. Tiga baris dalam CLAUDE.md atau AGENTS.md membuat perbedaan antara agen yang mencoba grep, gagal dan menyerah, dan yang mencari indeks terlebih dahulu:

PDF, DOCX and XLSX files under docs/ are indexed in the groupdocs-search MCP index
'docs'. grep cannot read them: use search (quote phrases) and get_text_fragments
for anything in specs, datasheets or ADRs, and cite the file.
Run update_index (indexName: docs) after pulling changes.

Dua poin pemeliharaan. Indeks ditulis ke .groupdocs-search-index/ di root folder yang dipasang, jadi tambahkan itu ke .gitignore. Dan setelah pull, update_index membaca ulang hanya yang berubah, sehingga menjaga indeks tetap terbaru hanya memerlukan satu panggilan.

Cursor dan VS Code

Kontainer yang sama berfungsi di klien MCP mana pun. Di VS Code, workspace .vscode/mcp.json dapat memasang folder apa pun yang terbuka, sehingga indeks mengikuti proyek:

{
  "servers": {
    "groupdocs-search": {
      "type": "stdio",
      "command": "docker",
      "args": [ "run", "--rm", "-i",
                "-v", "${workspaceFolder}:/data",
                "ghcr.io/groupdocs-search/search-net-mcp:latest" ]
    }
  }
}

Cursor menggunakan command dan args yang sama di bawah mcpServers dalam .cursor/mcp.json. Commit file konfigurasi dan setiap pengembang dalam proyek mendapatkan alat; simpan indeks itu sendiri di luar git.

Mengapa tidak mengonversi semuanya ke teks terlebih dahulu?

Anda dapat: membuat agen mengonversi setiap PDF saat diperlukan, atau memeriksa salinan Markdown ke dalam repositori. Keduanya bekerja untuk beberapa file. Indeks melakukan konversi sekali, menjaga agar tetap terbaru dengan satu panggilan, dan menjawab file mana yang penting sebelum agen membaca apa pun, yang merupakan langkah yang menjaga konteks sesi panjang tetap kecil. Mesin di baliknya adalah GroupDocs.Search, yang membaca dokumen Office dan PDF secara langsung daripada melalui konverter yang harus Anda pelihara.

Batasan jujur

  • Pada mode evaluasi, sebuah indeks menyimpan maksimal 100 dokumen dan pencarian mengembalikan maksimal 10; panggil get_license_status terlebih dahulu.
  • Teks penuh, bukan semantik: agen harus menggunakan kata‑kata yang digunakan dokumen, atau mencoba varian.
  • Tidak ada OCR: lembar data yang dipindai tanpa lapisan teks hanya diindeks berdasarkan properti file‑nya.
  • Hanya Docker. Di Linux, tambahkan --user "$(id -u):$(id -g)" agar kontainer dapat menulis indeks ke dalam repositori yang Anda miliki.

FAQ

Apakah Claude Code dapat membaca file PDF di repositori saya?
Tidak dengan grep. Dengan server GroupDocs.Search MCP ia dapat mencari dan mengutipnya, secara lokal, tanpa mengonversinya terlebih dahulu.

Apakah ini bekerja di Cursor dan VS Code juga?
Ya. Gunakan argumen docker run yang sama di .cursor/mcp.json atau .vscode/mcp.json; VS Code dapat memasang ${workspaceFolder}.

Apakah indeks akan masuk ke commit saya?
Hanya jika Anda mengizinkannya. Tambahkan .groupdocs-search-index/ ke .gitignore.

Selami lebih dalam