GZOO Cortex MCP Server

GZOO Cortex

กราฟความรู้แบบโลคอลเฟิร์สสำหรับนักพัฒนา เฝ้าดูไฟล์โปรเจกต์ของคุณ สกัดเอนทิตีและความสัมพันธ์โดยใช้ LLM และให้คุณสืบค้นข้าม ทุกโปรเจกต์ด้วยภาษาธรรมชาติ

“ฉันตัดสินใจด้านสถาปัตยกรรมอะไรไปบ้างในทุกโปรเจกต์?”

Cortex ค้นหาการตัดสินใจจาก README, ไฟล์ TypeScript, ไฟล์คอนฟิก, และการส่งออกบทสนทนา — จากนั้นสังเคราะห์คำตอบพร้อมการอ้างอิงแหล่งที่มา

ทำไม

คุณทำงานหลายโปรเจกต์ การตัดสินใจ, แพทเทิร์น, และบริบทกระจัดกระจาย อยู่ในไฟล์หลายร้อยไฟล์ คุณลืมสิ่งที่ตัดสินใจไปเมื่อสามเดือนก่อน คุณ แก้ปัญหาที่เคยแก้ไปแล้วในรีโปอื่นซ้ำอีก

Cortex เฝ้าดูไดเรกทอรีโปรเจกต์ของคุณ สกัดความรู้ออกมาโดยอัตโนมัติ และส่งคืนให้คุณเมื่อคุณต้องการ

มันทำอะไรได้บ้าง

• เฝ้าดู ไฟล์โปรเจกต์ของคุณ (md, ts, js, py, json, yaml) เพื่อตรวจจับการเปลี่ยนแปลง
• สกัด เอนทิตี: การตัดสินใจ, แพทเทิร์น, คอมโพเนนต์, การพึ่งพา, ข้อจำกัด, รายการที่ต้องดำเนินการ
• อนุมาน ความสัมพันธ์ระหว่างเอนทิตีข้ามโปรเจกต์
• ตรวจจับ ข้อขัดแย้งเมื่อการตัดสินใจขัดแย้งกัน
• สืบค้น ด้วยภาษาธรรมชาติพร้อมการอ้างอิงแหล่งที่มา
• ค้นหาเชิงความหมาย — ผสมผสานความคล้ายคลึงของคำหลักและเวกเตอร์ (embedding) เพื่อให้การสืบค้นตรงตามความหมาย ไม่ใช่แค่คำหลัก (เป็นทางเลือก; ดู Semantic Search)
• จัดเส้นทาง อย่างชาญฉลาดระหว่าง LLM บนคลาวด์และโลคอล
• เคารพ ความเป็นส่วนตัว — โปรเจกต์ที่ถูกจำกัดจะไม่ออกจากเครื่องของคุณ
• เว็บแดชบอร์ด พร้อมการแสดงภาพกราฟความรู้, ฟีดสด, และตัวสำรวจการสืบค้น
• เซิร์ฟเวอร์ MCP สำหรับการผสานรวมโดยตรงกับ Claude Code

เริ่มต้นอย่างรวดเร็ว

1. ติดตั้ง

npm install -g @gzoo/cortex

หากการติดตั้งแบบ global ล้มเหลวด้วย EACCES ให้ใช้ user prefix แทน:

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

หรือติดตั้งจากซอร์ส:

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

ตรวจสอบ: cortex --version (รุ่นปัจจุบัน: 0.8.1)

2. ตั้งค่า

รันวิซาร์ดแบบโต้ตอบ:

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

สิ่งนี้จะนำคุณผ่าน:

• ผู้ให้บริการ LLM — Anthropic, Google Gemini, DeepSeek, Groq, OpenRouter, หรือ Ollama (โลคอล)
• คีย์ API — บันทึกอย่างปลอดภัยไปยัง ~/.cortex/.env
• โหมดการจัดเส้นทาง — cloud-first, hybrid, local-first, หรือ local-only
• ไดเรกทอรีที่เฝ้าดู — ไดเรกทอรีที่ Cortex ควรตรวจสอบ
• ขีดจำกัดงบประมาณ — เพดานค่าใช้จ่าย LLM รายเดือน

cortex init เขียนคอนฟิก global ไปยัง ~/.cortex/cortex.config.json คีย์ API อยู่ใน ~/.cortex/.env

3. ลงทะเบียนโปรเจกต์

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

4. นำเข้า, เฝ้าดู & สืบค้น

