MCP Local RAG

Geliştiriciler için yerel RAG, MCP veya CLI aracılığıyla. Tam teknik terimler için anahtar kelime güçlendirmesi ile anlamsal arama — tamamen özel, kurulum sıfır.

Özellikler

• Anahtar kelime güçlendirmesi ile anlamsal arama Önce vektör araması, ardından anahtar kelime eşleşmesi tam eşleşmeleri artırır. useEffect, hata kodları ve sınıf adları gibi terimler — sadece anlamsal olarak tahmin edilmekten çok daha yüksek sıralanır.

• Akıllı anlamsal bölümleme Belgeleri karakter sayısına göre değil, anlama göre parçalara böler. Doğal konu sınırlarını bulmak için gömme benzerliğini kullanır — ilgili içeriği bir arada tutar ve konular değiştiğinde böler.

• Kalite odaklı sonuç filtreleme Sonuçları keyfi top-K cutoff'ları yerine uygunluk boşluklarına göre gruplandırır. Daha az ama daha güvenilir parçalar alın.

• Tamamen yerel olarak çalışır API anahtarı, bulut veya makinenizden çıkan veriler yok. İlk model indirilmesinden sonra tamamen çevrimdışı çalışır.

• Sıfır kurulum karmaşıklığı Tek npx komutu. Docker, Python, yönetilecek sunucu yok. MCP, CLI veya her ikisini kullanın. İsteğe bağlı Agent Skills, AI asistanlarının daha iyi sorgular oluşturmasına ve sonuçları yorumlamasına yardımcı olur.

Hızlı Başlangıç

BASE_DIR öğesini araştırmak istediğiniz klasöre ayarlayın (veya birden fazla kök için BASE_DIRS — bkz. Yapılandırma). Belgeler yapılandırılan köklerin biri altında yaşamalıdır.

MCP sunucusunu AI kodlama aracınıza ekleyin:

Cursor için — ~/.cursor/mcp.json dosyasına ekleyin:

{
  "mcpServers": {
    "local-rag": {
      "command": "npx",
      "args": ["-y", "mcp-local-rag"],
      "env": {
        "BASE_DIR": "/path/to/your/documents"
      }
    }
  }
}

Codex için — ~/.codex/config.toml dosyasına ekleyin:

[mcp_servers.local-rag]
command = "npx"
args = ["-y", "mcp-local-rag"]

[mcp_servers.local-rag.env]
BASE_DIR = "/path/to/your/documents"

Claude Code için — bu komutu çalıştırın:

claude mcp add local-rag --scope user --env BASE_DIR=/path/to/your/documents -- npx -y mcp-local-rag

Aracınızı yeniden başlatın, ardından kullanmaya başlayın:

Siz: "Ingest api-spec.pdf"
Asistan: Successfully ingested api-spec.pdf (47 chunks created)

Siz: "API belgeleri kimlik doğrulama hakkında ne diyor?"
Asistan: Belgelendirmeye göre, kimlik doğrulama JWT belirteçleriyle OAuth 2.0 kullanır.
          Akış bölüm 3.2'de açıklanmıştır...

Veya doğrudan CLI olarak kullanın — MCP sunucusu gerekmez:

npx mcp-local-rag ingest ./docs/
npx mcp-local-rag query "authentication API"

Bu kadar. Docker, Python, sunucu kurulumu yok.

Neden Var

AI'ın belgelerinizi aramasını istiyorsunuz — teknik spesifikasyonlar, araştırma makaleleri, iç belgeler. Ancak çoğu çözüm dosyalarınızı harici API'lere gönderir.

Gizlilik. Belgeleriniz hassas veriler içerebilir. Bu tamamen yerel olarak çalışır.

Maliyet. Harici gömme API'leri kullanım başına ücret alır. İlk model indirilmesinden sonra bu ücretsizdir.

Çevrimdışı. Kurulumdan sonra internet olmadan çalışır.

Kod araması. Saf anlamsal arama useEffect veya ERR_CONNECTION_REFUSED gibi kesin terimleri kaçırır. Anahtar kelime güçlendirmesi hem anlam hem de tam eşleşmeleri yakalar.

Agent gerçekliği. Uygulamada, birçok AI ortamı öncelikle araç çağrısını kullanır. CLI desteği ve Agent Skills, tam MCP entegrasyonu olmasa bile aynı iş akışlarını kullanılabilir hale getirir.

Kullanım

mcp-local-rag iki arayüz sağlar: AI kodlama araçları için bir MCP sunucusu ve terminalde doğrudan kullanım için bir CLI.

