GZOO Cortex MCP Server

官方

面向开发者的本地优先知识图谱。监控项目文件，通过LLM提取实体与关系，支持跨项目自然语言查询并附带源代码引用。

GitHub

文档

GZOO Cortex

面向开发者的本地优先知识图谱。 监控你的项目文件，使用 LLM 提取实体和关系，并让你能够用自然语言跨所有项目进行查询。

“我在各个项目中做过哪些架构决策？”

Cortex 从你的 README、TypeScript 文件、配置文件和对话导出中找到决策 — 然后综合出带有源引用的答案。

为什么

你同时处理多个项目。决策、模式和上下文分散在数百个文件中。你忘记了三个月前做的决定。你重新解决已经在另一个仓库中解决过的问题。

Cortex 监控你的项目目录，自动提取知识，并在你需要时将其反馈给你。

它能做什么

监控你的项目文件（md、ts、js、py、json、yaml）的更改
提取实体：决策、模式、组件、依赖关系、约束、行动项
推断跨项目实体之间的关系
检测决策冲突时的矛盾
查询使用自然语言并附带源引用
语义搜索 — 混合关键词和向量（嵌入）相似度，使查询按意义匹配，而不仅仅是关键词（可选；参见语义搜索）
智能路由 在云端和本地 LLM 之间
尊重隐私 — 受限项目永远不会离开你的机器
Web 仪表板 具有知识图谱可视化、实时动态和查询浏览器
MCP 服务器 用于与 Claude Code 直接集成

快速开始

1. 安装

npm install -g @gzoo/cortex

如果全局安装失败并出现 EACCES，请改用用户前缀：

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
路由模式 — 云端优先、混合、本地优先或仅本地
监控目录 — Cortex 应监控哪些目录
预算限制 — 每月 LLM 支出上限

cortex init 将全局配置写入 ~/.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`	Web 仪表板 + API + 文件监控器（`ignoreInitial` — 启动时不重新摄取）
`cortex watch`	仅 CLI 文件监控器（无仪表板）
`cortex ingest`	一次性摄取；事件不会出现在实时动态中

不要同时运行 watch 和 serve — 它们会竞争文件更改。实时动态仅显示来自 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. Web 仪表板

cortex serve                               # open http://localhost:3710

远程访问：

cortex serve --host 0.0.0.0

在非本地主机上会自动强制执行身份验证。一个持有者令牌会自动生成并保存到 ~/.cortex/.env（使用 grep CORTEX_SERVER_AUTH_TOKEN ~/.cortex/.env 读取）。使用 http://<host>:3710/?token=<token> 打开仪表板一次 — 该令牌仅嵌入到已证明拥有它的请求中，然后为浏览器标签页保留（因此匿名访问者永远不会收到它）。反向代理后的 API/WebSocket 调用使用 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 在每次文件更改时运行一个管道：

解析 — 文件内容由语言感知解析器分块（代码使用 tree-sitter，markdown 使用 remark）
提取 — LLM 识别实体（决策、组件、模式等）
关联 — LLM 推断新实体与现有实体之间的关系
检测 — 自动标记矛盾和重复项
存储 — 实体、关系和向量存入 SQLite + LanceDB
查询 — 自然语言查询搜索图谱并综合答案

所有数据都保存在本地的 ~/.cortex/。只有 LLM API 调用会离开你的机器（并且永远不会用于受限项目）。

LLM 提供商

Cortex 是与提供商无关的。它支持：

Anthropic Claude（Sonnet、Haiku）— 通过原生 Anthropic API
Google Gemini — 通过 OpenAI 兼容 API
DeepSeek（Reasoner、Chat）— 强大的推理能力，非常实惠
Groq — 快速推理，有免费套餐
任何 OpenAI 兼容 API — OpenRouter、本地代理等
Ollama（Mistral、Llama 等）— 完全本地，无需云端

成本跟踪对 DeepSeek、Gemini、Groq 和 OpenRouter 模型使用提供商感知的费率 — 而不是统一的 Anthropic 回退。

嵌入（用于语义搜索）被配置为一个独立的提供商 — 独立于你的聊天模型 — 因此你可以在 DeepSeek 上运行聊天，在 OpenAI 上运行嵌入。参见语义搜索。

路由模式

模式	云端成本	质量	需要 Ollama
`cloud-first`	因提供商而异	最高	否
`hybrid`	降低	高	是
`local-first`	最低	良好	是
`local-only`	$0	良好	是

在云端优先模式下，所有任务都路由到你的云端提供商。不需要 Ollama，仅在启用预算回退时使用。混合模式将高容量任务（实体提取、排序）路由到 Ollama，将推理密集型任务（关系推断、查询）路由到你的云端提供商。

要求

Node.js 20+
LLM API 密钥 用于云端模式 — Anthropic、Google Gemini、DeepSeek、Groq 或任何 OpenAI 兼容提供商
Ollama — 仅用于 hybrid、local-first 或 local-only 模式（安装）

配置

配置是分层的 — 后面的源会覆盖前面的：

优先级	位置	范围
1	内置默认值	全局
2	`~/.cortex/cortex.config.json`	全局（由 `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

