GZOO Cortex MCP Server

GZOO Cortex

Geliştiriciler için yerel öncelikli bilgi grafiği. Proje dosyalarınızı izler, LLM'leri kullanarak varlıkları ve ilişkileri çıkarır ve tüm projelerinizde doğal dilde sorgulama yapmanızı sağlar.

“Projelerim genelinde hangi mimari kararları aldım?”

Cortex, README'lerinizden, TypeScript dosyalarınızdan, yapılandırma dosyalarınızdan ve konuşma dışa aktarımlarınızdan kararları bulur — ardından kaynak alıntılarıyla bir yanıt sentezler.

Neden

Birden fazla proje üzerinde çalışıyorsunuz. Kararlar, desenler ve bağlam yüzlerce dosyaya dağılmış durumda. Üç ay önce neye karar verdiğinizi unutuyorsunuz. Başka bir depoda zaten çözdüğünüz sorunları yeniden çözüyorsunuz.

Cortex proje dizinlerinizi izler, bilgiyi otomatik olarak çıkarır ve ihtiyacınız olduğunda size geri verir.

Ne Yapar

• Proje dosyalarınızı (md, ts, js, py, json, yaml) değişiklikler için izler
• Varlıkları çıkarır: kararlar, desenler, bileşenler, bağımlılıklar, kısıtlamalar, eylem öğeleri
• Projeler arası varlıklar arasındaki ilişkileri çıkarır
• Kararlar çakıştığında çelişkileri tespit eder
• Kaynak alıntılarıyla doğal dilde sorgular
• Anlamsal olarak arar — anahtar kelime ve vektör (gömme) benzerliğini harmanlar, böylece sorgular yalnızca anahtar kelimelerle değil anlamla eşleşir (isteğe bağlı; bkz. Anlamsal Arama)
• Bulut ve yerel LLM'ler arasında akıllıca yönlendirir
• Gizliliğe saygı duyar — kısıtlı projeler asla makinenizden ayrılmaz
• Bilgi grafiği görselleştirmesi, canlı akış ve sorgu gezgini içeren web panosu
• Claude Code ile doğrudan entegrasyon için MCP sunucusu

Hızlı Başlangıç

1. Kurulum

npm install -g @gzoo/cortex

Genel kurulum EACCES ile başarısız olursa, bunun yerine bir kullanıcı öneki kullanın:

mkdir -p ~/.local
npm config set prefix ~/.local
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
npm install -g @gzoo/cortex

Veya kaynaktan kurun:

git clone https://github.com/gzoonet/cortex.git
cd cortex
npm install && npm run build && npm link

Doğrula: cortex --version (güncel sürüm: 0.8.1)

2. Kurulum

Etkileşimli sihirbazı çalıştırın:

cortex init
cortex doctor                              # verify config, providers, and DB

Bu size şunlarda rehberlik eder:

• LLM sağlayıcısı — Anthropic, Google Gemini, DeepSeek, Groq, OpenRouter veya Ollama (yerel)
• API anahtarı — ~/.cortex/.env konumuna güvenli bir şekilde kaydedilir
• Yönlendirme modu — bulut öncelikli, hibrit, yerel öncelikli veya yalnızca yerel
• İzleme dizinleri — Cortex'in hangi dizinleri izlemesi gerektiği
• Bütçe sınırı — aylık LLM harcama üst sınırı

cortex init genel yapılandırmayı ~/.cortex/cortex.config.json konumuna yazar. API anahtarları ~/.cortex/.env konumuna gider.

3. Projeleri Kaydetme

cortex projects add my-app ~/projects/app
cortex projects add api ~/projects/api
cortex projects list                       # verify

4. Yutma, İzleme ve Sorgulama

Önce mevcut dosyaları geri doldurun — izleyici yalnızca yeni değişiklikleri alır:

cortex ingest "~/projects/app/src/**/*.ts"   # one-shot backfill
cortex serve                                 # dashboard + API + file watcher (recommended)

Komut	Ne Yapar
cortex serve	Web panosu + API + dosya izleyici (ignoreInitial — başlangıçta yeniden yutma yok)
cortex watch	Yalnızca CLI dosya izleyici (pano yok)
cortex ingest	Tek seferlik yutma; olaylar Canlı Akış'ta görünmez

watch ve serve'ı birlikte çalıştırmayın — dosya değişiklikleri için rekabet ederler. Canlı Akış, yalnızca cortex serve'den gerçek zamanlı olayları gösterir (sunucu çalışırken dosya kaydetmeleri).

cortex query "what caching strategies am I using?"
cortex query "what decisions have I made about authentication?"
cortex find "PostgreSQL" --expand 2
cortex contradictions

5. Web Panosu