MCP ile Kullanım

MCP sunucusu 7 araç sağlar: ingest_file, ingest_data, query_documents, read_chunk_neighbors, list_files, delete_file, status.

Belgeleri İçe Aktarma

"Ingest the document at /Users/me/docs/api-spec.pdf"

PDF, DOCX, TXT ve Markdown'ı destekler. Sunucu metni çıkarır, parçalara böler, gömmeleri yerel olarak oluşturur ve her şeyi yerel bir vektör veritabanında depolar.

Aynı dosyayı yeniden içe aktarmak eski versiyonu otomatik olarak değiştirir.

Şekillerle PDF'leri içe aktarma (görsel modu)

Grafikler, tablolar veya diyagramlar içeren PDF'ler, isteğe bağlı olarak belge dizinine yerel VLM tarafından oluşturulan başlıklar ekleyebilir ve görsel içeriği aynı vektör + FTS işlem hattında aranabilir bir temsile verir. Başlıklar yardımcı metin — görüntü araması, OCR ve şekil dökümleme değildir.

MCP aracılığıyla:

"Ingest /Users/me/docs/api-spec.pdf with visual: true"

CLI aracılığıyla:

npx mcp-local-rag ingest ./docs/spec.pdf --visual

Her başlık, sayfa gövdesi parçalarının yanında [Visual content on page N: …] zarfı ile kendi parçası olarak yayınlanır. Mevcut gömmeci ve FTS dizininden geçer — şema farkı, ayrı dizin yoktur.

Görsel modu opt-in; normal içe aktarma VLM yüklemez. Sayfa başına VLM hataları tolere edilir — o sayfa yalnızca metinle ilerler.

Görsel kalite profili seçme

Görsel modu iki profil sunar, her içe aktarma çağrısı başına seçilir:

Profil	Model	Disk (önbellek)	Sayfa başına ılımlama	Uygun
fast (varsayılan)	HuggingFaceTB/SmolVLM-256M-Instruct	~250 MB	temel	Hafif görsel dizinleme, hızlı ilk çalıştırma kurulumu.
quality	onnx-community/Qwen2.5-VL-3B-Instruct-ONNX	~2,9 GB	~2× fast	Başlık sadakati önem taşıyan eksen etiketleri, panel alt-etiketleri, açıklamalar gibi görüntü içi metni olan şekiller.

Yukarıdaki sayılar, proje sondası PDF'leri üzerinde geliştirme sırasında CPU'da ölçülür; model güncellemeleriyle değişebilir veya donanımınızda farklı olabilir.

MCP aracılığıyla — ingest_file isteğe bağlı bir visualQuality parametresini kabul eder (enum: 'fast' | 'quality', varsayılan 'fast'; visual yanlış olduğunda yoksayılır):

"Ingest /Users/me/docs/research-paper.pdf with visual: true and visualQuality: 'quality'"

CLI aracılığıyla — --visual-quality fast|quality (varsayılan fast; --visual olmadığında sessizce yoksayılır):

npx mcp-local-rag ingest ./docs/research-paper.pdf --visual --visual-quality quality

Profil modeli tanımlayıcıları ve nicemleme varyantları sürüm başına sabitlenir. Her iki profil aynı CACHE_DIR paylaşır (varsayılan: ./models/); her profildeki ilk çalıştırma modeli indirir.

v0.14.0 sürümünden davranış değişikliği: Başlıklar artık chunking öncesi sayfa metnine eklenmek yerine ayrılmış parçalar olarak yayınlanır. Yan etki olarak, görsel içe aktarımlar için metadata.fileSize artık başlık karakter sayısını içermez — yalnızca çıkarma sonrası gövde uzunluğunu ölçer. Temel alınan PDF değişmez; görsel içe aktarılan PDF'ler için bildirilen fileSize sürüm sınırında küçülebilir.

Güvenlik notu: Görsel başlıklar PDF içeriklerinden türetilir ve saldırgı tarafından kontrol edilen metni miras alabilir. Aşağı akış LLM tüketicileri alınan parçaları güvenilmez veriler olarak değerlendirilmelidir, talimatlar olarak değil. [Visual content on page N: …] zarfı, tüketicilerin başlık metnini ayırt etmesine yardımcı olur.

HTML İçeriğini İçe Aktarma

AI asistanınız tarafından alınan HTML içeriğini (web getirme, curl, tarayıcı araçları vb. aracılığıyla) içe aktarmak için ingest_data kullanın:

"Fetch https://example.com/docs and ingest the HTML"

