Your coding agent is zeer goed in het vinden van dingen in een repository, zolang ze tekst zijn. Vraag Claude Code of Cursor wat het sensorspecificatieblad zegt over de bedrijfstemperatuur en het grept, vindt niets, en raadt of geeft het op, omdat het specificatieblad een PDF is en het besluitrecord een Word‑bestand. GroupDocs.Search.Mcp draait lokaal in Docker en geeft de agent een full‑text index over die documenten, met dezelfde zoek‑dan‑lees‑lus die hij al voor code gebruikt:

Index de map docs, vertel me vervolgens wat het sensorspecificatieblad zegt over de bedrijfstemperatuur en welke ADR de telemetrie‑opslag heeft beslist.

De stap‑voor‑stap versie met configuratie en probleemoplossing staat in de documentatie: Hoe laat je Claude Code of Cursor de PDF‑ en Word‑documenten in een repository doorzoeken.

Waarom geeft grep geen resultaat?

Omdat PDF‑ en DOCX‑bestanden hun woorden niet als platte tekst opslaan. Een DOCX is een zip‑archief; een PDF comprimeert zijn tekst‑streams. Zoek je byte‑voor‑byte, dan zijn de woorden er niet. We hebben het getest met een kleine repository: één PDF‑specificatieblad, een architectuur‑besluitrecord en een eisen‑document in DOCX, en een bronbestand.

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

De enige treffer is een code‑commentaar dat naar het document wijst dat de agent niet kan lezen. Dat is de kloof: de reden achter een constante, het besluit achter een ontwerp, de eis achter een test leven vaak precies in die bestanden.

Wat verandert er met een index?

De agent krijgt een retrieval‑tool voor documenten. Registreer de server vanaf de root van de repository, zodat de repository wordt gemount als de opslagmap:

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

Daarna geven dezelfde vragen antwoorden. Dit is wat de server teruggaf in onze test‑repository (paden getoond relatief ten opzichte van de repository‑root):

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

Eén query vond zowel de eis als de regel uit het specificatieblad, wat het soort kruis‑referentie is dat handmatig omslachtig is en met grep onmogelijk. In onze kleine index kwamen zoekopdrachten terug in 80 tot 240 milliseconden na de eerste oproep.

De lus die de agent al kent

user              agent                         Search MCP server
 |  "Wat zegt het datasheet over I2C‑adressen?"         |
 |---------------->|                                           |
 |                 |-- search {"query":"I2C"} --------------->|
 |                 |<- requirements-v2.docx,                   |
 |                 |   tmp117-sensor-datasheet.pdf ------------|
 |                 |-- get_text_fragments {"query":"I2C"} --->|
 |                 |<- "...ADD0 pin to GND gives 0x48..." -----|
 |<- "0x48 met ADD0 naar GND, 0x49 naar V+ (datasheet, p.1);      |
 |    REQ-15 laat de bus draaien op 400 kHz."                         |

search beantwoordt welke bestanden, get_text_fragments geeft de overeenkomende regels met een paar woorden context, en de agent citeert beide. Het is de vorm van grep, uitgebreid naar 82 formaten: PDF, DOCX, XLSX, PPTX, HTML, Markdown, zelfs de e‑mailthreads die iemand in de repo heeft geëxporteerd.

Vertel de agent wanneer hij het moet gebruiken

Agents volgen project‑instructies over wanneer ze een tool moeten inzetten. Drie regels in CLAUDE.md of AGENTS.md maken het verschil tussen een agent die grep probeert, faalt en opgeeft, en één die eerst de index doorzoekt:

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.

Twee housekeeping‑punten. De index wordt geschreven naar .groupdocs-search-index/ in de root van de gemounte map, dus voeg dat toe aan .gitignore. En na een pull leest update_index alleen wat veranderd is opnieuw, dus het actueel houden van de index kost één oproep.

Cursor en VS Code

Dezelfde container werkt in elke MCP‑client. In VS Code kan een workspace‑bestand .vscode/mcp.json elke geopende map mounten, zodat de index het project volgt:

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

Cursor gebruikt dezelfde command en args onder mcpServers in .cursor/mcp.json. Commit het configuratie‑bestand en elke ontwikkelaar in het project krijgt de tool; houd de index zelf buiten git.

Waarom niet eerst alles naar tekst converteren?

Dat kan: laat de agent elke PDF converteren wanneer hij die nodig heeft, of controleer Markdown‑kopieën in de repository. Beide werken voor een handvol bestanden. De index doet de conversie één keer, houdt deze actueel met één oproep, en beantwoordt welke file relevant is voordat de agent iets leest, wat de context van een lange sessie klein houdt. De engine erachter is GroupDocs.Search, die Office‑ en PDF‑documenten direct leest in plaats van via een converter die je moet onderhouden.

Eerlijke beperkingen

  • In evaluatiemodus bevat een index maximaal 100 documenten en een zoekopdracht geeft maximaal 10 resultaten; roep eerst get_license_status aan.
  • Full‑text, niet semantisch: de agent moet de woorden gebruiken die de documenten gebruiken, of varianten proberen.
  • Geen OCR: een gescande specificatieblad zonder tekstlaag wordt alleen geïndexeerd op basis van de bestandseigenschappen.
  • Alleen Docker. Op Linux voeg --user "$(id -u):$(id -g)" toe zodat de container de index kan schrijven naar een repository die jij bezit.

FAQ

Kan Claude Code PDF‑bestanden in mijn repository lezen?
Niet met grep. Met de GroupDocs.Search MCP‑server kan hij ze lokaal doorzoeken en citeren, zonder ze eerst te converteren.

Werkt het ook in Cursor en VS Code?
Ja. Gebruik dezelfde docker run‑argumenten in .cursor/mcp.json of .vscode/mcp.json; VS Code kan ${workspaceFolder} mounten.

Zal de index in mijn commits terechtkomen?
Alleen als je het toestaat. Voeg .groupdocs-search-index/ toe aan .gitignore.

Dieper duiken