Seu agente de codificação é muito bom em encontrar coisas em um repositório, contanto que sejam texto. Pergunte ao Claude Code ou ao Cursor o que a ficha técnica do sensor diz sobre a temperatura de operação e ele usa grep, não encontra nada e ou tenta adivinhar ou desiste, porque a ficha técnica está em PDF e o registro de decisão está em um arquivo Word. GroupDocs.Search.Mcp roda localmente em Docker e fornece ao agente um índice de texto completo sobre esses documentos, com o mesmo ciclo de buscar‑então‑ler que ele já usa para código:

Indexe a pasta docs, então me diga o que a ficha técnica do sensor diz sobre a temperatura de operação e qual ADR decidiu o armazenamento de telemetria.

A versão passo a passo com configuração e solução de problemas está na documentação: Como deixar o Claude Code ou o Cursor pesquisar os PDFs e documentos Word em um repositório.

Por que o grep não retorna nada?

Porque PDF e DOCX não armazenam suas palavras como texto simples. Um DOCX é um arquivo zip; um PDF comprime seus fluxos de texto. Pesquisar byte a byte em qualquer um deles e as palavras não estarão lá. Testamos isso com um repositório pequeno: um PDF de ficha técnica, um registro de decisão de arquitetura e um documento de requisitos em DOCX, e um arquivo fonte.

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

O único resultado é um comentário no código apontando para o documento que o agente não consegue ler. Essa é a lacuna: a razão por trás de uma constante, a decisão por trás de um design, o requisito por trás de um teste costumam estar exatamente nesses arquivos.

O que muda com um índice?

O agente obtém uma ferramenta de recuperação para documentos. Registre o servidor a partir da raiz do repositório, de modo que o repositório seja montado como a pasta de armazenamento:

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

Então as mesmas perguntas retornam respostas. Isto é o que o servidor devolveu em nosso repositório de teste (caminhos mostrados relativos à raiz do repositório):

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

Uma consulta encontrou o requisito e a linha da ficha técnica juntos, que é o tipo de referência cruzada que é tediosa de fazer manualmente e impossível com grep. No nosso pequeno índice, as buscas retornaram em 80 a 240 milissegundos após a primeira chamada.

O loop que o agente já conhece

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 responde quais arquivos, get_text_fragments devolve as linhas correspondentes com algumas palavras de contexto, e o agente cita ambos. É a forma do grep, estendida para 82 formatos: PDF, DOCX, XLSX, PPTX, HTML, Markdown, até mesmo os tópicos de e‑mail que alguém exportou para o repositório.

Diga ao agente quando usá‑lo

Os agentes seguem instruções do projeto sobre quando recorrer a uma ferramenta. Três linhas em CLAUDE.md ou AGENTS.md fazem a diferença entre um agente que tenta grep, falha e desiste, e um que pesquisa o índice primeiro:

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.

Dois pontos de manutenção. O índice é gravado em .groupdocs-search-index/ na raiz da pasta montada, então adicione isso ao .gitignore. E após um pull, update_index relê apenas o que mudou, de modo que manter o índice atualizado custa uma chamada.

Cursor e VS Code

O mesmo contêiner funciona em qualquer cliente MCP. No VS Code, um workspace .vscode/mcp.json pode montar a pasta que estiver aberta, de modo que o índice siga o projeto:

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

O Cursor usa o mesmo command e args sob mcpServers em .cursor/mcp.json. Faça commit do arquivo de configuração e todo desenvolvedor do projeto terá a ferramenta; mantenha o índice fora do git.

Por que não converter tudo para texto primeiro?

Você pode: fazer o agente converter cada PDF quando precisar, ou verificar cópias em Markdown no repositório. Ambos funcionam para um pequeno número de arquivos. O índice faz a conversão uma única vez, a mantém atual com uma chamada e responde qual arquivo importa antes que o agente o leia, que é a etapa que mantém o contexto de uma sessão longa pequeno. O motor por trás disso é GroupDocs.Search, que lê documentos Office e PDF diretamente, sem passar por um conversor que você teria que manter.

Limites honestos

  • No modo de avaliação um índice contém no máximo 100 documentos e uma busca retorna no máximo 10; chame get_license_status primeiro.
  • Texto completo, não semântico: o agente tem que usar as palavras que os documentos usam, ou tentar variantes.
  • Sem OCR: uma ficha técnica escaneada sem camada de texto é indexada apenas pelas propriedades do arquivo.
  • Apenas Docker. No Linux, adicione --user "$(id -u):$(id -g)" para que o contêiner possa gravar o índice em um repositório que você possui.

FAQ

O Claude Code pode ler arquivos PDF no meu repositório?
Não com grep. Com o servidor GroupDocs.Search MCP ele pode pesquisar e citar esses arquivos, localmente, sem convertê‑los primeiro.

Isso funciona no Cursor e no VS Code também?
Sim. Use os mesmos argumentos docker run em .cursor/mcp.json ou .vscode/mcp.json; o VS Code pode montar ${workspaceFolder}.

O índice vai acabar nos meus commits?
Só se você permitir. Adicione .groupdocs-search-index/ ao .gitignore.

Aprofunde