GZOO Cortex MCP Server

GZOO Cortex

Graf pengetahuan lokal-utama untuk pengembang. Memantau berkas proyek Anda, mengekstrak entitas dan relasi menggunakan LLM, dan memungkinkan Anda melakukan kueri di seluruh proyek dalam bahasa alami.

“Keputusan arsitektur apa yang telah saya buat di seluruh proyek?”

Cortex menemukan keputusan dari README, berkas TypeScript, berkas konfigurasi, dan ekspor percakapan — lalu menyintesis jawaban dengan kutipan sumber.

Mengapa

Anda mengerjakan banyak proyek. Keputusan, pola, dan konteks tersebar di ratusan berkas. Anda lupa apa yang Anda putuskan tiga bulan lalu. Anda memecahkan kembali masalah yang sudah Anda pecahkan di repositori lain.

Cortex memantau direktori proyek Anda, mengekstrak pengetahuan secara otomatis, dan memberikannya kembali kepada Anda saat Anda membutuhkannya.

Apa yang Dilakukan

• Memantau berkas proyek Anda (md, ts, js, py, json, yaml) untuk perubahan
• Mengekstrak entitas: keputusan, pola, komponen, dependensi, batasan, item tindakan
• Menyimpulkan relasi antar entitas di seluruh proyek
• Mendeteksi kontradiksi saat keputusan bertentangan
• Melakukan kueri dalam bahasa alami dengan kutipan sumber
• Mencari secara semantik — memadukan kemiripan kata kunci dan vektor (embedding) sehingga kueri cocok berdasarkan makna, bukan hanya kata kunci (opsional; lihat Pencarian Semantik)
• Merutekan secara cerdas antara LLM cloud dan lokal
• Menghormati privasi — proyek terbatas tidak pernah meninggalkan mesin Anda
• Dasbor web dengan visualisasi graf pengetahuan, umpan langsung, dan penjelajah kueri
• Server MCP untuk integrasi langsung dengan Claude Code

Mulai Cepat

1. Instal

npm install -g @gzoo/cortex

Jika instalasi global gagal dengan EACCES, gunakan prefiks pengguna sebagai gantinya:

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

Atau instal dari sumber:

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

Verifikasi: cortex --version (rilis saat ini: 0.8.1)

2. Penyiapan

Jalankan wizard interaktif:

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

Ini akan memandu Anda melalui:

• Penyedia LLM — Anthropic, Google Gemini, DeepSeek, Groq, OpenRouter, atau Ollama (lokal)
• Kunci API — disimpan dengan aman ke ~/.cortex/.env
• Mode perutean — cloud-utama, hibrida, lokal-utama, atau hanya-lokal
• Direktori pantauan — direktori mana yang harus dipantau Cortex
• Batas anggaran — batas pengeluaran LLM bulanan

cortex init menulis konfigurasi global ke ~/.cortex/cortex.config.json. Kunci API masuk ke ~/.cortex/.env.

3. Daftarkan Proyek

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

4. Ingest, Pantau & Kueri

Isi ulang berkas yang ada terlebih dahulu — pemantau hanya menangkap perubahan baru:

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

Perintah	Apa yang dilakukan
cortex serve	Dasbor web + API + pemantau berkas (ignoreInitial — tidak ada ingest ulang saat mulai)
cortex watch	Pemantau berkas khusus CLI (tanpa dasbor)
cortex ingest	Ingest satu kali; kejadian tidak muncul di Umpan Langsung

Jangan jalankan watch dan serve bersamaan — mereka bersaing untuk perubahan berkas. Umpan Langsung hanya menampilkan kejadian waktu nyata dari cortex serve (penyimpanan berkas saat server berjalan).

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. Dasbor Web

cortex serve                               # open http://localhost:3710

Akses jarak jauh:

cortex serve --host 0.0.0.0

Otentikasi diterapkan secara otomatis pada host non-localhost. Token pembawa dibuat otomatis dan disimpan ke ~/.cortex/.env (baca dengan grep CORTEX_SERVER_AUTH_TOKEN ~/.cortex/.env). Buka dasbor sekali dengan http://<host>:3710/?token=<token> — token hanya disematkan untuk permintaan yang sudah membuktikan kepemilikannya dan kemudian disimpan untuk tab peramban (sehingga pengunjung anonim tidak pernah menerimanya). Panggilan API/WebSocket di belakang proksi balik menggunakan Authorization: Bearer <token>.

Mengecualikan Berkas & Direktori

Cortex mengabaikan node_modules, dist, .git, dan direktori umum lainnya secara default. Untuk menambahkan lebih banyak:

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

Cara Kerja

Cortex menjalankan pipeline pada setiap perubahan berkas:

1. Parse — konten berkas dipotong oleh parser yang sadar bahasa (tree-sitter untuk kode, remark untuk markdown)
2. Ekstrak — LLM mengidentifikasi entitas (keputusan, komponen, pola, dll.)
3. Relasi — LLM menyimpulkan relasi antara entitas baru dan yang sudah ada
4. Deteksi — kontradiksi dan duplikat ditandai secara otomatis
5. Simpan — entitas, relasi, dan vektor masuk ke SQLite + LanceDB
6. Kueri — kueri bahasa alami mencari graf dan menyintesis jawaban

