Ваш кодовий агент дуже добре знаходить речі в репозиторії, доки це текст. Запитайте Claude Code або Cursor, що вказано в даташиті датчика щодо робочої температури, і він виконає grep, нічого не знайде і або вгадає, або зупиниться, бо даташит – це PDF, а запис рішення – Word‑файл. GroupDocs.Search.Mcp працює локально в Docker і надає агенту повнотекстовий індекс цих документів, використовуючи той самий цикл «шукати‑потім‑читати», який він вже застосовує для коду:

Індексувати папку docs, а потім сказати, що в даташиті датчика зазначено про робочу температуру і який ADR вирішив питання зберігання телеметрії.

Крок‑за‑кроком версія з налаштуванням і усуненням проблем описана в документації: Як дозволити Claude Code або Cursor шукати PDF‑и та Word‑документи в репозиторії.

Чому grep повертає порожній результат?

Тому що PDF і DOCX не зберігають свої слова як простий текст. DOCX – це zip‑архів; PDF стискає свої текстові потоки. Шукати їх байт за байтом – слів просто немає. Ми протестували це на невеликому репозиторії: один PDF‑даташит, запис архітектурного рішення та документ вимог у DOCX, і файл вихідного коду.

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

Єдиний результат – це коментар у коді, що вказує на документ, який агент не може прочитати. Ось у чому полягає прогалина: причина константи, рішення щодо дизайну, вимога до тесту часто живуть саме в цих файлах.

Що змінюється з індексом?

Агент отримує інструмент пошуку документів. Зареєструйте сервер з кореня репозиторію, щоб репозиторій був змонтований як папка сховища:

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

Тоді ті ж питання повертають відповіді. Ось що сервер повернув у нашому тестовому репозиторії (шляхи показані відносно кореня репозиторію):

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

Один запит знайшов вимогу та рядок даташиту разом, що є типом перехресного посилання, яке важко робити вручну і неможливо за допомогою grep. На нашому маленькому індексі пошук повертався за 80‑240 мілісекунд після першого виклику.

Цикл, який агент вже знає

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 відповідає, які файли містять запит, get_text_fragments повертає рядки з контекстом, і агент цитує обидва. Це розширена форма grep, підтримуюча 82 формати: PDF, DOCX, XLSX, PPTX, HTML, Markdown, навіть листи електронної пошти, експортовані в репозиторій.

Повідомте агенту, коли його використовувати

Агенти дотримуються інструкцій про те, коли слід звертатися до інструменту. Три рядки у CLAUDE.md або AGENTS.md роблять різницю між агентом, який намагається використати grep, зазнає невдачі і здається, і агентом, що спочатку шукає в індексі:

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.

Два організаційних моменту. Індекс записується у .groupdocs-search-index/ у корені змонтованої папки, тому додайте його до .gitignore. Після pull команда update_index перечитує лише змінені файли, тож підтримка індексу в актуальному стані вимагає лише одного виклику.

Cursor та VS Code

Той самий контейнер працює в будь‑якому MCP‑клієнті. У VS Code робочий простір .vscode/mcp.json може змонтувати будь‑яку відкриту папку, тож індекс слідує за проєктом:

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

Cursor використовує ті ж command і args у розділі mcpServers файлу .cursor/mcp.json. Закомітьте файл конфігурації, і кожен розробник у проєкті отримає інструмент; тримайте сам індекс поза git‑ом.

Чому не конвертувати все спочатку в текст?

Можна: змусити агента конвертувати кожен PDF за потреби або перевіряти копії у Markdown у репозиторії. Обидва підходи працюють для невеликої кількості файлів. Індекс виконує конвертацію один раз, підтримує її актуальною одним викликом і відповідає, який файл важливий, ще до того, як агент його прочитає, що зменшує контекст довгої сесії. Двигун за цим – GroupDocs.Search, який читає Office‑ та PDF‑документи безпосередньо, а не через конвертер, який треба підтримувати.

Чесні обмеження

  • У режимі оцінки індекс містить не більше 100 документів, а пошук повертає не більше 10 результатів; спочатку викличте get_license_status.
  • Повнотекстовий, а не семантичний пошук: агент має використовувати саме ті слова, що є в документах, або пробувати варіанти.
  • Без OCR: сканований даташит без текстового шару індексується лише за властивостями файлу.
  • Тільки Docker. На Linux додайте --user "$(id -u):$(id -g)", щоб контейнер міг записати індекс у ваш репозиторій.

FAQ

Чи може Claude Code читати PDF‑файли у моєму репозиторії?
Не за допомогою grep. За допомогою сервера GroupDocs.Search MCP агент може шукати та цитувати їх локально, без попередньої конвертації.

Чи працює це і в Cursor, і у VS Code?
Так. Використайте ті ж аргументи docker run у .cursor/mcp.json або .vscode/mcp.json; VS Code може змонтувати ${workspaceFolder}.

Чи потрапить індекс у мої коміти?
Лише якщо ви дозволите це. Додайте .groupdocs-search-index/ до .gitignore.

Детальніше