وكيل البرمجة الخاص بك جيد جدًا في العثور على الأشياء في المستودع، طالما أنها نصية. اسأل Claude Code أو Cursor عما تقول ورقة بيانات المستشعر بخصوص درجة الحرارة التشغيلية، سيبحثان، لا يجدان شيئًا، إما يخمنان أو يستسلمان، لأن ورقة البيانات هي PDF وسجل القرار هو ملف Word. يعمل GroupDocs.Search.Mcp محليًا في Docker ويمنح الوكيل فهرسًا نصيًا كاملًا لتلك المستندات، مع حلقة البحث ثم القراءة نفسها التي يستخدمها بالفعل للشفرة:

فهرس مجلد المستندات، ثم أخبرني ما تقول ورقة بيانات المستشعر عن درجة الحرارة التشغيلية وأي ADR قرر تخزين القياسات.

الإصدار خطوة بخطوة مع التكوين واستكشاف الأخطاء موجود في الوثائق: How to let Claude Code or Cursor search the PDFs and Word documents in a repository.

لماذا تعود نتيجة 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. وبعد السحب، يعيد 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)" حتى يتمكن الحاوية من كتابة الفهرس في مستودع تملكه.

الأسئلة المتكررة

هل يستطيع 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.

تعمق أكثر