เติมข้อมูลไฟล์ที่มีอยู่ก่อน — ตัวเฝ้าดูจะรับเฉพาะการเปลี่ยนแปลงใหม่:

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

คำสั่ง	สิ่งที่ทำ
cortex serve	เว็บแดชบอร์ด + API + ตัวเฝ้าดูไฟล์ (ignoreInitial — ไม่นำเข้าซ้ำเมื่อเริ่ม)
cortex watch	ตัวเฝ้าดูไฟล์แบบ CLI เท่านั้น (ไม่มีแดชบอร์ด)
cortex ingest	การนำเข้าครั้งเดียว; เหตุการณ์จะไม่ปรากฏใน Live Feed

อย่ารัน watch และ serve พร้อมกัน — พวกมันแย่งการเปลี่ยนแปลงไฟล์ Live Feed แสดงเหตุการณ์แบบเรียลไทม์จาก cortex serve เท่านั้น (การบันทึกไฟล์ขณะที่เซิร์ฟเวอร์กำลังทำงาน)

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. เว็บแดชบอร์ด

cortex serve                               # open http://localhost:3710

การเข้าถึงระยะไกล:

cortex serve --host 0.0.0.0

การรับรองความถูกต้องถูกบังคับใช้โดยอัตโนมัติบนโฮสต์ที่ไม่ใช่ localhost โทเค็น bearer ถูกสร้างขึ้นโดยอัตโนมัติและบันทึกไปยัง ~/.cortex/.env (อ่านด้วย grep CORTEX_SERVER_AUTH_TOKEN ~/.cortex/.env) เปิดแดชบอร์ดครั้งเดียวด้วย http://<host>:3710/?token=<token> — โทเค็นถูกฝังไว้สำหรับคำขอที่พิสูจน์แล้วว่าครอบครองมันเท่านั้น และจากนั้นจะถูกเก็บไว้สำหรับแท็บเบราว์เซอร์ (ดังนั้นผู้เยี่ยมชมที่ไม่ระบุชื่อจะไม่ได้รับมัน) การเรียก API/WebSocket หลัง reverse proxy ใช้ Authorization: Bearer <token>

การยกเว้นไฟล์ & ไดเรกทอรี

Cortex ไม่สนใจ node_modules, dist, .git, และไดเรกทอรีทั่วไปอื่นๆ โดยค่าเริ่มต้น หากต้องการเพิ่มเติม:

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

มันทำงานอย่างไร

Cortex รันไปป์ไลน์ทุกครั้งที่มีการเปลี่ยนแปลงไฟล์:

1. แยกวิเคราะห์ — เนื้อหาไฟล์ถูกแบ่งเป็นชิ้นโดยตัวแยกวิเคราะห์ที่รับรู้ภาษา (tree-sitter สำหรับโค้ด, remark สำหรับ markdown)
2. สกัด — LLM ระบุเอนทิตี (การตัดสินใจ, คอมโพเนนต์, แพทเทิร์น, ฯลฯ)
3. เชื่อมโยง — LLM อนุมานความสัมพันธ์ระหว่างเอนทิตีใหม่และที่มีอยู่
4. ตรวจจับ — ข้อขัดแย้งและรายการซ้ำถูกตั้งค่าสถานะโดยอัตโนมัติ
5. จัดเก็บ — เอนทิตี, ความสัมพันธ์, และเวกเตอร์ไปยัง SQLite + LanceDB
6. สืบค้น — การสืบค้นภาษาธรรมชาติค้นหากราฟและสังเคราะห์คำตอบ

ข้อมูลทั้งหมดอยู่ภายใน ~/.cortex/ เฉพาะการเรียก LLM API เท่านั้นที่ออกจากเครื่องของคุณ (และไม่เคยสำหรับโปรเจกต์ที่ถูกจำกัด)

ผู้ให้บริการ LLM

Cortex เป็นแบบ ไม่ยึดติดกับผู้ให้บริการ รองรับ:

• Anthropic Claude (Sonnet, Haiku) — ผ่าน Anthropic API ดั้งเดิม
• Google Gemini — ผ่าน API ที่เข้ากันได้กับ OpenAI
• DeepSeek (Reasoner, Chat) — การให้เหตุผลที่แข็งแกร่ง, ราคาไม่แพงมาก
• Groq — การอนุมานที่รวดเร็วพร้อมระดับฟรี
• API ใดๆ ที่เข้ากันได้กับ OpenAI — OpenRouter, พร็อกซีโลคอล, ฯลฯ
• Ollama (Mistral, Llama, ฯลฯ) — โลคอลเต็มรูปแบบ, ไม่ต้องใช้คลาวด์

