GZOO Cortex MCP Server

oficial

Grafo de conhecimento local para desenvolvedores. Monitora arquivos do projeto, extrai entidades e relacionamentos via LLMs, e permite consultar entre projetos com linguagem natural e citações de fontes.

GitHub

Documentação

GZOO Cortex

Grafo de conhecimento local-first para desenvolvedores. Monitora os arquivos dos seus projetos, extrai entidades e relacionamentos usando LLMs e permite consultar todos os seus projetos em linguagem natural.

“Quais decisões de arquitetura tomei entre os projetos?”

O Cortex encontra decisões nos seus READMEs, arquivos TypeScript, arquivos de configuração e exportações de conversas — e então sintetiza uma resposta com citações das fontes.

Por quê

Você trabalha em vários projetos. Decisões, padrões e contexto estão espalhados por centenas de arquivos. Você esquece o que decidiu três meses atrás. Você resolve problemas que já havia resolvido em outro repositório.

O Cortex monitora os diretórios dos seus projetos, extrai conhecimento automaticamente e o devolve quando você precisa.

O que ele faz

Monitora seus arquivos de projeto (md, ts, js, py, json, yaml) em busca de alterações
Extrai entidades: decisões, padrões, componentes, dependências, restrições, itens de ação
Infere relacionamentos entre entidades entre projetos
Detecta contradições quando decisões entram em conflito
Consulta em linguagem natural com citações das fontes
Busca semanticamente — combina similaridade por palavra-chave e vetorial (embedding) para que as consultas correspondam por significado, não apenas por palavras-chave (opcional; veja Busca Semântica)
Roteia de forma inteligente entre LLMs locais e na nuvem
Respeita a privacidade — projetos restritos nunca saem da sua máquina
Painel web com visualização do grafo de conhecimento, feed ao vivo e explorador de consultas
Servidor MCP para integração direta com o Claude Code

Início Rápido

1. Instalar

npm install -g @gzoo/cortex

Se a instalação global falhar com EACCES, use um prefixo de usuário:

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

Ou instale a partir do código fonte:

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

Verifique: cortex --version (versão atual: 0.8.1)

2. Configuração

Execute o assistente interativo:

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

Ele o guiará por:

Provedor LLM — Anthropic, Google Gemini, DeepSeek, Groq, OpenRouter ou Ollama (local)
Chave de API — salva com segurança em ~/.cortex/.env
Modo de roteamento — cloud-first, híbrido, local-first ou somente local
Diretórios monitorados — quais diretórios o Cortex deve monitorar
Limite de orçamento — teto de gastos mensais com LLM

cortex init grava a configuração global em ~/.cortex/cortex.config.json. As chaves de API vão em ~/.cortex/.env.

3. Registrar Projetos

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

4. Ingerir, Monitorar e Consultar

Preencha os arquivos existentes primeiro — o monitor só capta novas alterações:

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

Comando	O que faz
`cortex serve`	Painel web + API + monitor de arquivos (`ignoreInitial` — sem reingestão ao iniciar)
`cortex watch`	Monitor de arquivos somente CLI (sem painel)
`cortex ingest`	Ingestão única; os eventos não aparecem no Feed ao Vivo

Não execute watch e serve juntos — eles competem pelas alterações de arquivo. O Feed ao Vivo mostra eventos em tempo real apenas do cortex serve (arquivos salvos enquanto o servidor está em execução).

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

cortex serve                               # open http://localhost:3710

Acesso remoto:

cortex serve --host 0.0.0.0

A autenticação é aplicada automaticamente em hosts que não sejam localhost. Um token de portador é gerado automaticamente e salvo em ~/.cortex/.env (leia-o com grep CORTEX_SERVER_AUTH_TOKEN ~/.cortex/.env). Abra o painel uma vez com http://<host>:3710/?token=<token> — o token é incorporado apenas para solicitações que já comprovem sua posse e é mantido para a aba do navegador (para que visitantes anônimos nunca o recebam). Chamadas de API/WebSocket atrás de um proxy reverso usam Authorization: Bearer <token>.

Excluindo Arquivos e Diretórios

O Cortex ignora node_modules, dist, .git e outros diretórios comuns por padrão. Para adicionar mais:

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

Como Funciona

O Cortex executa um pipeline a cada alteração de arquivo:

Analisar — o conteúdo do arquivo é dividido em partes por um analisador ciente da linguagem (tree-sitter para código, remark para markdown)
Extrair — o LLM identifica entidades (decisões, componentes, padrões, etc.)
Relacionar — o LLM infere relacionamentos entre entidades novas e existentes
Detectar — contradições e duplicatas são sinalizadas automaticamente
Armazenar — entidades, relacionamentos e vetores vão para SQLite + LanceDB
Consultar — consultas em linguagem natural pesquisam o grafo e sintetizam respostas

