GZOO Cortex MCP Server

chính thức

Đồ thị tri thức ưu tiên cục bộ dành cho nhà phát triển. Theo dõi các tệp dự án, trích xuất thực thể và mối quan hệ qua LLM, cho phép bạn truy vấn xuyên suốt các dự án bằng ngôn ngữ tự nhiên và trích dẫn nguồn.

GitHub

Tài liệu

GZOO Cortex

Đồ thị tri thức cục bộ dành cho nhà phát triển. Theo dõi các tệp dự án của bạn, trích xuất thực thể và mối quan hệ bằng LLM, đồng thời cho phép bạn truy vấn trên tất cả các dự án bằng ngôn ngữ tự nhiên.

“Tôi đã đưa ra những quyết định kiến trúc nào trên các dự án?”

Cortex tìm thấy các quyết định từ README, tệp TypeScript, tệp cấu hình và các bản xuất hội thoại — sau đó tổng hợp câu trả lời kèm trích dẫn nguồn.

Tại sao

Bạn làm việc trên nhiều dự án. Các quyết định, mẫu hình và ngữ cảnh nằm rải rác trên hàng trăm tệp. Bạn quên mất mình đã quyết định gì ba tháng trước. Bạn giải quyết lại những vấn đề đã từng giải quyết trong một repo khác.

Cortex theo dõi các thư mục dự án của bạn, tự động trích xuất tri thức và trả lại cho bạn khi bạn cần.

Nó làm gì

Theo dõi các tệp dự án của bạn (md, ts, js, py, json, yaml) để phát hiện thay đổi
Trích xuất các thực thể: quyết định, mẫu hình, thành phần, phụ thuộc, ràng buộc, mục hành động
Suy luận mối quan hệ giữa các thực thể trên các dự án
Phát hiện mâu thuẫn khi các quyết định xung đột
Truy vấn bằng ngôn ngữ tự nhiên kèm trích dẫn nguồn
Tìm kiếm ngữ nghĩa — kết hợp từ khóa và độ tương đồng vector (embedding) để truy vấn khớp theo ý nghĩa, không chỉ từ khóa (tùy chọn; xem Tìm kiếm ngữ nghĩa)
Định tuyến thông minh giữa LLM đám mây và cục bộ
Tôn trọng quyền riêng tư — các dự án bị hạn chế không bao giờ rời khỏi máy của bạn
Bảng điều khiển web với trực quan hóa đồ thị tri thức, nguồn cấp trực tiếp và trình khám phá truy vấn
Máy chủ MCP để tích hợp trực tiếp với Claude Code

Bắt đầu nhanh

1. Cài đặt

npm install -g @gzoo/cortex

Nếu cài đặt toàn cục thất bại với EACCES, hãy sử dụng tiền tố người dùng thay thế:

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

Hoặc cài đặt từ mã nguồn:

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

Xác minh: cortex --version (bản phát hành hiện tại: 0.8.1)

2. Thiết lập

Chạy trình hướng dẫn tương tác:

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

Trình hướng dẫn này sẽ hướng dẫn bạn qua:

Nhà cung cấp LLM — Anthropic, Google Gemini, DeepSeek, Groq, OpenRouter hoặc Ollama (cục bộ)
Khóa API — được lưu an toàn vào ~/.cortex/.env
Chế độ định tuyến — ưu tiên đám mây, lai, ưu tiên cục bộ hoặc chỉ cục bộ
Thư mục theo dõi — những thư mục nào Cortex nên giám sát
Giới hạn ngân sách — giới hạn chi tiêu LLM hàng tháng

cortex init ghi cấu hình toàn cục vào ~/.cortex/cortex.config.json. Khóa API được lưu trong ~/.cortex/.env.

3. Đăng ký dự án

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

4. Nhập, Theo dõi & Truy vấn

Điền dữ liệu các tệp hiện có trước — trình theo dõi chỉ nhận các thay đổi mới:

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

Lệnh	Chức năng
`cortex serve`	Bảng điều khiển web + API + trình theo dõi tệp (`ignoreInitial` — không nhập lại khi khởi động)
`cortex watch`	Trình theo dõi tệp chỉ dùng CLI (không có bảng điều khiển)
`cortex ingest`	Nhập một lần; các sự kiện không xuất hiện trong Nguồn cấp trực tiếp