Semua data tetap lokal di ~/.cortex/. Hanya panggilan API LLM yang meninggalkan mesin Anda (dan tidak pernah untuk proyek terbatas).

Penyedia LLM

Cortex tidak terikat penyedia. Mendukung:

• Anthropic Claude (Sonnet, Haiku) — melalui API Anthropic asli
• Google Gemini — melalui API yang kompatibel dengan OpenAI
• DeepSeek (Reasoner, Chat) — penalaran kuat, sangat terjangkau
• Groq — inferensi cepat dengan tingkat gratis
• API apa pun yang kompatibel dengan OpenAI — OpenRouter, proksi lokal, dll.
• Ollama (Mistral, Llama, dll.) — sepenuhnya lokal, tidak perlu cloud

Pelacakan biaya menggunakan tarif sadar penyedia untuk model DeepSeek, Gemini, Groq, dan OpenRouter — bukan fallback Anthropic umum.

Embedding (untuk pencarian semantik) dikonfigurasi sebagai penyedia terpisah — independen dari model obrolan Anda — sehingga Anda dapat menjalankan obrolan di DeepSeek dan embedding di OpenAI. Lihat Pencarian Semantik.

Mode Perutean

Mode	Biaya Cloud	Kualitas	Ollama Diperlukan
cloud-first	Bervariasi menurut penyedia	Tertinggi	Tidak
hybrid	Berkurang	Tinggi	Ya
local-first	Minimal	Baik	Ya
local-only	$0	Baik	Ya

Dalam mode cloud-utama, semua tugas dirutekan ke penyedia cloud Anda. Ollama tidak diperlukan dan hanya digunakan jika fallback anggaran diaktifkan. Mode hibrida merutekan tugas bervolume tinggi (ekstraksi entitas, peringkat) ke Ollama dan tugas berat penalaran (inferensi relasi, kueri) ke penyedia cloud Anda.

Persyaratan

• Node.js 20+
• Kunci API LLM untuk mode cloud — Anthropic, Google Gemini, DeepSeek, Groq, atau penyedia apa pun yang kompatibel dengan OpenAI
• Ollama — hanya untuk mode hybrid, local-first, atau local-only (instal)

Konfigurasi

Konfigurasi berlapis — sumber selanjutnya menimpa yang sebelumnya:

Prioritas	Lokasi	Cakupan
1	Default bawaan	Global
2	~/.cortex/cortex.config.json	Global (dibuat oleh cortex init)
3	./cortex.config.json	Timpa proyek (opsional)
4	CORTEX_* env vars	Sesi

Kunci API disimpan terpisah di ~/.cortex/.env (tidak pernah di JSON konfigurasi).

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

Referensi konfigurasi lengkap: docs/configuration.md

Pencarian Semantik (Embedding)

Cortex memadukan pencarian kata kunci (teks penuh) dengan kemiripan vektor, sehingga kueri cocok berdasarkan makna daripada kata-kata persis. Embedding opsional dan mati secara default — aktifkan dengan penyedia embedding cloud (tidak perlu GPU lokal atau Ollama):

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

Penyedia embedding independen dari penyedia obrolan Anda — jalankan obrolan di DeepSeek (atau Anthropic, Groq, …) dan embedding di OpenAI. Setiap titik akhir embedding yang kompatibel dengan OpenAI berfungsi.

Berkas baru di-embed secara otomatis saat di-ingest. Untuk membangun indeks untuk graf yang sudah Anda ingest, jalankan reindeks satu kali:

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

Perintah

Perintah	Deskripsi
cortex init	Wizard penyiapan interaktif
cortex doctor	Validasi konfigurasi, penyedia, proyek, rahasia, dan basis data
cortex projects add/list/remove/show	Kelola proyek terdaftar
cortex serve	Dasbor web + API + pemantau berkas (port 3710)
cortex watch [project]	Pemantau berkas khusus CLI
cortex ingest <file-or-glob>	Ingest berkas satu kali (terpisah dari Umpan Langsung)
cortex reindex [project]	Bangun ulang indeks pencarian semantik (embedding) untuk entitas yang ada
cortex query <question>	Kueri bahasa alami dengan kutipan
cortex find <term>	Temukan entitas berdasarkan nama
cortex status	Statistik graf, biaya, status penyedia
cortex costs	Rincian biaya terperinci
cortex contradictions	Daftar kontradiksi aktif
cortex resolve <id>	Selesaikan kontradiksi
cortex models list/pull/test/info	Kelola model Ollama
cortex mcp	Mulai server MCP untuk Claude Code
cortex report	Ringkasan pasca-ingest
cortex privacy set/list	Atur privasi direktori
cortex config list/get/set/validate	Baca/tulis konfigurasi
cortex config exclude add/remove/list	Kelola pengecualian berkas/direktori
cortex stop / cortex restart	Kelola proses watch/serve yang berjalan
cortex db	Operasi basis data