Todos os dados permanecem locais em ~/.cortex/. Apenas as chamadas à API do LLM saem da sua máquina (e nunca para projetos restritos).

Provedores de LLM

O Cortex é agnóstico em relação ao provedor. Ele suporta:

Anthropic Claude (Sonnet, Haiku) — via API nativa da Anthropic
Google Gemini — via API compatível com OpenAI
DeepSeek (Reasoner, Chat) — raciocínio forte, muito acessível
Groq — inferência rápida com camada gratuita
Qualquer API compatível com OpenAI — OpenRouter, proxies locais, etc.
Ollama (Mistral, Llama, etc.) — totalmente local, sem necessidade de nuvem

O rastreamento de custos usa taxas cientes do provedor para modelos DeepSeek, Gemini, Groq e OpenRouter — não um fallback genérico da Anthropic.

Embeddings (para busca semântica) são configurados como um provedor separado — independente do seu modelo de chat — para que você possa executar o chat no DeepSeek e os embeddings no OpenAI. Veja Busca Semântica.

Modos de Roteamento

Modo	Custo na Nuvem	Qualidade	Ollama Necessário
`cloud-first`	Varia por provedor	Mais alta	Não
`hybrid`	Reduzido	Alta	Sim
`local-first`	Mínimo	Boa	Sim
`local-only`	$0	Boa	Sim

No modo cloud-first, todas as tarefas são roteadas para o seu provedor de nuvem. O Ollama não é necessário e só é usado se o fallback de orçamento estiver habilitado. O modo híbrido roteia tarefas de alto volume (extração de entidades, classificação) para o Ollama e tarefas com raciocínio pesado (inferência de relacionamentos, consultas) para o seu provedor de nuvem.

Requisitos

Node.js 20+
Chave de API do LLM para modos em nuvem — Anthropic, Google Gemini, DeepSeek, Groq ou qualquer provedor compatível com OpenAI
Ollama — apenas para os modos hybrid, local-first ou local-only (instalar)

Configuração

A configuração é em camadas — fontes posteriores substituem as anteriores:

Prioridade	Localização	Escopo
1	Padrões internos	Global
2	`~/.cortex/cortex.config.json`	Global (criado por `cortex init`)
3	`./cortex.config.json`	Substituições do projeto (opcional)
4	Variáveis de ambiente `CORTEX_*`	Sessão

As chaves de API são armazenadas separadamente em ~/.cortex/.env (nunca no JSON de configuração).

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

Referência completa de configuração: docs/configuration.md

Busca Semântica (Embeddings)