cortex serve                               # open http://localhost:3710

Uzaktan erişim:

cortex serve --host 0.0.0.0

Kimlik doğrulama, localhost olmayan ana bilgisayarlarda otomatik olarak uygulanır. Bir taşıyıcı belirteç otomatik olarak oluşturulur ve ~/.cortex/.env konumuna kaydedilir (grep CORTEX_SERVER_AUTH_TOKEN ~/.cortex/.env ile okuyun). Panoyu http://<host>:3710/?token=<token> ile bir kez açın — belirteç yalnızca zaten ona sahip olduğunu kanıtlayan isteklere gömülür ve ardından tarayıcı sekmesi için saklanır (böylece anonim ziyaretçiler asla almaz). Ters proxy arkasındaki API/WebSocket çağrıları Authorization: Bearer <token> kullanır.

Dosyaları ve Dizinleri Hariç Tutma

Cortex varsayılan olarak node_modules, dist, .git ve diğer yaygın dizinleri yok sayar. Daha fazlasını eklemek için:

cortex config exclude add docs             # exclude a directory
cortex config exclude add "*.log"          # exclude by pattern
cortex config exclude list                 # see all excludes
cortex config exclude remove docs          # remove an exclude

Nasıl Çalışır

Cortex her dosya değişikliğinde bir işlem hattı çalıştırır:

1. Ayrıştır — dosya içeriği dile duyarlı bir ayrıştırıcı tarafından parçalara ayrılır (kod için tree-sitter, markdown için remark)
2. Çıkar — LLM varlıkları tanımlar (kararlar, bileşenler, desenler, vb.)
3. İlişkilendir — LLM yeni ve mevcut varlıklar arasındaki ilişkileri çıkarır
4. Tespit Et — çelişkiler ve kopyalar otomatik olarak işaretlenir
5. Depola — varlıklar, ilişkiler ve vektörler SQLite + LanceDB'ye gider
6. Sorgula — doğal dil sorguları grafiği arar ve yanıtları sentezler

Tüm veriler ~/.cortex/ içinde yerel olarak kalır. Yalnızca LLM API çağrıları makinenizden ayrılır (ve kısıtlı projeler için asla).

LLM Sağlayıcıları

Cortex sağlayıcıdan bağımsızdır. Şunları destekler:

• Anthropic Claude (Sonnet, Haiku) — yerel Anthropic API aracılığıyla
• Google Gemini — OpenAI uyumlu API aracılığıyla
• DeepSeek (Reasoner, Chat) — güçlü muhakeme, çok uygun fiyatlı
• Groq — ücretsiz katmanla hızlı çıkarım
• Herhangi bir OpenAI uyumlu API — OpenRouter, yerel proxy'ler, vb.
• Ollama (Mistral, Llama, vb.) — tamamen yerel, bulut gerekmez

Maliyet takibi, DeepSeek, Gemini, Groq ve OpenRouter modelleri için sağlayıcıya duyarlı oranlar kullanır — genel bir Anthropic geri dönüşü değil.

Gömmeler (anlamsal arama için) sohbet modelinizden bağımsız olarak ayrı bir sağlayıcı olarak yapılandırılır — böylece sohbeti DeepSeek'te ve gömmeleri OpenAI'da çalıştırabilirsiniz. Bkz. Anlamsal Arama.

Yönlendirme Modları

Mod	Bulut Maliyeti	Kalite	Ollama Gerekli
cloud-first	Sağlayıcıya göre değişir	En Yüksek	Hayır
hybrid	Azaltılmış	Yüksek	Evet
local-first	Minimum	İyi	Evet
local-only	$0	İyi	Evet

Bulut öncelikli modda, tüm görevler bulut sağlayıcınıza yönlendirilir. Ollama gerekli değildir ve yalnızca bütçe geri dönüşü etkinleştirildiğinde kullanılır. Hibrit mod, yüksek hacimli görevleri (varlık çıkarma, sıralama) Ollama'ya ve muhakeme ağırlıklı görevleri (ilişki çıkarımı, sorgular) bulut sağlayıcınıza yönlendirir.

Gereksinimler

• Node.js 20+
• Bulut modları için LLM API anahtarı — Anthropic, Google Gemini, DeepSeek, Groq veya herhangi bir OpenAI uyumlu sağlayıcı
• Ollama — yalnızca hybrid, local-first veya local-only modları için (kurulum)

Yapılandırma

Yapılandırma katmanlıdır — sonraki kaynaklar öncekileri geçersiz kılar:

Öncelik	Konum	Kapsam
1	Yerleşik varsayılanlar	Genel
2	~/.cortex/cortex.config.json	Genel (cortex init tarafından oluşturulur)
3	./cortex.config.json	Proje geçersiz kılmaları (isteğe bağlı)
4	CORTEX_* ortam değişkenleri	Oturum