Referensi CLI lengkap: docs/cli-reference.md

Dasbor Web

Jalankan cortex serve untuk membuka dasbor web lengkap di http://localhost:3710 dengan:

• Beranda Dasbor — statistik graf, aktivitas terbaru, rincian tipe entitas
• Graf Pengetahuan — graf gaya-D3 interaktif dengan pengelompokan, klik untuk menjelajah
• Umpan Langsung — kejadian perubahan berkas dan ekstraksi entitas waktu nyata melalui WebSocket (hanya dari cortex serve)
• Penjelajah Kueri — kueri bahasa alami dengan respons streaming
• Penyelesai Kontradiksi — tinjau dan selesaikan keputusan yang bertentangan

Penerapan Jarak Jauh

Untuk akses di luar localhost, ikat ke semua antarmuka dan letakkan Cortex di belakang proksi balik:

cortex serve --host 0.0.0.0

Contoh konfigurasi nginx — lindungi /api/ dan /ws dengan otentikasi dasar; sajikan aset statis tanpa otentikasi (dasbor menyematkan token pembawa ke HTML):

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;
}

Atur CORTEX_SERVER_AUTH_TOKEN atau server.auth.token dalam konfigurasi. Saat otentikasi diaktifkan, Cortex menyematkan token ke dalam HTML dasbor sehingga panggilan API dan WebSocket terotentikasi secara otomatis.

Server MCP (Integrasi Claude Code)

Cortex menyertakan server MCP sehingga Claude Code dapat langsung mengkueri graf pengetahuan Anda:

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

Ini memberi Claude Code 12 alat:

Alat	Deskripsi
cortex_ask	Pertanyaan bahasa alami tentang proyek Anda
get_status	Status sistem dan statistik graf
list_projects	Daftar proyek terdaftar
find_entity	Cari entitas berdasarkan nama
query_cortex	Kueri graf pengetahuan terstruktur
get_contradictions	Daftar kontradiksi yang terdeteksi
resolve_contradiction	Selesaikan kontradiksi
search_entities	Cari entitas dengan filter
ingest_file	Picu ingest berkas
add_project	Daftarkan proyek baru
remove_project	Hapus pendaftaran proyek
session_brief	Ringkasan konteks untuk sesi saat ini

Arsitektur

Monorepo dengan delapan paket:

• @cortex/core — tipe, EventBus, pemuat konfigurasi, kelas kesalahan
• @cortex/ingest — parser berkas (tree-sitter + remark), chunker, pemantau, pipeline
• @cortex/graph — penyimpanan SQLite, vektor LanceDB, mesin kueri
• @cortex/llm — penyedia Anthropic/Gemini/OpenAI-compatible/Ollama, perute, prompt, cache
• @cortex/cli — CLI Commander.js
• @cortex/mcp — server Model Context Protocol (transport stdio, 12 alat)
• @cortex/server — Express REST API + relai WebSocket
• @cortex/web — React + Vite + D3 dasbor web

Dokumentasi arsitektur: docs/

Privasi & Keamanan

• Berkas yang diklasifikasikan sebagai restricted tidak pernah dikirim ke LLM cloud
• Berkas sensitif (.env, .pem, .key) terdeteksi otomatis dan diblokir
• Rahasia kunci API dipindai dan disunting sebelum transmisi cloud apa pun
• Semua data disimpan secara lokal di ~/.cortex/ — tidak ada yang menelepon ke rumah

Arsitektur keamanan lengkap: docs/security.md

Dibangun Dengan

• SQLite melalui better-sqlite3 — penyimpanan entitas dan relasi
• LanceDB — embedding vektor untuk pencarian semantik
• Anthropic Claude — penyedia LLM cloud
• Google Gemini — penyedia LLM cloud (melalui API kompatibel OpenAI)
• DeepSeek — penyedia LLM cloud (penalaran + obrolan)
• Groq — inferensi cloud cepat
• Ollama — inferensi LLM lokal
• tree-sitter — parsing file berbasis bahasa
• Chokidar — pemantauan file lintas platform
• Commander.js — kerangka kerja CLI
• React + Vite — dasbor web
• D3 — visualisasi grafik pengetahuan

Berkontribusi

Lihat CONTRIBUTING.md untuk panduan.

Lisensi

MIT — lihat LICENSE

Tentang

Dibangun oleh GZOO — platform otomatisasi bisnis bertenaga AI.

Cortex awalnya adalah alat internal untuk menjaga konteks di berbagai proyek klien. Kami merilisnya sebagai sumber terbuka karena setiap pengembang yang mengerjakan lebih dari satu hal kehilangan konteks, dan kami pikir pendekatan ini — pemantauan file otomatis + grafik pengetahuan + kueri bahasa alami — adalah cara yang tepat untuk mengatasinya.