语义搜索（嵌入）

Cortex 混合了关键词（全文）搜索与向量相似度，因此查询按意义匹配，而不是精确的词语。嵌入是可选的，默认关闭 — 使用云端嵌入提供商启用它们（不需要本地 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

嵌入提供商独立于你的聊天提供商 — 在 DeepSeek（或 Anthropic、Groq 等）上运行聊天，在 OpenAI 上运行嵌入。任何 OpenAI 兼容的嵌入端点都可以使用。

新文件在摄取时会自动嵌入。要为你已经摄取的图谱构建索引，请运行一次性重建索引：

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

命令

命令	描述
`cortex init`	交互式设置向导
`cortex doctor`	验证配置、提供商、项目、密钥和数据库
`cortex projects add/list/remove/show`	管理已注册的项目
`cortex serve`	Web 仪表板 + API + 文件监控器（端口 3710）
`cortex watch [project]`	仅 CLI 文件监控器
`cortex ingest <file-or-glob>`	一次性文件摄取（与实时动态分开）
`cortex reindex [project]`	为现有实体重建语义（嵌入）搜索索引
`cortex query <question>`	带引用的自然语言查询
`cortex find <term>`	按名称查找实体
`cortex status`	图谱统计、成本、提供商状态
`cortex costs`	详细的成本明细
`cortex contradictions`	列出活跃的矛盾
`cortex resolve <id>`	解决一个矛盾
`cortex models list/pull/test/info`	管理 Ollama 模型
`cortex mcp`	为 Claude Code 启动 MCP 服务器
`cortex report`	摄取后摘要
`cortex privacy set/list`	设置目录隐私
`cortex config list/get/set/validate`	读取/写入配置
`cortex config exclude add/remove/list`	管理文件/目录排除
`cortex stop` / `cortex restart`	管理正在运行的监控/服务进程
`cortex db`	数据库操作

完整 CLI 参考：docs/cli-reference.md

Web 仪表板

运行 cortex serve 以在 http://localhost:3710 打开一个完整的 Web 仪表板，包含：

仪表板主页 — 图谱统计、近期活动、实体类型细分
知识图谱 — 交互式 D3 力导向图，具有聚类功能，点击可探索
实时动态 — 通过 WebSocket 实时显示文件更改和实体提取事件（仅来自 cortex serve）
查询浏览器 — 带有流式响应的自然语言查询
矛盾解决器 — 审查和解决冲突的决策

远程部署

对于本地主机之外的访问，绑定到所有接口并将 Cortex 置于反向代理之后：

cortex serve --host 0.0.0.0

示例 nginx 配置 — 使用基本身份验证保护 /api/ 和 /ws；无需身份验证即可提供静态资源（仪表板将持有者令牌注入 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

这为 Claude Code 提供了 12 个工具：

工具	描述
`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 — 类型、EventBus、配置加载器、错误类
@cortex/ingest — 文件解析器（tree-sitter + remark）、分块器、监控器、管道
@cortex/graph — SQLite 存储、LanceDB 向量、查询引擎
@cortex/llm — Anthropic/Gemini/OpenAI 兼容/Ollama 提供商、路由器、提示、缓存
@cortex/cli — Commander.js CLI
@cortex/mcp — 模型上下文协议服务器（stdio 传输，12 个工具）
@cortex/server — Express REST API + WebSocket 中继
@cortex/web — React + Vite + D3 Web 仪表板

架构文档：docs/

隐私与安全

分类为 restricted 的文件绝不会发送到云端 LLM
敏感文件（.env、.pem、.key）会被自动检测并阻止
API 密钥机密在任何云端传输前都会被扫描和编辑
所有数据都存储在本地 ~/.cortex/ — 不会回传任何信息

完整安全架构：docs/security.md

构建工具

SQLite 通过 better-sqlite3 — 实体与关系存储
LanceDB — 用于语义搜索的向量嵌入
Anthropic Claude — 云端大语言模型提供商
Google Gemini — 云端大语言模型提供商（通过兼容 OpenAI 的 API）
DeepSeek — 云端大语言模型提供商（推理 + 对话）
Groq — 快速云端推理
Ollama — 本地大语言模型推理
tree-sitter — 语言感知的文件解析
Chokidar — 跨平台文件监控
Commander.js — 命令行界面框架
React + Vite — Web 仪表盘
D3 — 知识图谱可视化

贡献

请参阅 CONTRIBUTING.md 了解指南。

许可证

MIT — 详见 LICENSE

关于

由 GZOO 构建 — 一个 AI 驱动的业务自动化平台。

Cortex 最初是一个内部工具，用于在多个客户项目中维护上下文。我们将其开源，因为每个同时处理多项事务的开发者都会丢失上下文，而我们相信这种方式——自动文件监控 + 知识图谱 + 自然语言查询——是解决这个问题的正确途径。