Sunucu, Readability kullanarak ana içeriği çıkarır (navigasyon, reklamlar vb. kaldırır), Markdown'a dönüştürür ve dizine ekler. Mükemmel:

• Web belgelendirmesi
• AI asistanı tarafından alınan HTML
• Pano içeriği

HTML otomatik olarak temizlenir — boilerplate değil, makale içeriğini alırsınız.

Not: RAG sunucusu web içeriği getirmez — AI asistanınız bunu alır ve HTML'yi ingest_data öğesine iletir. Bu, sunucuyu tamamen yerel tutarken asistanınızın erişebileceği herhangi bir içeriği dizine ekleyebilmenizi sağlar. Harici içerik içe aktarırken web sitesi hizmet şartlarına ve telif hakkına saygı gösterin.

Belgeleri Arama

"API belgeleri kimlik doğrulama hakkında ne diyor?"
"Hız sınırlaması hakkında bilgi bulun"
"Hata işleme en iyi uygulamaları arayın"

Arama, anahtar kelime güçlendirmesi ile anlamsal benzerlik kullanır. Bu, useEffect tam eşleşmeleri bulur, sadece anlamsal olarak benzer React konseptleri değil.

Sonuçlar metin içeriği, kaynak dosya, belge başlığı ve uygunluk puanını içerir. Belge başlığı her parça için bağlam sağlar, bir sonucun hangi belgeye ait olduğunu tanımlamaya yardımcı olur. limit (1-20, varsayılan 10) ile sonuç sayısını ayarlayın.

Bir Sonucun Çevresindeki Bağlamı Genişletme

Bir arama sonucu daha fazla çevre bağlamı gerektiğinde, çevresindeki parçaları okumak için read_chunk_neighbors kullanın:

"Bu kimlik doğrulama sonucu uygun görünüyor — tam açıklama için çevre parçalarını oku"