Không chạy watch và serve cùng nhau — chúng cạnh tranh các thay đổi tệp. Nguồn cấp trực tiếp chỉ hiển thị các sự kiện thời gian thực từ cortex serve (lưu tệp khi máy chủ đang chạy).

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. Bảng điều khiển Web

cortex serve                               # open http://localhost:3710

Truy cập từ xa:

cortex serve --host 0.0.0.0

Xác thực được thực thi tự động trên các máy chủ không phải localhost. Một mã thông báo bearer được tự động tạo và lưu vào ~/.cortex/.env (đọc nó bằng grep CORTEX_SERVER_AUTH_TOKEN ~/.cortex/.env). Mở bảng điều khiển một lần với http://<host>:3710/?token=<token> — mã thông báo chỉ được nhúng cho các yêu cầu đã chứng minh quyền sở hữu nó và sau đó được giữ cho tab trình duyệt (vì vậy khách truy cập ẩn danh không bao giờ nhận được nó). Các cuộc gọi API/WebSocket đằng sau proxy ngược sử dụng Authorization: Bearer <token>.

Loại trừ Tệp & Thư mục

Cortex bỏ qua node_modules, dist, .git và các thư mục phổ biến khác theo mặc định. Để thêm nhiều hơn:

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

Cách thức hoạt động

Cortex chạy một quy trình trên mỗi thay đổi tệp:

Phân tích cú pháp — nội dung tệp được chia thành các đoạn bởi trình phân tích cú pháp nhận biết ngôn ngữ (tree-sitter cho mã, remark cho markdown)
Trích xuất — LLM xác định các thực thể (quyết định, thành phần, mẫu hình, v.v.)
Liên hệ — LLM suy luận mối quan hệ giữa các thực thể mới và hiện có
Phát hiện — mâu thuẫn và trùng lặp được gắn cờ tự động
Lưu trữ — thực thể, mối quan hệ và vector được đưa vào SQLite + LanceDB
Truy vấn — truy vấn ngôn ngữ tự nhiên tìm kiếm đồ thị và tổng hợp câu trả lời

Tất cả dữ liệu được lưu cục bộ trong ~/.cortex/. Chỉ các cuộc gọi API LLM rời khỏi máy của bạn (và không bao giờ cho các dự án bị hạn chế).

Nhà cung cấp LLM

Cortex không phụ thuộc vào nhà cung cấp. Nó hỗ trợ:

Anthropic Claude (Sonnet, Haiku) — qua API Anthropic gốc
Google Gemini — qua API tương thích OpenAI
DeepSeek (Reasoner, Chat) — suy luận mạnh mẽ, rất phải chăng
Groq — suy luận nhanh với bậc miễn phí
Bất kỳ API tương thích OpenAI nào — OpenRouter, proxy cục bộ, v.v.
Ollama (Mistral, Llama, v.v.) — hoàn toàn cục bộ, không cần đám mây

Theo dõi chi phí sử dụng tỷ lệ nhận biết nhà cung cấp cho các mô hình DeepSeek, Gemini, Groq và OpenRouter — không phải dự phòng Anthropic chung chung.

Embeddings (cho tìm kiếm ngữ nghĩa) được cấu hình như một nhà cung cấp riêng biệt — độc lập với mô hình trò chuyện của bạn — vì vậy bạn có thể chạy trò chuyện trên DeepSeek và embeddings trên OpenAI. Xem Tìm kiếm ngữ nghĩa.

Chế độ định tuyến

Chế độ	Chi phí đám mây	Chất lượng	Yêu cầu Ollama
`cloud-first`	Thay đổi theo nhà cung cấp	Cao nhất	Không
`hybrid`	Giảm	Cao	Có
`local-first`	Tối thiểu	Tốt	Có
`local-only`	$0	Tốt	Có

Trong chế độ ưu tiên đám mây, tất cả các tác vụ được định tuyến đến nhà cung cấp đám mây của bạn. Ollama không bắt buộc và chỉ được sử dụng nếu dự phòng ngân sách được bật. Chế độ lai định tuyến các tác vụ khối lượng lớn (trích xuất thực thể, xếp hạng) đến Ollama và các tác vụ nặng về suy luận (suy luận mối quan hệ, truy vấn) đến nhà cung cấp đám mây của bạn.

Yêu cầu

Node.js 20+
Khóa API LLM cho các chế độ đám mây — Anthropic, Google Gemini, DeepSeek, Groq hoặc bất kỳ nhà cung cấp tương thích OpenAI nào
Ollama — chỉ cho các chế độ hybrid, local-first hoặc local-only (cài đặt)