API anahtarları ~/.cortex/.env içinde ayrı olarak saklanır (asla yapılandırma JSON'unda değil).

cortex config list                       # see all non-default settings
cortex config set llm.mode hybrid        # switch routing mode
cortex config set llm.budget.monthlyLimitUsd 10  # set budget
cortex config exclude add vendor         # exclude a directory from watching
cortex privacy set ~/clients restricted  # mark directory as restricted
cortex doctor                            # validate setup

Tam yapılandırma referansı: docs/configuration.md

Anlamsal Arama (Gömmeler)

Cortex, anahtar kelime (tam metin) aramasını vektör benzerliği ile harmanlar, böylece sorgular tam kelimeler yerine anlamla eşleşir. Gömmeler isteğe bağlıdır ve varsayılan olarak kapalıdır — bunları bir bulut gömme sağlayıcısı ile etkinleştirin (yerel GPU veya Ollama gerekmez):

cortex config set llm.embeddings.enabled true
cortex config set llm.embeddings.baseUrl https://api.openai.com/v1
cortex config set llm.embeddings.model text-embedding-3-small
cortex config set llm.embeddings.apiKeySource env:OPENAI_API_KEY
cortex config set llm.embeddings.dimensions 1536
# then add the key to ~/.cortex/.env:
echo 'OPENAI_API_KEY=sk-...' >> ~/.cortex/.env

Gömme sağlayıcısı sohbet sağlayıcınızdan bağımsızdır — sohbeti DeepSeek'te (veya Anthropic, Groq, …) ve gömmeleri OpenAI'da çalıştırın. Herhangi bir OpenAI uyumlu gömme uç noktası çalışır.

Yeni dosyalar yutuldukça otomatik olarak gömülür. Zaten yutulmuş bir grafik için dizini oluşturmak üzere, tek seferlik bir yeniden dizinleme çalıştırın:

cortex reindex                 # all projects
cortex reindex my-app          # a single project

Komutlar

Komut	Açıklama
cortex init	Etkileşimli kurulum sihirbazı
cortex doctor	Yapılandırmayı, sağlayıcıları, projeleri, sırları ve veritabanını doğrula
cortex projects add/list/remove/show	Kayıtlı projeleri yönet
cortex serve	Web panosu + API + dosya izleyici (port 3710)
cortex watch [project]	Yalnızca CLI dosya izleyici
cortex ingest <file-or-glob>	Tek seferlik dosya yutma (Canlı Akış'tan ayrı)
cortex reindex [project]	Mevcut varlıklar için anlamsal (gömme) arama dizinini yeniden oluştur
cortex query <question>	Alıntılarla doğal dil sorgusu
cortex find <term>	Varlıkları ada göre bul
cortex status	Grafik istatistikleri, maliyetler, sağlayıcı durumu
cortex costs	Ayrıntılı maliyet dökümü
cortex contradictions	Aktif çelişkileri listele
cortex resolve <id>	Bir çelişkiyi çöz
cortex models list/pull/test/info	Ollama modellerini yönet
cortex mcp	Claude Code için MCP sunucusunu başlat
cortex report	Yutma sonrası özet
cortex privacy set/list	Dizin gizliliğini ayarla
cortex config list/get/set/validate	Yapılandırmayı oku/yaz
cortex config exclude add/remove/list	Dosya/dizin hariç tutmalarını yönet
cortex stop / cortex restart	Çalışan izleme/sunum süreçlerini yönet
cortex db	Veritabanı işlemleri

Tam CLI referansı: docs/cli-reference.md

Web Panosu

http://localhost:3710 adresinde tam bir web panosu açmak için cortex serve çalıştırın, şunları içerir:

• Pano Ana Sayfası — grafik istatistikleri, son etkinlik, varlık türü dökümü
• Bilgi Grafiği — kümeleme ile etkileşimli D3-force grafiği, keşfetmek için tıklayın
• Canlı Akış — WebSocket aracılığıyla gerçek zamanlı dosya değişikliği ve varlık çıkarma olayları (yalnızca cortex serve'dan)
• Sorgu Gezgini — akış yanıtlı doğal dil sorguları
• Çelişki Çözücü — çakışan kararları inceleyin ve çözün

Uzaktan Dağıtım

Localhost ötesinde erişim için, tüm arayüzlere bağlanın ve Cortex'i bir ters proxy arkasına koyun:

cortex serve --host 0.0.0.0

Örnek nginx yapılandırması — /api/ ve /ws'i temel kimlik doğrulama ile koruyun; statik varlıkları kimlik doğrulama olmadan sunun (pano, taşıyıcı belirteci HTML'e enjekte eder):

location /api/ {
    auth_basic "Cortex";
    auth_basic_user_file /etc/nginx/.htpasswd;
    proxy_pass http://127.0.0.1:3710;
    proxy_set_header Authorization "Bearer $CORTEX_TOKEN";
}

location /ws {
    auth_basic "Cortex";
    auth_basic_user_file /etc/nginx/.htpasswd;
    proxy_pass http://127.0.0.1:3710;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
}

location / {
    auth_basic off;
    proxy_pass http://127.0.0.1:3710;
}

Yapılandırmada CORTEX_SERVER_AUTH_TOKEN veya server.auth.token ayarlayın. Kimlik doğrulama etkinleştirildiğinde, Cortex belirteci pano HTML'ine enjekte eder, böylece API ve WebSocket çağrıları otomatik olarak kimlik doğrular.

MCP Sunucusu (Claude Code Entegrasyonu)

Cortex, Claude Code'un bilgi grafiğinizi doğrudan sorgulayabilmesi için bir MCP sunucusu içerir:

claude mcp add cortex --scope user -- npx @gzoo/cortex mcp

Bu, Claude Code'a 12 araç sağlar:

Araç	Açıklama
cortex_ask	Projeleriniz hakkında doğal dil soruları
get_status	Sistem durumu ve grafik istatistikleri
list_projects	Kayıtlı projeleri listele
find_entity	Varlıkları ada göre ara
query_cortex	Yapılandırılmış bilgi grafiği sorguları
get_contradictions	Tespit edilen çelişkileri listele
resolve_contradiction	Bir çelişkiyi çöz
search_entities	Filtrelerle varlıkları ara
ingest_file	Dosya yutmayı tetikle
add_project	Yeni bir proje kaydet
remove_project	Bir projenin kaydını sil
session_brief	Geçerli oturum için bağlam özeti

Mimari

Sekiz paketli monorepo:

• @cortex/core — türler, EventBus, yapılandırma yükleyici, hata sınıfları
• @cortex/ingest — dosya ayrıştırıcıları (tree-sitter + remark), parçalayıcı, izleyici, işlem hattı
• @cortex/graph — SQLite deposu, LanceDB vektörleri, sorgu motoru
• @cortex/llm — Anthropic/Gemini/OpenAI uyumlu/Ollama sağlayıcıları, yönlendirici, istemler, önbellek
• @cortex/cli — Commander.js CLI
• @cortex/mcp — Model Bağlam Protokolü sunucusu (stdio aktarımı, 12 araç)
• @cortex/server — Express REST API + WebSocket rölesi
• @cortex/web — React + Vite + D3 web panosu

Mimari belgeleri: docs/

Gizlilik ve Güvenlik

• restricted olarak sınıflandırılan dosyalar bulut LLM'lerine asla gönderilmez
• Hassas dosyalar (.env, .pem, .key) otomatik olarak tespit edilir ve engellenir
• API anahtarı sırları taranır ve herhangi bir bulut iletiminden önce sansürlenir
• Tüm veriler ~/.cortex/ içinde yerel olarak depolanır — eve telefon eden hiçbir şey yok

Tam güvenlik mimarisi: docs/security.md

İle İnşa Edildi

• SQLite better-sqlite3 aracılığıyla — varlık ve ilişki depolama
• LanceDB — anlamsal arama için vektör gömme
• Anthropic Claude — bulut LLM sağlayıcısı
• Google Gemini — bulut LLM sağlayıcısı (OpenAI uyumlu API aracılığıyla)
• DeepSeek — bulut LLM sağlayıcısı (akıl yürütme + sohbet)
• Groq — hızlı bulut çıkarımı
• Ollama — yerel LLM çıkarımı
• tree-sitter — dil farkında dosya ayrıştırma
• Chokidar — platformlar arası dosya izleme
• Commander.js — CLI çerçevesi
• React + Vite — web kontrol paneli
• D3 — bilgi grafiği görselleştirme

Katkıda Bulunma

Yönergeler için CONTRIBUTING.md dosyasına bakın.

Lisans

MIT — LICENSE dosyasına bakın

Hakkında

GZOO tarafından geliştirildi — yapay zeka destekli bir iş otomasyonu platformu.

Cortex, birden fazla müşteri projesinde bağlamı korumak için dahili bir araç olarak başladı. Birden fazla şey üzerinde çalışan her geliştirici bağlamı kaybettiği için açık kaynak yaptık ve bu yaklaşımın — otomatik dosya izleme + bilgi grafiği + doğal dil sorguları — bunu çözmenin doğru yolu olduğunu düşünüyoruz.