Arama sonucundan filePath ve chunkIndex iletişim kurun. Yanıt hedef parçayı (isTarget: true işaretli) ve komşularını, parça dizinine göre sıralanmış olarak içerir. Varsayılan olarak 2 parça öncesi ve 2 sonrası (her birine kadar 50'ye ayarlanabilir).

Dosyaları Yönetme

"Liste yapılandırılan temel dizinlerdeki tüm dosyalar ve içe aktarılan durumları"   # Ne dizine alındığını gör
"RAG'den old-spec.pdf sil"     # Bir dosya kaldır
"RAG sunucu durumunu göster"           # Sistem durumunu kontrol et

CLI Olarak Kullanma

Tüm MCP araçları aynı zamanda CLI komutları olarak da mevcuttur — MCP sunucusu gerekmez:

npx mcp-local-rag ingest ./docs/               # Toplu dosya içe aktarma
npx mcp-local-rag query "authentication API"    # Belgeleri ara
npx mcp-local-rag read-neighbors --file-path /abs/path.md --chunk-index 5  # Bağlamı genişlet
npx mcp-local-rag list                          # İçe aktarma durumunu göster
npx mcp-local-rag status                        # Veritabanı istatistikleri
npx mcp-local-rag delete ./docs/old.pdf         # İçeriği kaldır
npx mcp-local-rag delete --source "https://..."  # Kaynak URL'ye göre kaldır

query, read-neighbors, list, status ve delete stdout'a JSON çıkarmak (ör. | jq). ingest stderr'e ilerleme çıkarmak. Genel seçenekler (--db-path, --cache-dir, --model-name) komuttan önce gelir. Ayrıntılar için npx mcp-local-rag --help çalıştırın.

⚠️ CLI, MCP istemci yapılandırmanızı (mcp.json, config.toml vb.) okumuyor. Aşağıda gösterildiği gibi CLI'yi bayraklar veya ortam değişkenleri aracılığıyla yapılandırın.

Yapılandırma

CLI bayrakları — genel seçenekler komuttan önce, komut seçenekleri sonra:

npx mcp-local-rag --db-path ./my-db query "auth" --base-dir ./docs

--base-dir bayrağı ingest ve list üzerinde tekrarlanabilir; kök başına bir kez iletişim kurun:

npx mcp-local-rag ingest --base-dir ./docs --base-dir ./specs ./docs/readme.md
npx mcp-local-rag list --base-dir ./docs --base-dir ./specs

ingest için konumsal yol yapılandırılan köklerden birinin içinde oturmalıdır. En az bir --base-dir sağlandığında, CLI kökleri herhangi bir ortam-var kökünü değiştirir (birleştirme yoktur).

Ortam değişkenleri — kabuğunuzda ayarlayın:

export DB_PATH=./my-db
export BASE_DIR=./docs
npx mcp-local-rag query "auth"

Birden fazla kök için, BASE_DIRS (JSON dizi boş olmayan yol dizelerinin):

export BASE_DIRS='["/Users/me/Documents/work","/Users/me/Projects/specs"]'
npx mcp-local-rag list

MCP ve CLI arasında yapılandırmayı paylaşma — MCP istemciniz kabuk ortam değişkenlerini miras alırsa, bunları kabuk profilinizde (ör. ~/.zshrc) ayarlayabilirsiniz, böylece her ikisi de aynı değerleri kullanır. Aksi takdirde, bunları MCP yapılandırmanızda da açıkça ayarlayın.

export BASE_DIR=/path/to/your/documents
export DB_PATH=/path/to/lancedb

Yapılandırma bu sırayla çözülür:

1. CLI bayrakları (en yüksek öncelik)
2. Ortam değişkenleri
3. Varsayılanlar

CLI bayraklarının, ortam değişkenlerinin ve varsayılanların tam listesi için bkz. Yapılandırma.

CLI'si yapılandırma (MCP sunucusu yok), AI asistanınızın daha iyi sorgular oluşturmasına ve sonuçları tutarlı bir şekilde yorumlamasına yardımcı olacak Agent Skills yükleyin.

⚠️ CLI --model-name, MCP sunucusunun MODEL_NAME ortam değişkeniyle eşleşmelidir. Mevcut bir veritabanına karşı farklı bir gömme modeli kullanmak uyumsuz vektörler oluşturur, arama kalitesini sessizce düşürür.

Araştırma Tuning

Kullanım durumunuz için bunları ayarlayın:

Değişken	Varsayılan	Açıklama
RAG_HYBRID_WEIGHT	0.6	Anahtar kelime güçlendirme faktörü. 0 = yalnızca anlamsal, daha yüksek = daha güçlü anahtar kelime güçlendirmesi.
RAG_GROUPING	(ayarlanmamış)	En üst grup için similar, üst 2 grup için related.
RAG_MAX_DISTANCE	(ayarlanmamış)	Düşük ilgili sonuçları filtrele (ör. 0.5).
RAG_MAX_FILES	(ayarlanmamış)	Sonuçları en üst N dosya ile sınırla (ör. 1 en iyi dosya için).

Kod odaklı tuning

Kodlar ve API spesifikasyonları için, tam tanımlayıcıların (useEffect, ERR_*, sınıf adları) sıralamaya hakim olması için anahtar kelime güçlendirmesini artırın:

"env": {
  "RAG_HYBRID_WEIGHT": "0.7",
  "RAG_GROUPING": "similar"
}

• 0.7 — dengeli anlamsal + anahtar kelime
• 1.0 — saldırgan; kesin eşleşmeler sonuçları güçlü bir şekilde yeniden sıralar

Anahtar kelime güçlendirmesi anlamsal filtrelemeden sonra uygulanır, bu nedenle kesin olmayan eşleşmeleri ortaya çıkarmadan hassasiyeti artırır.

Nasıl Çalışır

TL;DR:

• Belgeler sabit karakter sayılarına göre değil, anlamsal benzerliğe göre bölümlenir
• Her parça, Transformers.js kullanarak yerel olarak gömülür
• Arama, kesin eşleşmeler için anahtar kelime güçlendirmesi ile anlamsal benzerlik kullanır
• Sonuçlar ham puanlara değil, uygunluk boşluklarına dayalı olarak filtrelenir

Ayrıntılar

Bir belgeyi içe aktardığınızda, ayrıştırıcı dosya türüne göre metni çıkarır (PDF mupdf aracılığıyla, DOCX mammoth aracılığıyla, metin dosyaları doğrudan).

Anlamsal chunker metni cümlelere böler, ardından bunları gömme benzerliğini kullanarak gruplandırır. Anlama kayması olduğu yerleri bulur — keyfi karakter sınırlarına kaymak yerine ilgili içeriği bir arada tutar. Bu, tipik olarak 500-1000 karakter olan anlam birimi olan parçalar üretir. Markdown kod blokları bozulmamış tutulur — hiç bir blok arasında bölünmez — arama sonuçlarında kopyalanabilir kodu korur.

Her parça, Transformers.js gömme modeli (varsayılan: all-MiniLM-L6-v2, MODEL_NAME aracılığıyla yapılandırılabilir) aracılığıyla geçer, metni vektörlere dönüştürür. Vektörler, hiçbir sunucu işlemi gerektirmeyen dosya tabanlı bir vektör veritabanı olan LanceDB'de depolanır.

Aradığınızda:

1. Sorgunuz aynı modeli kullanarak bir vektör haline gelir
2. Anlamsal (vektör) arama en uygun parçaları bulur
3. Kalite filtreleri uygulanır (mesafe eşiği, gruplandırma)
4. Anahtar kelime eşleşmeleri kesin terim eşleşmesi için sıralamaları artırır

Anahtar kelime güçlendirmesi, useEffect veya hata kodları gibi kesin terimlerin eşleştiğinde daha yüksek sıralanmasını sağlar.

Agent Skills

Agent Skills, AI asistanlarının RAG araçlarını daha etkili bir şekilde kullanmasına yardımcı olan optimize edilmiş istekler sağlar. Daha iyi sorgu formülasyonu, sonuç yorumu ve içe aktarma iş akışları için beceriler yükleyin:

# Claude Code (proje düzeyi)
npx mcp-local-rag skills install --claude-code

# Claude Code (kullanıcı düzeyi)
npx mcp-local-rag skills install --claude-code --global

# Codex
npx mcp-local-rag skills install --codex

Beceriler:

• Sorgu optimizasyonu: Daha iyi arama sorgusu formülasyonu
• Sonuç yorumu: Puan eşikleri ve filtreleme yönergeleri
• HTML içe aktarma: Format seçimi ve kaynak adlandırması

Beceri Aktivasyonunu Sağlama

Beceriler çoğu durumda otomatik olarak yüklenir — AI asistanları beceri meta verilerini tarar ve gerektiğinde ilgili talimatları yükler. Tutarlı davranış için:

Seçenek 1: Açık istek (doğal dil) RAG işlemlerinden önce, doğal dilde isteyin:

• "Bu arama için mcp-local-rag becerisini kullan"
• "RAG en iyi uygulamalarını becerilerden uygula"

Seçenek 2: Agent talimatları dosyasına ekle AGENTS.md, CLAUDE.md veya diğer agent talimatları dosyasına ekleyin:

query_documents, ingest_file veya ingest_data araçlarını kullanırken,
daha iyi sorgu formülasyonu ve sonuç yorumu için mcp-local-rag becerisini uygula.

Yapılandırma

Ortam Değişkenleri ve CLI Bayrakları

MCP sunucusu yalnızca ortam değişkenleri tarafından yapılandırılır — bunları MCP istemcinizin env bloğu aracılığıyla iletişim kurun. CLI aynı ortam değişkenlerini artı eşdeğer bayrakları kabul eder (öncelik: CLI bayrağı > ortam > varsayılan). CLI bayrakları çıplak mcp-local-rag (MCP sunucusu) başlatmada kabul edilmez.

Ortam Değişkeni	CLI Bayrağı	Varsayılan	Açıklama
BASE_DIR	--base-dir (tekrarlanabilir)	Geçerli dizin	Tekli belge kök dizini (güvenlik sınırı). Multi-kök kurulumu için Belge Kökleri bölümüne bakın.
BASE_DIRS	—	(ayarlanmamış)	Belge köklerinin JSON dizisi (güvenlik sınırı). BASE_DIR öğesinden önce gelir. Multi-kök kurulumu için Belge Kökleri bölümüne bakın.
DB_PATH	--db-path	./lancedb/	Vektör veritabanı konumu
CACHE_DIR	--cache-dir	./models/	Model önbellek dizini
MODEL_NAME	--model-name	Xenova/all-MiniLM-L6-v2	HuggingFace modeli ID (mevcut modeller)
MAX_FILE_SIZE	--max-file-size	104857600 (100MB)	Maksimum dosya boyutu bayt cinsinden
CHUNK_MIN_LENGTH	--chunk-min-length	50	Minimum parça uzunluğu karakterler (1–10000)
RAG_DEVICE	—	cpu	Yürütme cihazı. ONNX Runtime'a doğrudan iletilir. Desteklenen arka uç adlarının canlı listesi için Transformers.js cihaz kaynak koduna bakın. Başlatma başarısız olursa, sunucu bir hata atar.

Model seçim ipuçları:

• Çok dilli belgeler → ör. onnx-community/embeddinggemma-300m-ONNX (100+ dil)
• Bilimsel makaleler → ör. sentence-transformers/allenai-specter (alıntı analizi)
• Kod depoları → varsayılan sık yeterli; anahtar kelime güçlendirmesi daha önemli (veya jinaai/jina-embeddings-v2-base-code)

⚠️ MODEL_NAME değiştirmek gömme boyutlarını değiştirir. Modelleri değiştirdik