Cấu hình

Cấu hình được phân lớp — các nguồn sau ghi đè các nguồn trước:

Ưu tiên	Vị trí	Phạm vi
1	Mặc định tích hợp	Toàn cục
2	`~/.cortex/cortex.config.json`	Toàn cục (được tạo bởi `cortex init`)
3	`./cortex.config.json`	Ghi đè dự án (tùy chọn)
4	Biến môi trường `CORTEX_*`	Phiên

Khóa API được lưu trữ riêng biệt trong ~/.cortex/.env (không bao giờ trong JSON cấu hình).

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

Tham khảo cấu hình đầy đủ: docs/configuration.md

Tìm kiếm ngữ nghĩa (Embeddings)

Cortex kết hợp tìm kiếm từ khóa (toàn văn) với độ tương đồng vector, để các truy vấn khớp theo ý nghĩa thay vì từ chính xác. Embeddings là tùy chọn và tắt theo mặc định — bật chúng với nhà cung cấp embeddings đám mây (không yêu cầu GPU cục bộ hoặc 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

Nhà cung cấp embeddings độc lập với nhà cung cấp trò chuyện của bạn — chạy trò chuyện trên DeepSeek (hoặc Anthropic, Groq, …) và embeddings trên OpenAI. Bất kỳ điểm cuối embeddings tương thích OpenAI nào cũng hoạt động.

Các tệp mới được nhúng tự động khi chúng được nhập. Để xây dựng chỉ mục cho một đồ thị bạn đã nhập, hãy chạy lập chỉ mục lại một lần:

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

Lệnh

Lệnh	Mô tả
`cortex init`	Trình hướng dẫn thiết lập tương tác
`cortex doctor`	Xác thực cấu hình, nhà cung cấp, dự án, bí mật và cơ sở dữ liệu
`cortex projects add/list/remove/show`	Quản lý các dự án đã đăng ký
`cortex serve`	Bảng điều khiển web + API + trình theo dõi tệp (cổng 3710)
`cortex watch [project]`	Trình theo dõi tệp chỉ dùng CLI
`cortex ingest <file-or-glob>`	Nhập tệp một lần (tách biệt khỏi Nguồn cấp trực tiếp)
`cortex reindex [project]`	Xây dựng lại chỉ mục tìm kiếm ngữ nghĩa (embedding) cho các thực thể hiện có
`cortex query <question>`	Truy vấn ngôn ngữ tự nhiên kèm trích dẫn
`cortex find <term>`	Tìm thực thể theo tên
`cortex status`	Thống kê đồ thị, chi phí, trạng thái nhà cung cấp
`cortex costs`	Phân tích chi phí chi tiết
`cortex contradictions`	Liệt kê các mâu thuẫn đang hoạt động
`cortex resolve <id>`	Giải quyết một mâu thuẫn
`cortex models list/pull/test/info`	Quản lý mô hình Ollama
`cortex mcp`	Khởi động máy chủ MCP cho Claude Code
`cortex report`	Tóm tắt sau khi nhập
`cortex privacy set/list`	Đặt quyền riêng tư thư mục
`cortex config list/get/set/validate`	Đọc/ghi cấu hình
`cortex config exclude add/remove/list`	Quản lý loại trừ tệp/thư mục
`cortex stop` / `cortex restart`	Quản lý các tiến trình theo dõi/phục vụ đang chạy
`cortex db`	Thao tác cơ sở dữ liệu

Tham khảo CLI đầy đủ: docs/cli-reference.md

Bảng điều khiển Web

Chạy cortex serve để mở bảng điều khiển web đầy đủ tại http://localhost:3710 với:

Trang chủ Bảng điều khiển — thống kê đồ thị, hoạt động gần đây, phân tích loại thực thể
Đồ thị tri thức — đồ thị lực D3 tương tác với phân cụm, nhấp để khám phá
Nguồn cấp trực tiếp — sự kiện thay đổi tệp và trích xuất thực thể thời gian thực qua WebSocket (chỉ từ cortex serve)
Trình khám phá truy vấn — truy vấn ngôn ngữ tự nhiên với phản hồi trực tuyến
Trình giải quyết mâu thuẫn — xem xét và giải quyết các quyết định xung đột

Triển khai từ xa

Để truy cập ngoài localhost, liên kết với tất cả các giao diện và đặt Cortex sau proxy ngược:

cortex serve --host 0.0.0.0

Ví dụ cấu hình nginx — bảo vệ /api/ và /ws bằng xác thực cơ bản; phục vụ tài nguyên tĩnh mà không cần xác thực (bảng điều khiển nhúng mã thông báo bearer vào 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;
}

Đặt CORTEX_SERVER_AUTH_TOKEN hoặc server.auth.token trong cấu hình. Khi xác thực được bật, Cortex nhúng mã thông báo vào HTML bảng điều khiển để các cuộc gọi API và WebSocket tự động xác thực.

Máy chủ MCP (Tích hợp Claude Code)

Cortex bao gồm một máy chủ MCP để Claude Code có thể truy vấn trực tiếp đồ thị tri thức của bạn:

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

Điều này cung cấp cho Claude Code 12 công cụ:

Công cụ	Mô tả
`cortex_ask`	Câu hỏi ngôn ngữ tự nhiên về các dự án của bạn
`get_status`	Trạng thái hệ thống và thống kê đồ thị
`list_projects`	Liệt kê các dự án đã đăng ký
`find_entity`	Tra cứu thực thể theo tên
`query_cortex`	Truy vấn đồ thị tri thức có cấu trúc
`get_contradictions`	Liệt kê các mâu thuẫn đã phát hiện
`resolve_contradiction`	Giải quyết một mâu thuẫn
`search_entities`	Tìm kiếm thực thể với bộ lọc
`ingest_file`	Kích hoạt nhập tệp
`add_project`	Đăng ký một dự án mới
`remove_project`	Hủy đăng ký một dự án
`session_brief`	Tóm tắt ngữ cảnh cho phiên hiện tại

Kiến trúc

Monorepo với tám gói:

@cortex/core — kiểu, EventBus, trình tải cấu hình, lớp lỗi
@cortex/ingest — trình phân tích cú pháp tệp (tree-sitter + remark), trình chia đoạn, trình theo dõi, quy trình
@cortex/graph — kho lưu trữ SQLite, vector LanceDB, công cụ truy vấn
@cortex/llm — nhà cung cấp Anthropic/Gemini/tương thích OpenAI/Ollama, bộ định tuyến, lời nhắc, bộ nhớ đệm
@cortex/cli — CLI Commander.js
@cortex/mcp — máy chủ Model Context Protocol (vận chuyển stdio, 12 công cụ)
@cortex/server — Express REST API + chuyển tiếp WebSocket
@cortex/web — Bảng điều khiển web React + Vite + D3

Tài liệu kiến trúc: docs/

Quyền riêng tư & Bảo mật

Các tệp được phân loại là restricted không bao giờ được gửi đến LLM đám mây
Các tệp nhạy cảm (.env, .pem, .key) được tự động phát hiện và chặn
Bí mật khóa API được quét và biên tập lại trước khi truyền lên đám mây
Tất cả dữ liệu được lưu trữ cục bộ trong ~/.cortex/ — không có gì gọi về nhà

Kiến trúc bảo mật đầy đủ: docs/security.md

Được xây dựng bằng

SQLite qua better-sqlite3 — lưu trữ thực thể và quan hệ
LanceDB — nhúng vector cho tìm kiếm ngữ nghĩa
Anthropic Claude — nhà cung cấp LLM đám mây
Google Gemini — nhà cung cấp LLM đám mây (qua API tương thích OpenAI)
DeepSeek — nhà cung cấp LLM đám mây (suy luận + trò chuyện)
Groq — suy luận đám mây tốc độ cao
Ollama — suy luận LLM cục bộ
tree-sitter — phân tích tệp theo ngôn ngữ
Chokidar — theo dõi tệp đa nền tảng
Commander.js — khung CLI
React + Vite — bảng điều khiển web
D3 — trực quan hóa đồ thị tri thức

Đóng góp

Xem CONTRIBUTING.md để biết hướng dẫn.

Giấy phép

MIT — xem LICENSE

Giới thiệu

Được xây dựng bởi GZOO — một nền tảng tự động hóa kinh doanh sử dụng AI.

Cortex khởi đầu là một công cụ nội bộ để duy trì ngữ cảnh qua nhiều dự án khách hàng. Chúng tôi đã mở mã nguồn vì mọi lập trình viên làm việc trên nhiều thứ đều mất ngữ cảnh, và chúng tôi tin rằng cách tiếp cận này — tự động theo dõi tệp + đồ thị tri thức + truy vấn ngôn ngữ tự nhiên — là cách đúng đắn để giải quyết vấn đề đó.