Agent lập trình của bạn rất giỏi trong việc tìm kiếm các thứ trong một kho lưu trữ, miễn là chúng là văn bản. Hãy hỏi Claude Code hoặc Cursor về những gì tờ dữ liệu cảm biến nói về nhiệt độ hoạt động và nó sẽ grep, không tìm thấy gì, và hoặc đoán hoặc bỏ cuộc, vì tờ dữ liệu là PDF và bản ghi quyết định là tệp Word. GroupDocs.Search.Mcp chạy cục bộ trong Docker và cung cấp cho agent một chỉ mục toàn văn trên các tài liệu đó, với vòng lặp tìm kiếm‑sau‑đọc mà nó đã sử dụng cho mã:

Lập chỉ mục thư mục docs, sau đó cho tôi biết tờ dữ liệu cảm biến nói gì về nhiệt độ hoạt động và ADR nào đã quyết định việc lưu trữ dữ liệu truyền thông.

Phiên bản từng bước với cấu hình và khắc phục sự cố có trong tài liệu: How to let Claude Code or Cursor search the PDFs and Word documents in a repository.

Tại sao grep lại trả về rỗng?

Bởi vì PDF và DOCX không lưu trữ các từ của chúng dưới dạng văn bản thuần. Một DOCX là một kho lưu trữ zip; một PDF nén các luồng văn bản của nó. Tìm kiếm từng byte một và các từ không có ở đó. Chúng tôi đã thử nghiệm với một kho lưu trữ nhỏ: một tờ dữ liệu PDF, một bản ghi quyết định kiến trúc và một tài liệu yêu cầu ở định dạng DOCX, và một tệp nguồn.

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

Kết quả duy nhất là một chú thích trong mã chỉ đến tài liệu mà agent không thể đọc. Đó là khoảng trống: lý do đằng sau một hằng số, quyết định đằng sau một thiết kế, yêu cầu đằng sau một bài kiểm tra thường tồn tại chính trong những tệp đó.

Điều gì thay đổi khi có chỉ mục?

Agent nhận được một công cụ truy xuất cho tài liệu. Đăng ký máy chủ từ thư mục gốc của kho lưu trữ, để kho lưu trữ được gắn làm thư mục lưu trữ:

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

Sau đó các câu hỏi giống nhau sẽ trả về câu trả lời. Đây là những gì máy chủ trả về trong kho thử nghiệm của chúng tôi (đường dẫn được hiển thị tương đối so với thư mục gốc của kho lưu trữ):

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

Một truy vấn đã tìm thấy yêu cầu và dòng trong tờ dữ liệu cùng nhau, đó là kiểu tham chiếu chéo mà việc thực hiện thủ công rất tốn công và không thể làm được với grep. Trên chỉ mục nhỏ của chúng tôi, các tìm kiếm trả về trong 80 đến 240 miligiây sau lần gọi đầu tiên.

Vòng lặp mà agent đã biết

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 trả lời những tệp nào, get_text_fragments trả về các dòng khớp kèm một vài từ ngữ cảnh, và agent trích dẫn cả hai. Nó là dạng của grep, mở rộng sang 82 định dạng: PDF, DOCX, XLSX, PPTX, HTML, Markdown, thậm chí các chuỗi email mà ai đó đã xuất ra trong repo.

Hướng dẫn agent khi nào nên sử dụng

Agents tuân theo hướng dẫn dự án về thời điểm nên dùng công cụ. Ba dòng trong CLAUDE.md hoặc AGENTS.md tạo ra sự khác biệt giữa một agent cố gắng dùng grep, thất bại và bỏ cuộc, và một agent tìm kiếm trong chỉ mục trước:

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.

Hai điểm quản trị. Chỉ mục được ghi vào .groupdocs-search-index/ ở thư mục gốc của thư mục đã gắn, vì vậy hãy thêm nó vào .gitignore. Và sau khi pull, update_index chỉ đọc lại những gì đã thay đổi, vì vậy việc giữ chỉ mục luôn cập nhật chỉ tốn một lần gọi.

Cursor và VS Code

Cùng một container hoạt động trong bất kỳ client MCP nào. Trong VS Code, một workspace .vscode/mcp.json có thể gắn bất kỳ thư mục nào đang mở, vì vậy chỉ mục sẽ theo dự án:

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

Cursor sử dụng cùng command và args dưới mcpServers trong .cursor/mcp.json. Commit file cấu hình và mọi nhà phát triển trong dự án sẽ có công cụ; giữ chỉ mục ra ngoài git.

Tại sao không chuyển mọi thứ sang văn bản trước?

Bạn có thể: để agent chuyển đổi mỗi PDF khi cần, hoặc kiểm tra các bản sao Markdown trong kho. Cả hai cách đều hoạt động với một vài tệp. Chỉ mục thực hiện chuyển đổi một lần, giữ nó cập nhật bằng một lần gọi, và trả lời tệp nào quan trọng trước khi agent đọc bất kỳ tệp nào, đó là bước giúp giữ ngữ cảnh của một phiên dài nhỏ gọn. Động cơ phía sau là GroupDocs.Search, nó đọc trực tiếp các tài liệu Office và PDF thay vì qua một bộ chuyển đổi mà bạn phải duy trì.

Giới hạn thực tế

  • Trong chế độ đánh giá, một chỉ mục chứa tối đa 100 tài liệu và một tìm kiếm trả về tối đa 10; hãy gọi get_license_status trước.
  • Toàn văn, không ngữ nghĩa: agent phải dùng những từ mà tài liệu sử dụng, hoặc thử các biến thể.
  • Không có OCR: một tờ dữ liệu được quét mà không có lớp văn bản chỉ được lập chỉ mục dựa trên thuộc tính tệp.
  • Chỉ hỗ trợ Docker. Trên Linux, thêm --user "$(id -u):$(id -g)" để container có thể ghi chỉ mục vào kho lưu trữ mà bạn sở hữu.

Câu hỏi thường gặp

Claude Code có thể đọc tệp PDF trong kho lưu trữ của tôi không?
Không với grep. Với máy chủ GroupDocs.Search MCP, nó có thể tìm kiếm và trích dẫn chúng, cục bộ, mà không cần chuyển đổi trước.

Nó có hoạt động trong Cursor và VS Code không?
Có. Sử dụng cùng các đối số docker run trong .cursor/mcp.json hoặc .vscode/mcp.json; VS Code có thể gắn ${workspaceFolder}.

Chỉ mục sẽ xuất hiện trong các commit của tôi chứ?
Chỉ nếu bạn cho phép. Thêm .groupdocs-search-index/ vào .gitignore.

Đi sâu hơn