Twój agent programistyczny jest bardzo dobry w znajdowaniu rzeczy w repozytorium, o ile są to teksty. Zapytaj Claude Code lub Cursor, co karta danych czujnika mówi o temperaturze pracy, a on przeszukuje, nie znajduje nic i albo zgaduje, albo się poddaje, ponieważ karta danych jest w formacie PDF, a rekord decyzji jest plikiem Word. GroupDocs.Search.Mcp działa lokalnie w Dockerze i daje agentowi pełnotekstowy indeks tych dokumentów, z tą samą pętlą „szukaj‑następnie‑czytaj”, której już używa do kodu:

Zindeksuj folder docs, a potem powiedz mi, co karta danych czujnika mówi o temperaturze pracy i który ADR zdecydował o przechowywaniu telemetrycznym.

Wersja krok‑po‑kroku z konfiguracją i rozwiązywaniem problemów znajduje się w dokumentacji: How to let Claude Code or Cursor search the PDFs and Word documents in a repository.

Dlaczego grep zwraca pusty wynik?

Ponieważ PDF i DOCX nie przechowują swoich słów jako zwykły tekst. DOCX jest archiwum zip; PDF kompresuje swoje strumienie tekstowe. Przeszukujesz je bajt po bajcie i słowa po prostu nie istnieją. Przetestowaliśmy to na małym repozytorium: jednej karcie danych PDF, rekordzie decyzji architektonicznej i dokumencie wymagań w formacie DOCX oraz pliku źródłowym.

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

Jedynym trafieniem jest komentarz w kodzie wskazujący na dokument, którego agent nie może odczytać. To jest luka: powód stałej, decyzja projektowa, wymóg testowy często znajdują się właśnie w tych plikach.

Co się zmienia dzięki indeksowi?

Agent otrzymuje narzędzie do pobierania dokumentów. Zarejestruj serwer z katalogu głównego repozytorium, aby repozytorium zostało zamontowane jako folder przechowywania:

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

Następnie te same pytania zwracają odpowiedzi. Oto co serwer zwrócił w naszym testowym repozytorium (ścieżki podane względem katalogu głównego repozytorium):

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

Jedno zapytanie znalazło jednocześnie wymóg i fragment karty danych, co jest rodzajem odwołania krzyżowego, które jest żmudne do wykonania ręcznie i niemożliwe przy użyciu grep. W naszym małym indeksie wyszukiwania zwracały wyniki w 80‑240 ms po pierwszym wywołaniu.

Pętla, którą agent już zna

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 podaje, które pliki, get_text_fragments zwraca pasujące linie z kilkoma słowami kontekstu, a agent cytuje oba. To jest forma grep, rozszerzona do 82 formatów: PDF, DOCX, XLSX, PPTX, HTML, Markdown, a nawet wątków e‑mailowych wyeksportowanych do repozytorium.

Powiedz agentowi, kiedy go używać

Agenci podążają za instrukcjami projektu dotyczącymi momentu sięgania po narzędzie. Trzy linijki w CLAUDE.md lub AGENTS.md robią różnicę między agentem, który próbuje grep, nie udaje mu się i się poddaje, a tym, który najpierw przeszukuje indeks:

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.

Dwa punkty organizacyjne. Indeks jest zapisywany w .groupdocs-search-index/ w katalogu głównym zamontowanego folderu, więc dodaj go do .gitignore. Po pobraniu zmian, update_index odczytuje tylko to, co się zmieniło, więc utrzymanie indeksu w aktualności kosztuje jedno wywołanie.

Cursor i VS Code

Ten sam kontener działa w dowolnym kliencie MCP. W VS Code plik konfiguracyjny workspace .vscode/mcp.json może zamontować dowolny otwarty folder, więc indeks podąża za projektem:

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

Cursor używa tych samych command i args w sekcji mcpServers w .cursor/mcp.json. Zacommituj plik konfiguracyjny i każdy deweloper w projekcie otrzyma narzędzie; trzymaj sam indeks poza Gitem.

Dlaczego nie konwertować wszystkiego najpierw na tekst?

Można: niech agent konwertuje każdy PDF w momencie potrzeby, albo sprawdź kopie w formacie Markdown w repozytorium. Obie metody działają przy kilku plikach. Indeks wykonuje konwersję raz, utrzymuje ją aktualną jednym wywołaniem i odpowiada, który plik jest istotny, zanim agent go odczyta – to krok, który utrzymuje kontekst długiej sesji w małym rozmiarze. Silnikiem stojącym za tym jest GroupDocs.Search, który czyta dokumenty Office i PDF bezpośrednio, a nie przez konwerter, który trzeba utrzymywać.

Szczere ograniczenia

  • W trybie ewaluacji indeks zawiera maksymalnie 100 dokumentów, a wyszukiwanie zwraca maksymalnie 10 wyników; najpierw wywołaj get_license_status.
  • Pełnotekstowy, nie semantyczny: agent musi używać słów, które występują w dokumentach, lub próbować wariantów.
  • Brak OCR: zeskanowana karta danych bez warstwy tekstowej jest indeksowana wyłącznie na podstawie właściwości pliku.
  • Tylko Docker. Na Linuksie dodaj --user "$(id -u):$(id -g)", aby kontener mógł zapisać indeks w repozytorium, które jest Twoje.

FAQ

Czy Claude Code może czytać pliki PDF w moim repozytorium?
Nie przy użyciu grep. Z serwerem GroupDocs.Search MCP może przeszukiwać i cytować je lokalnie, bez wstępnej konwersji.

Czy działa to także w Cursor i VS Code?
Tak. Użyj tych samych argumentów docker run w .cursor/mcp.json lub .vscode/mcp.json; VS Code może zamontować ${workspaceFolder}.

Czy indeks trafi do moich commitów?
Tylko jeśli na to pozwolisz. Dodaj .groupdocs-search-index/ do .gitignore.

Zagłęb się