การติดตามค่าใช้จ่ายใช้อัตราที่รับรู้ผู้ให้บริการสำหรับโมเดล DeepSeek, Gemini, Groq, และ OpenRouter — ไม่ใช่ fallback แบบ Anthropic ทั่วไป

Embeddings (สำหรับการค้นหาเชิงความหมาย) ถูกกำหนดค่าเป็นผู้ให้บริการ แยกต่างหาก — เป็นอิสระจากโมเดลแชทของคุณ — เพื่อให้คุณสามารถรันแชทบน DeepSeek และ embeddings บน OpenAI ดู Semantic Search

โหมดการจัดเส้นทาง

โหมด	ค่าใช้จ่ายคลาวด์	คุณภาพ	ต้องใช้ Ollama
cloud-first	แตกต่างกันไปตามผู้ให้บริการ	สูงสุด	ไม่
hybrid	ลดลง	สูง	ใช่
local-first	น้อยที่สุด	ดี	ใช่
local-only	$0	ดี	ใช่

ในโหมด cloud-first งานทั้งหมดถูกจัดเส้นทางไปยังผู้ให้บริการคลาวด์ของคุณ ไม่จำเป็นต้องใช้ Ollama และจะใช้เฉพาะเมื่อเปิดใช้งาน fallback งบประมาณ โหมด Hybrid จัดเส้นทางงานปริมาณมาก (การสกัดเอนทิตี, การจัดอันดับ) ไปยัง Ollama และงานที่ใช้การให้เหตุผลมาก (การอนุมานความสัมพันธ์, การสืบค้น) ไปยังผู้ให้บริการคลาวด์ของคุณ

ความต้องการ

• Node.js 20+
• คีย์ LLM API สำหรับโหมดคลาวด์ — Anthropic, Google Gemini, DeepSeek, Groq, หรือผู้ให้บริการใดๆ ที่เข้ากันได้กับ OpenAI
• Ollama — สำหรับโหมด hybrid, local-first, หรือ local-only เท่านั้น (ติดตั้ง)

การกำหนดค่า

คอนฟิกเป็นชั้นๆ — แหล่งที่มาภายหลังจะแทนที่แหล่งก่อนหน้า:

ลำดับความสำคัญ	ตำแหน่ง	ขอบเขต
1	ค่าเริ่มต้นในตัว	Global
2	~/.cortex/cortex.config.json	Global (สร้างโดย cortex init)
3	./cortex.config.json	การแทนที่โปรเจกต์ (เป็นทางเลือก)
4	CORTEX_* ตัวแปรสภาพแวดล้อม	เซสชัน

คีย์ API ถูกจัดเก็บแยกต่างหากใน ~/.cortex/.env (ไม่เคยอยู่ใน JSON คอนฟิก)

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

เอกสารอ้างอิงการกำหนดค่าฉบับเต็ม: docs/configuration.md

การค้นหาเชิงความหมาย (Embeddings)

