KoboldCpp RAG MCP Server

# KoboldCpp RAG MCP Server | خادم استرجاع المعرفة لـ KoboldCpp عبر بروتوكول MCP

An enterprise-grade, privacy-first Retrieval-Augmented Generation (RAG) server designed specifically for KoboldCpp. It leverages the Model Context Protocol (MCP) and ChromaDB to grant local Large Language Models direct semantic access to private documents with zero data leaks.

خادم استرجاع معرفة وتوليد معزز (RAG) عالي الأداء ومحلي بالكامل، مصمم لربط نماذج الذكاء الاصطناعي داخل KoboldCpp بمستنداتك وملفاتك الخاصة عبر بروتوكول MCP وقاعدة ChromaDB المتجهة بأمان وخصوصية تامة 100%.

---

## Key Highlights | أبرز المزايا التقنية

- Multi-Format Ingestion: Full text and tabular parsing for PDF, DOCX, XLSX, XLS, CSV, TXT, and Markdown files.

  (دعم شامل لمختلف الصيغ: قراءة واستخراج النصوص والجداول من ملفات الـ PDF، الوورد، الإكسل، ملفات القيم المفصولة بفواصل، والنصوص الخام).

- Local Embedding Engine: Employs sentence-transformers/all-MiniLM-L6-v2 locally via Hugging Face and ONNX runtimes.

  (معالجة متجهات محلية سريعة بالاعتماد على نموذج التضمين القياسي دون الحاجة لطلب واجهات سحابية).

- Persistent Vector Storage: Powered by ChromaDB with persistent disk serialization in a dedicated vector space.

  (تخزين متجهي دائم ومفهرس دلالياً يضمن حفظ المقاطع وقراءتها فورياً من القرص الصلب).

- Autonomous Tool Calling: Directly integrated into KoboldCpp's tool system, allowing models to index files or query context autonomously during conversations.

  (استدعاء ذاتي للأدوات: يستطيع النموذج استكشاف قاعدة المعرفة وفهرسة الملفات الجديدة استجابة لطلب المستخدم داخل المحادثة).

- Zero Data Leakage: All processing, chunking, embedding, and vector querying are confined to the host machine.

  (أمان مطلق وخصوصية كاملة: لا يتم إرسال أي ملف أو متجه إلى الإنترنت).

---

## Architecture & MCP Tools | بنية السيرفر والأدوات المتاحة

The server implements two primary MCP functions executed via standard I/O (stdio):

1. index_documents:

  - Scans the documents/ directory.

  - Cleans and extracts text depending on file extensions.

  - Chunks text into 500-token windows with 50-token overlap to maintain coherence.

  - Generates vector embeddings and upserts data into data_db/.

  - (مسح مجلد المستندات، استخراج المحتوى، تقسيمه إلى مقاطع متداخلة لضمان الترابط الدلالي، ثم تحديث قاعدة المتجهات).

2. query_knowledge_base:

  - Takes a search query string and a top_k retrieval parameter.

  - Computes query embeddings and executes semantic similarity searches.

  - Returns matched chunks enriched with source document metadata.

  - (استقبال استفسارات المستخدم، مطابقتها دلالياً مع المقاطع المخزنة، وإرجاع أدق الفقرات مع الإشارة لاسم المصدر).

---

## Directory Structure | هيكلية المشروع

RAG_KoboldCpp/

│

├── documents/ # Drop your PDFs, Word, and Excel files here

├── data_db/ # Persistent ChromaDB vector storage (Git-ignored)

├── server.py # Core MCP RAG server implementation

├── test_rag.py # Standalone verification and indexing utility

├── run_mcp.bat # Automated environment launcher for KoboldCpp

├── mcp_config.json # MCP client configuration schema for KoboldCpp

├── requirements.txt # Pinned dependency manifest

└── .gitignore # Security exclusions (guards data_db and private files)

---

## Installation & Setup | خطوات التثبيت والتشغيل

1. Clone the Repository | استنساخ المستودع:

  git clone https://github.com/mamq144/KoboldCpp-RAG-MCP.git

  cd KoboldCpp-RAG-MCP

2. Prepare Virtual Environment | إعداد البيئة الافتراضية:

  python -m venv venv

  venv\Scripts\activate

3. Install Dependencies | تثبيت المكتبات:

  pip install -r requirements.txt

4. Index Your Knowledge Base | إضافة المستندات وفهرستها:

  - Place any documents (.pdf, .docx, .xlsx, .txt, etc.) inside the documents folder.

  - Run the manual indexing check:

  python test_rag.py

---

## KoboldCpp Integration | الربط مع KoboldCpp

Option A: Via Command Line (CLI)

Run your KoboldCpp instance with the --mcp flag pointing directly to your JSON configuration:

koboldcpp.exe --model your_model.gguf --gpulayers -1 --mcp "E:\RAG_KoboldCpp\mcp_config.json"

Option B: Via Web GUI (Settings)

1. Launch KoboldCpp and open http://localhost:5001.

2. Navigate to Settings -> Tools -> MCP Tool Calling.

3. Ensure "Enable Toolcalling" and "Automatically Execute Tools" are checked.

4. Verify that "index_documents" and "query_knowledge_base" are listed and enabled.

---

## License | الترخيص

Distributed under the MIT License. See LICENSE for more information.

مرخص تحت مظلة رخصة MIT المفتوحة.