Contextator

Contextator, bir kodlama ajanının projenin dokümanına ulaşması için dokümanı bir yere taşımak gerekmesin diye geliştirdiğim açık kaynak bir MCP sunucusudur. Vaadi tek cümleyle şu: bir projeye kaynaklarını verirsiniz — sunucuda bağlı bir klasör, bir git deposu ya da onun tek bir alt dizini, yüklenmiş bir .zip/.tar.gz/.rar arşivi, bir Obsidian kasası veya bir Notion çalışma alanı — ve o proje /mcp/<proje-adı> adresinde kendi Model Context Protocol ucu hâline gelir. Claude Code, Cursor, Claude Desktop ya da MCP konuşan herhangi bir istemci o uca bağlanır ve üç araçla çalışır: search_docs anlamsal arama yapar, list_topics indekslenmiş dokümanları dizinlerine göre listeler, read_document bir dosyayı ya da onun tek bir bölümünü döndürür. Her kaynak kendi adının altına monte edildiği için bir doküman handbook/install.md diye okunur ve /mcp/billing’e bağlı bir istemci /mcp/mobile’ı hiç görmez.

Mimarinin merkezinde üç karar var. Yalıtım adresin kendisidir: her proje kendi URL’ini ve kendi doküman koleksiyonunu taşır, bu yüzden projeler arası arama tasarım gereği yoktur — alternatifi tek uca bir project parametresi koymaktı ve o tasarımda yalıtım ajanın doğru parametreyi göndermesine bağlı kalırdı. Varsayılan yol dışarıya çıkmaz: embedding’ler Xenova/multilingual-e5-small ile makinenin CPU’sunda üretilir (384 boyut, Türkçe dâhil çok dilli bir retrieval modeli); birkaç ortam değişkeniyle OpenAI embedding’lerine geçilebilir ama çalışmak için hiçbir API anahtarı gerekmez. Arama iki dizine birden sorar: bir cümle modeli bir sabit adını ya da hata kodunu temsil edemediği için her chunk hem HNSW vektör dizininde hem tam metin dizininde durur ve bir arama iki listenin sıralamalarını birleştirir — skorları değil sıralamaları, çünkü skor ağırlıkları embedding modeli her değiştiğinde yeniden öğrenilmek zorunda kalırdı. Dosyalar sha256 ile izlenir: yalnız değişen dosya yeniden gömülür, silinen dosyanın dokümanları düşer ve tam yeniden indeksleme canlı indeksin yanına yazılıp tek adımda yayına alınır, böylece proje bütün koşu boyunca cevap vermeye devam eder.

Ürün tek bir Docker container’ı olarak dağıtılır: PostgreSQL 16 + pgvector ve Node.js uygulaması aynı imajın içinde, küçük bir entrypoint betiğiyle birlikte ayağa kalkar ve birlikte durur — “kurulum tek komut olsun” kararının bedeli, tek-süreç ortodoksisinden bilinçli bir sapmadır. .html, .docx, .csv ve .pdf dosyaları indekslenirken Markdown’a çevrilir; metin katmanı olmayan taranmış bir PDF indekslenmez, reddedilir — çünkü fark edilmeyen başarısızlık, var olan ama hiçbir şeyle eşleşmeyen boş bir doküman üretendir. Hesap ve rol modeli root/admin/member üçlüsü ile proje başına viewer/editor üyeliğinden oluşur, her MCP ucu üç ayarlı bir kapı taşır (açık · bearer token · hesap gerektiren, OAuth 2.1 ile) ve retrieval kalitesi bir golden set üzerinden ölçülüp CI’da eşik altına düştüğünde derlemeyi düşürür. Lisans AGPL-3.0-or-later: değiştirilmiş bir sürümü ağ üzerinden sunan, o değişiklikleri aynı lisansla yayımlar.