Cortex ผสมผสานการค้นหาคำหลัก (full-text) กับ ความคล้ายคลึงของเวกเตอร์ เพื่อให้การสืบค้นตรงตามความหมายมากกว่าคำที่ตรงกันทุกประการ Embeddings เป็น ทางเลือกและปิดโดยค่าเริ่มต้น — เปิดใช้งานด้วยผู้ให้บริการ embeddings บนคลาวด์ (ไม่ต้องใช้ GPU โลคอลหรือ 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

ผู้ให้บริการ embeddings เป็น อิสระจากผู้ให้บริการแชทของคุณ — รันแชทบน DeepSeek (หรือ Anthropic, Groq, …) และ embeddings บน OpenAI ปลายทาง embeddings ใดๆ ที่เข้ากันได้กับ OpenAI ทำงานได้

ไฟล์ใหม่ถูกฝังโดยอัตโนมัติเมื่อถูกนำเข้า หากต้องการสร้างดัชนีสำหรับกราฟที่คุณ นำเข้าไปแล้ว ให้รันการสร้างดัชนีใหม่ครั้งเดียว:

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

คำสั่ง

คำสั่ง	คำอธิบาย
cortex init	วิซาร์ดการตั้งค่าแบบโต้ตอบ
cortex doctor	ตรวจสอบคอนฟิก, ผู้ให้บริการ, โปรเจกต์, ความลับ, และฐานข้อมูล
cortex projects add/list/remove/show	จัดการโปรเจกต์ที่ลงทะเบียน
cortex serve	เว็บแดชบอร์ด + API + ตัวเฝ้าดูไฟล์ (พอร์ต 3710)
cortex watch [project]	ตัวเฝ้าดูไฟล์แบบ CLI เท่านั้น
cortex ingest <file-or-glob>	การนำเข้าไฟล์ครั้งเดียว (แยกจาก Live Feed)
cortex reindex [project]	สร้างดัชนีการค้นหาเชิงความหมาย (embedding) ใหม่สำหรับเอนทิตีที่มีอยู่
cortex query <question>	การสืบค้นภาษาธรรมชาติพร้อมการอ้างอิง
cortex find <term>	ค้นหาเอนทิตีตามชื่อ
cortex status	สถิติกราฟ, ค่าใช้จ่าย, สถานะผู้ให้บริการ
cortex costs	รายละเอียดค่าใช้จ่าย
cortex contradictions	แสดงรายการข้อขัดแย้งที่ใช้งานอยู่
cortex resolve <id>	แก้ไขข้อขัดแย้ง
cortex models list/pull/test/info	จัดการโมเดล Ollama
cortex mcp	เริ่มเซิร์ฟเวอร์ MCP สำหรับ Claude Code
cortex report	สรุปหลังการนำเข้า
cortex privacy set/list	ตั้งค่าความเป็นส่วนตัวของไดเรกทอรี
cortex config list/get/set/validate	อ่าน/เขียนการกำหนดค่า
cortex config exclude add/remove/list	จัดการการยกเว้นไฟล์/ไดเรกทอรี
cortex stop / cortex restart	จัดการกระบวนการ watch/serve ที่กำลังทำงาน
cortex db	การดำเนินการฐานข้อมูล

เอกสารอ้างอิง CLI ฉบับเต็ม: docs/cli-reference.md

เว็บแดชบอร์ด

รัน cortex serve เพื่อเปิดเว็บแดชบอร์ดเต็มรูปแบบที่ http://localhost:3710 พร้อมด้วย:

• หน้าแรกแดชบอร์ด — สถิติกราฟ, กิจกรรมล่าสุด, การแจกแจงประเภทเอนทิตี
• กราฟความรู้ — กราฟ D3-force แบบโต้ตอบพร้อมการจัดกลุ่ม, คลิกเพื่อสำรวจ
• Live Feed — เหตุการณ์การเปลี่ยนแปลงไฟล์และการสกัดเอนทิตีแบบเรียลไทม์ผ่าน WebSocket (จาก cortex serve เท่านั้น)
• ตัวสำรวจการสืบค้น — การสืบค้นภาษาธรรมชาติพร้อมการตอบสนองแบบสตรีมมิ่ง
• ตัวแก้ไขข้อขัดแย้ง — ตรวจสอบและแก้ไขการตัดสินใจที่ขัดแย้งกัน

การปรับใช้ระยะไกล

สำหรับการเข้าถึงนอกเหนือ localhost ให้ผูกกับอินเทอร์เฟซทั้งหมดและวาง Cortex ไว้หลัง reverse proxy:

cortex serve --host 0.0.0.0

ตัวอย่างการกำหนดค่า nginx — ปกป้อง /api/ และ /ws ด้วย basic auth; ให้บริการ static assets โดยไม่ต้องรับรองความถูกต้อง (แดชบอร์ดฝังโทเค็น bearer ลงใน 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;
}

ตั้งค่า CORTEX_SERVER_AUTH_TOKEN หรือ server.auth.token ในคอนฟิก เมื่อเปิดใช้งานการรับรองความถูกต้อง Cortex จะฝังโทเค็นลงใน HTML ของแดชบอร์ด เพื่อให้การเรียก API และ WebSocket รับรองความถูกต้องโดยอัตโนมัติ

เซิร์ฟเวอร์ MCP (การผสานรวม Claude Code)

Cortex รวมเซิร์ฟเวอร์ MCP เพื่อให้ Claude Code สามารถสืบค้นกราฟความรู้ของคุณได้โดยตรง:

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

สิ่งนี้มอบ 12 เครื่องมือ ให้ Claude Code:

เครื่องมือ	คำอธิบาย
cortex_ask	คำถามภาษาธรรมชาติเกี่ยวกับโปรเจกต์ของคุณ
get_status	สถานะระบบและสถิติกราฟ
list_projects	แสดงรายการโปรเจกต์ที่ลงทะเบียน
find_entity	ค้นหาเอนทิตีตามชื่อ
query_cortex	การสืบค้นกราฟความรู้แบบมีโครงสร้าง
get_contradictions	แสดงรายการข้อขัดแย้งที่ตรวจพบ
resolve_contradiction	แก้ไขข้อขัดแย้ง
search_entities	ค้นหาเอนทิตีด้วยตัวกรอง
ingest_file	เรียกการนำเข้าไฟล์
add_project	ลงทะเบียนโปรเจกต์ใหม่
remove_project	ยกเลิกการลงทะเบียนโปรเจกต์
session_brief	สรุปบริบทสำหรับเซสชันปัจจุบัน

สถาปัตยกรรม

Monorepo พร้อมแปดแพ็คเกจ:

• @cortex/core — types, EventBus, ตัวโหลดคอนฟิก, คลาสข้อผิดพลาด
• @cortex/ingest — ตัวแยกวิเคราะห์ไฟล์ (tree-sitter + remark), ตัวแบ่งชิ้น, ตัวเฝ้าดู, ไปป์ไลน์
• @cortex/graph — ที่เก็บ SQLite, เวกเตอร์ LanceDB, เอนจินการสืบค้น
• @cortex/llm — ผู้ให้บริการ Anthropic/Gemini/OpenAI-compatible/Ollama, เราเตอร์, พรอมต์, แคช
• @cortex/cli — Commander.js CLI
• @cortex/mcp — เซิร์ฟเวอร์ Model Context Protocol (การขนส่ง stdio, 12 เครื่องมือ)
• @cortex/server — Express REST API + ตัวถ่ายทอด WebSocket
• @cortex/web — React + Vite + D3 เว็บแดชบอร์ด

เอกสารสถาปัตยกรรม: docs/

ความเป็นส่วนตัว & ความปลอดภัย

• ไฟล์ที่ถูกจัดประเภทเป็น restricted จะ ไม่เคย ถูกส่งไปยัง LLM บนคลาวด์
• ไฟล์ที่ละเอียดอ่อน (.env, .pem, .key) ถูกตรวจจับและบล็อกโดยอัตโนมัติ
• ความลับของคีย์ API ถูกสแกนและปกปิดก่อนการส่งผ่านคลาวด์ใดๆ
• ข้อมูลทั้งหมดถูกจัดเก็บภายใน ~/.cortex/ — ไม่มีการส่งข้อมูลกลับบ้าน

สถาปัตยกรรมความปลอดภัยฉบับเต็ม: docs/security.md

สร้างด้วย

• SQLite ผ่าน better-sqlite3 — ที่เก็บเอนทิตีและความสัมพันธ์
• LanceDB — การฝังเวกเตอร์สำหรับการค้นหาเชิงความหมาย
• Anthropic Claude — ผู้ให้บริการ LLM บนคลาวด์
• Google Gemini — ผู้ให้บริการ LLM บนคลาวด์ (ผ่าน API ที่เข้ากันได้กับ OpenAI)
• DeepSeek — ผู้ให้บริการ LLM บนคลาวด์ (การให้เหตุผล + แชท)
• Groq — การอนุมานบนคลาวด์ที่รวดเร็ว
• Ollama — การอนุมาน LLM ภายในเครื่อง
• tree-sitter — การแยกวิเคราะห์ไฟล์ที่รับรู้ภาษา
• Chokidar — การเฝ้าดูไฟล์ข้ามแพลตฟอร์ม
• Commander.js — เฟรมเวิร์ก CLI
• React + Vite — แดชบอร์ดเว็บ
• D3 — การแสดงภาพกราฟความรู้

การมีส่วนร่วม

ดูแนวทางได้ที่ CONTRIBUTING.md

ใบอนุญาต

MIT — ดู LICENSE

เกี่ยวกับ

สร้างโดย GZOO — แพลตฟอร์มอัตโนมัติทางธุรกิจที่ขับเคลื่อนด้วย AI

Cortex เริ่มต้นจากเครื่องมือภายในเพื่อรักษาบริบทในหลายโปรเจกต์ของลูกค้า เราโอเพนซอร์สมันเพราะนักพัฒนาทุกคนที่ทำงานมากกว่าหนึ่งอย่างย่อมสูญเสียบริบท และเราคิดว่าแนวทางนี้ — การเฝ้าดูไฟล์อัตโนมัติ + กราฟความรู้ + การค้นหาด้วยภาษาธรรมชาติ — เป็นวิธีที่ถูกต้องในการแก้ปัญหานี้