Su agente de codificación es muy bueno encontrando cosas en un repositorio, siempre que sean texto. Pregunte a Claude Code o Cursor qué dice la hoja de datos del sensor sobre la temperatura de operación y él usa grep, no encuentra nada y o bien adivina o se rinde, porque la hoja de datos es un PDF y el registro de decisiones es un archivo Word. GroupDocs.Search.Mcp se ejecuta localmente en Docker y le brinda al agente un índice de texto completo sobre esos documentos, con el mismo bucle de buscar‑luego‑leer que ya usa para el código:

Indexa la carpeta docs, luego dime qué dice la hoja de datos del sensor sobre la temperatura de operación y qué ADR decidió el almacenamiento de telemetría.

La versión paso a paso con configuración y solución de problemas está en la documentación: Cómo permitir que Claude Code o Cursor busquen los PDFs y documentos Word en un repositorio.

¿Por qué grep no devuelve resultados?

Porque PDF y DOCX no almacenan sus palabras como texto plano. Un DOCX es un archivo zip; un PDF comprime sus flujos de texto. Buscar byte a byte en cualquiera de ellos y las palabras no están. Lo probamos con un repositorio pequeño: una hoja de datos en PDF, un registro de decisiones de arquitectura y un documento de requisitos en DOCX, y un archivo fuente.

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

El único hallazgo es un comentario de código que apunta al documento que el agente no puede leer. Esa es la brecha: la razón detrás de una constante, la decisión detrás de un diseño, el requisito detrás de una prueba a menudo se encuentran precisamente en esos archivos.

¿Qué cambia con un índice?

El agente obtiene una herramienta de recuperación para documentos. Registre el servidor desde la raíz del repositorio, de modo que el repositorio se monte como la carpeta de almacenamiento:

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

Luego las mismas preguntas devuelven respuestas. Esto es lo que el servidor devolvió en nuestro repositorio de prueba (las rutas se muestran relativas a la raíz del repositorio):

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

Una consulta encontró el requisito y la línea de la hoja de datos juntos, lo cual es el tipo de referencia cruzada que es tediosa de hacer a mano e imposible con grep. En nuestro índice pequeño, las búsquedas devolvieron resultados en 80 a 240 milisegundos después de la primera llamada.

El bucle que el agente ya conoce

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 qué archivos, get_text_fragments devuelve las líneas coincidentes con unas pocas palabras de contexto, y el agente cita ambos. Es la forma de grep, ampliada a 82 formatos: PDF, DOCX, XLSX, PPTX, HTML, Markdown, incluso los hilos de correo electrónico que alguien exportó al repositorio.

Indique al agente cuándo usarlo

Los agentes siguen las instrucciones del proyecto sobre cuándo recurrir a una herramienta. Tres líneas en CLAUDE.md o AGENTS.md marcan la diferencia entre un agente que intenta grep, falla y se rinde, y uno que busca primero en el índice:

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.

Dos puntos de mantenimiento. El índice se escribe en .groupdocs-search-index/ en la raíz de la carpeta montada, así que añádalo a .gitignore. Y después de un pull, update_index vuelve a leer solo lo que cambió, por lo que mantener el índice actualizado cuesta una llamada.

Cursor y VS Code

El mismo contenedor funciona en cualquier cliente MCP. En VS Code, un espacio de trabajo .vscode/mcp.json puede montar cualquier carpeta que esté abierta, de modo que el índice siga al proyecto:

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

Cursor usa el mismo command y args bajo mcpServers en .cursor/mcp.json. Confirme el archivo de configuración y cada desarrollador del proyecto obtendrá la herramienta; mantenga el propio índice fuera de git.

¿Por qué no convertir todo a texto primero?

Puede: hacer que el agente convierta cada PDF cuando lo necesite, o verificar copias en Markdown en el repositorio. Ambos funcionan para un puñado de archivos. El índice realiza la conversión una sola vez, la mantiene actualizada con una llamada, y responde qué archivo importa antes de que el agente lea cualquiera, lo cual es el paso que mantiene pequeño el contexto de una sesión larga. El motor detrás de ello es GroupDocs.Search, que lee documentos de Office y PDF directamente en lugar de hacerlo a través de un conversor que usted debe mantener.

Límites honestos

  • En modo de evaluación un índice contiene como máximo 100 documentos y una búsqueda devuelve como máximo 10; llame a get_license_status primero.
  • Texto completo, no semántico: el agente debe usar las palabras que usan los documentos, o probar variantes.
  • Sin OCR: una hoja de datos escaneada sin capa de texto se indexa solo por sus propiedades de archivo.
  • Solo Docker. En Linux, añada --user "$(id -u):$(id -g)" para que el contenedor pueda escribir el índice en un repositorio que le pertenece.

Preguntas frecuentes

¿Puede Claude Code leer archivos PDF en mi repositorio?
No con grep. Con el servidor GroupDocs.Search MCP puede buscarlos y citarlos, localmente, sin convertirlos primero.

¿Funciona también en Cursor y VS Code?
Sí. Use los mismos argumentos docker run en .cursor/mcp.json o .vscode/mcp.json; VS Code puede montar ${workspaceFolder}.

¿El índice terminará en mis commits?
Solo si lo permite. Añada .groupdocs-search-index/ a .gitignore.

Profundizar