Your coding agent은 텍스트인 한 저장소에서 항목을 찾는 데 매우 뛰어납니다. 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밀리초 안에 검색 결과가 반환되었습니다.

에이전트가 이미 알고 있는 루프

사용자              에이전트                         검색 MCP 서버
 |  "데이터시트에 I2C 주소에 대해 무엇이라고 적혀 있나요?"         |
 |---------------->|                                           |
 |                 |-- search {"query":"I2C"} --------------->|
 |                 |<- requirements-v2.docx,                   |
 |                 |   tmp117-sensor-datasheet.pdf ------------|
 |                 |-- get_text_fragments {"query":"I2C"} --->|
 |                 |<- "...ADD0 pin to GND gives 0x48..." -----|
 |<- "ADD0 핀을 GND에 연결하면 0x48, V+에 연결하면 0x49 (데이터시트, p.1);      |
 |    REQ-15는 버스를 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는 .cursor/mcp.json의 mcpServers 아래에서 동일한 command와 args를 사용합니다. 설정 파일을 커밋하면 프로젝트의 모든 개발자가 도구를 사용할 수 있으며, 인덱스 자체는 git에 포함되지 않도록 유지하세요.

모든 것을 먼저 텍스트로 변환하지 않는 이유는?

가능합니다: 에이전트가 필요할 때마다 각 PDF를 변환하도록 하거나, Markdown 복사본을 저장소에 두는 방법입니다. 두 방법 모두 소수의 파일에 대해서는 작동합니다. 인덱스는 한 번 변환을 수행하고 한 번의 호출로 최신 상태를 유지하며, 에이전트가 파일을 읽기 전에 어떤 파일이 중요한지 답변합니다. 이는 긴 세션의 컨텍스트를 작게 유지하는 단계입니다. 그 뒤엔 GroupDocs.Search 엔진이 사용되며, 이는 변환기를 별도로 유지할 필요 없이 Office 및 PDF 문서를 직접 읽습니다.

솔직한 제한 사항

  • 평가 모드에서는 인덱스가 최대 100개의 문서만 보관하고 검색 결과는 최대 10개만 반환합니다; 먼저 get_license_status를 호출하세요.
  • 전체 텍스트 검색이며, 의미 기반이 아닙니다: 에이전트는 문서가 사용하는 단어를 그대로 사용하거나 변형을 시도해야 합니다.
  • OCR 없음: 텍스트 레이어가 없는 스캔된 데이터시트는 파일 속성만으로 인덱싱됩니다.
  • Docker 전용. Linux에서는 --user "$(id -u):$(id -g)" 옵션을 추가하여 컨테이너가 소유한 저장소에 인덱스를 쓸 수 있게 합니다.

자주 묻는 질문

Claude Code가 내 저장소의 PDF 파일을 읽을 수 있나요?
grep으로는 불가능합니다. GroupDocs.Search MCP 서버를 사용하면 로컬에서 PDF를 검색하고 인용할 수 있으며, 먼저 변환할 필요가 없습니다.

Cursor와 VS Code에서도 작동하나요?
예. .cursor/mcp.json 또는 .vscode/mcp.json에 동일한 docker run 인자를 사용하면 됩니다; VS Code는 ${workspaceFolder}를 마운트할 수 있습니다.

인덱스가 내 커밋에 포함될까요?
허용하는 경우에만 포함됩니다. .groupdocs-search-index/를 .gitignore에 추가하세요.

더 깊이 들어가기