O Cortex combina busca por palavra-chave (texto completo) com similaridade vetorial, para que as consultas correspondam por significado em vez de palavras exatas. Os embeddings são opcionais e desativados por padrão — habilite-os com um provedor de embeddings na nuvem (sem necessidade de GPU local ou 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

O provedor de embeddings é independente do seu provedor de chat — execute o chat no DeepSeek (ou Anthropic, Groq, …) e os embeddings no OpenAI. Qualquer endpoint de embeddings compatível com OpenAI funciona.

Novos arquivos recebem embedding automaticamente conforme são ingeridos. Para construir o índice de um grafo que você já ingeriu, execute uma reindexação única:

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

Comandos

Comando	Descrição
`cortex init`	Assistente de configuração interativo
`cortex doctor`	Validar configuração, provedores, projetos, segredos e banco de dados
`cortex projects add/list/remove/show`	Gerenciar projetos registrados
`cortex serve`	Painel web + API + monitor de arquivos (porta 3710)
`cortex watch [project]`	Monitor de arquivos somente CLI
`cortex ingest <file-or-glob>`	Ingestão única de arquivos (separada do Feed ao Vivo)
`cortex reindex [project]`	Reconstruir o índice de busca semântica (embedding) para entidades existentes
`cortex query <question>`	Consulta em linguagem natural com citações
`cortex find <term>`	Encontrar entidades por nome
`cortex status`	Estatísticas do grafo, custos, status do provedor
`cortex costs`	Detalhamento detalhado de custos
`cortex contradictions`	Listar contradições ativas
`cortex resolve <id>`	Resolver uma contradição
`cortex models list/pull/test/info`	Gerenciar modelos do Ollama
`cortex mcp`	Iniciar servidor MCP para Claude Code
`cortex report`	Resumo pós-ingestão
`cortex privacy set/list`	Definir privacidade do diretório
`cortex config list/get/set/validate`	Ler/escrever configuração
`cortex config exclude add/remove/list`	Gerenciar exclusões de arquivos/diretórios
`cortex stop` / `cortex restart`	Gerenciar processos de monitoramento/servidor em execução
`cortex db`	Operações de banco de dados

Referência completa da CLI: docs/cli-reference.md

Painel Web

Execute cortex serve para abrir um painel web completo em http://localhost:3710 com:

Painel Inicial — estatísticas do grafo, atividade recente, divisão por tipo de entidade
Grafo de Conhecimento — grafo de força D3 interativo com agrupamento, clique para explorar
Feed ao Vivo — eventos de alteração de arquivo e extração de entidade em tempo real via WebSocket (apenas do cortex serve)
Explorador de Consultas — consultas em linguagem natural com respostas em streaming
Resolvedor de Contradições — revisar e resolver decisões conflitantes

Implantação Remota

Para acesso além do localhost, vincule a todas as interfaces e coloque o Cortex atrás de um proxy reverso:

cortex serve --host 0.0.0.0

Exemplo de configuração nginx — proteja /api/ e /ws com autenticação básica; sirva ativos estáticos sem autenticação (o painel injeta o token de portador no 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;
}

Defina CORTEX_SERVER_AUTH_TOKEN ou server.auth.token na configuração. Quando a autenticação está habilitada, o Cortex injeta o token no HTML do painel para que as chamadas de API e WebSocket se autentiquem automaticamente.

Servidor MCP (Integração com Claude Code)

O Cortex inclui um servidor MCP para que o Claude Code possa consultar seu grafo de conhecimento diretamente:

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

Isso fornece ao Claude Code 12 ferramentas:

Ferramenta	Descrição
`cortex_ask`	Perguntas em linguagem natural sobre seus projetos
`get_status`	Status do sistema e estatísticas do grafo
`list_projects`	Listar projetos registrados
`find_entity`	Procurar entidades por nome
`query_cortex`	Consultas estruturadas ao grafo de conhecimento
`get_contradictions`	Listar contradições detectadas
`resolve_contradiction`	Resolver uma contradição
`search_entities`	Pesquisar entidades com filtros
`ingest_file`	Acionar ingestão de arquivos
`add_project`	Registrar um novo projeto
`remove_project`	Cancelar o registro de um projeto
`session_brief`	Resumo do contexto para a sessão atual

Arquitetura

Monorepo com oito pacotes:

@cortex/core — tipos, EventBus, carregador de configuração, classes de erro
@cortex/ingest — analisadores de arquivo (tree-sitter + remark), divisor, monitor, pipeline
@cortex/graph — armazenamento SQLite, vetores LanceDB, mecanismo de consulta
@cortex/llm — provedores Anthropic/Gemini/compatível com OpenAI/Ollama, roteador, prompts, cache
@cortex/cli — CLI Commander.js
@cortex/mcp — servidor Model Context Protocol (transporte stdio, 12 ferramentas)
@cortex/server — API REST Express + retransmissão WebSocket
@cortex/web — Painel web React + Vite + D3

Documentação de arquitetura: docs/

Privacidade e Segurança

Arquivos classificados como restricted nunca são enviados para LLMs na nuvem
Arquivos sensíveis (.env, .pem, .key) são detectados e bloqueados automaticamente
Segredos de chave de API são escaneados e redigidos antes de qualquer transmissão para a nuvem
Todos os dados armazenados localmente em ~/.cortex/ — nada é enviado para casa

Arquitetura de segurança completa: docs/security.md

Construído Com

SQLite via better-sqlite3 — armazenamento de entidades e relacionamentos
LanceDB — embeddings vetoriais para busca semântica
Anthropic Claude — provedor de LLM em nuvem
Google Gemini — provedor de LLM em nuvem (via API compatível com OpenAI)
DeepSeek — provedor de LLM em nuvem (raciocínio + chat)
Groq — inferência rápida em nuvem
Ollama — inferência local de LLM
tree-sitter — análise de arquivos com reconhecimento de linguagem
Chokidar — monitoramento de arquivos multiplataforma
Commander.js — framework CLI
React + Vite — painel web
D3 — visualização de grafo de conhecimento

Contribuindo

Consulte CONTRIBUTING.md para diretrizes.

Licença

MIT — veja LICENSE

Sobre

Criado pela GZOO — uma plataforma de automação de negócios baseada em IA.

O Cortex começou como uma ferramenta interna para manter o contexto entre vários projetos de clientes. Nós o tornamos open-source porque todo desenvolvedor que trabalha em mais de uma coisa perde contexto, e acreditamos que esta abordagem — monitoramento automático de arquivos + grafo de conhecimento + consultas em linguagem natural — é a maneira certa de resolver isso.