Kodlama ajanınız bir depodaki şeyleri bulmada çok iyidir, yeter ki metin olsun. Claude Code ya da Cursor’a sensör veri sayfasının çalışma sıcaklığı hakkında ne dediğini sorun ve o grep yapar, hiçbir şey bulamaz ve ya tahmin eder ya da vazgeçer, çünkü veri sayfası bir PDF ve karar kaydı bir Word dosyasıdır. GroupDocs.Search.Mcp yerel olarak Docker’da çalışır ve ajana bu belgeler üzerinde tam metin indeksi sağlar, zaten kod için kullandığı arama‑sonra‑okuma döngüsüyle aynı şekilde:

docs klasörünü indeksle, ardından sensör veri sayfasının çalışma sıcaklığı hakkında ne dediğini ve telemetri depolamasını hangi ADR karar verdiğini bana söyle.

Adım adım sürüm, yapılandırma ve sorun giderme ile birlikte belgelerde bulunabilir: Claude Code veya Cursor’un bir depodaki PDF ve Word belgelerini aramasını nasıl sağlarsınız.

Grep neden boş dönüyor?

Çünkü PDF ve DOCX kelimelerini düz metin olarak saklamaz. DOCX bir zip arşividir; PDF metin akışlarını sıkıştırır. Bayt bayt arama yaparsanız kelimeler bulunmaz. Bunu küçük bir depoyla test ettik: bir PDF veri sayfası, bir mimari karar kaydı ve DOCX formatında bir gereksinim belgesi, ve bir kaynak dosya.

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

Tek eşleşme, ajanın okuyamadığı belgeye işaret eden bir kod yorumudur. İşte bu eksiklik: bir sabitin nedeni, bir tasarımın kararı, bir testin gereksinimi genellikle tam da bu dosyalarda bulunur.

Bir indeksle ne değişir?

Ajan, belgeler için bir geri getirme aracı elde eder. Sunucuyu depo kökünden kaydedin, böylece depo depolama klasörü olarak bağlanır:

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

Ardından aynı sorular cevap alır. Sunucunun test depomuzda döndürdüğü sonuçlar (yollar depo köküne göre gösterilmiştir):

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

Bir sorgu, gereksinimi ve veri sayfası satırını birlikte buldu; bu, elle yapmak için zahmetli ve grep ile imkansız olan bir çapraz referans türüdür. Küçük indeksimizde aramalar, ilk çağrıdan 80 ila 240 milisaniye içinde geri döndü.

Ajanın zaten bildiği döngü

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 hangi dosyaların olduğunu yanıtlar, get_text_fragments eşleşen satırları birkaç bağlam kelimesiyle döndürür ve ajan ikisini de alıntılar. Bu, grep’in şekli olup 82 formata genişletilmiştir: PDF, DOCX, XLSX, PPTX, HTML, Markdown, hatta birinin repoya aktardığı e‑posta dizileri.

Ajana ne zaman kullanacağını söyle

Ajanlar, bir araca ne zaman başvuracakları konusunda proje talimatlarını izler. CLAUDE.md veya AGENTS.md dosyasındaki üç satır, grep denemeye çalışan, başarısız olup vazgeçen bir ajan ile önce indeksi arayan bir ajan arasındaki farkı yaratır:

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.

İki bakım noktası. İndeks, bağlanan klasörün kökünde .groupdocs-search-index/ dizinine yazılır, bu yüzden bunu .gitignore dosyasına ekleyin. Ve bir çekme (pull) işleminden sonra, update_index sadece değişenleri yeniden okur, böylece indeksi güncel tutmak bir çağrı maliyetindedir.

Cursor ve VS Code

Aynı konteyner herhangi bir MCP istemcisinde çalışır. VS Code’da, bir çalışma alanı .vscode/mcp.json açık olan herhangi bir klasörü bağlayabilir, böylece indeks proje ile birlikte hareket eder:

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

Cursor, .cursor/mcp.json içinde mcpServers altında aynı command ve args değerlerini kullanır. Konfigürasyon dosyasını commit edin ve projedeki her geliştirici aracı elde eder; indeksi git dışına tutun.

Neden her şeyi önce metne dönüştürmüyorsunuz?

Yapabilirsiniz: ajan ihtiyacı olduğunda her PDF’i dönüştürsün ya da Markdown kopyalarını depoya ekleyin. Her ikisi de birkaç dosya için çalışır. İndeks dönüşümü bir kez yapar, bir çağrıyla güncel tutar ve ajan herhangi bir dosyayı okumadan önce hangi dosyanın önemli olduğunu yanıtlar; bu, uzun bir oturumun bağlamını küçük tutan adımdır. Bunun arkasındaki motor GroupDocs.Search’tir; bu, Office ve PDF belgelerini doğrudan okur, bakımını yapmanız gereken bir dönüştürücü üzerinden geçmez.

Dürüst sınırlamalar

  • Değerlendirme modunda bir indeks en fazla 100 belge tutar ve bir arama en fazla 10 sonuç döndürür; önce get_license_status çağırın.
  • Tam metin, semantik değil: ajan belgelerin kullandığı kelimeleri kullanmalı ya da varyantları denemelidir.
  • OCR yok: metin katmanı olmayan taranmış bir veri sayfası sadece dosya özellikleriyle indekslenir.
  • Sadece Docker. Linux’ta, konteynerin sizin sahip olduğunuz bir depoya indeksi yazabilmesi için --user "$(id -u):$(id -g)" ekleyin.

SSS

Claude Code depomdaki PDF dosyalarını okuyabilir mi?
Grep ile değil. GroupDocs.Search MCP sunucusuyla, önce dönüştürmeden yerel olarak arama yapabilir ve alıntılayabilir.

Cursor ve VS Code’da da çalışıyor mu?
Evet. .cursor/mcp.json veya .vscode/mcp.json içinde aynı docker run argümanlarını kullanın; VS Code ${workspaceFolder}‘ı bağlayabilir.

İndeks commitlerime dahil olacak mı?
Sadece izin verirseniz. .groupdocs-search-index/‘i .gitignore‘a ekleyin.

Daha derine inin