Cortex

What gzoonet/cortex MCP server does

gzoonet/cortex MCP server builds a local knowledge graph from developer project files. It watches configured directories, processes supported file types, and extracts entities such as architecture decisions, components, dependencies, constraints, patterns, and action items. It also infers relationships across entities and projects, identifies contradictions and duplicates, and supports natural-language queries with source citations.

The project includes a CLI and a web dashboard. The dashboard provides a graph visualization, live ingestion feed, and query explorer. The CLI can register projects, ingest existing files, query the graph, search for entities, and list contradictions. The MCP integration exposes four tools: getstatus, listprojects, findentity, and querycortex.

How it works

For each file change, the processing pipeline parses content into chunks, uses an LLM to extract entities, relates new entities to existing ones, checks for conflicts and duplicates, and stores the results. SQLite holds graph data, while LanceDB stores vectors. Queries combine graph information with natural-language synthesis. Optional semantic search blends keyword matching with embedding similarity; embeddings are configured separately from the chat model and are disabled by default.

All stored data remains under ~/.cortex/. LLM requests can leave the machine when a cloud provider is configured, except for restricted projects, which are kept local. Routing modes include cloud-first, hybrid, local-first, and local-only. Hybrid and local modes require Ollama; cloud modes can use Anthropic, Google Gemini, DeepSeek, Groq, OpenRouter, or another OpenAI-compatible endpoint.

Setup and configuration

Install the CLI globally with npm install -g @gzoo/cortex, then run cortex init to configure an LLM provider, credentials, routing mode, watched directories, and a monthly budget. cortex doctor checks configuration, providers, and the database. Global settings are written to ~/.cortex/cortex.config.json, while API keys are stored in ~/.cortex/.env.

Register directories with cortex projects add, backfill existing files with cortex ingest, and start ongoing processing with cortex serve or cortex watch. These modes should not run at the same time because they compete for file changes. cortex serve also starts the dashboard and API, normally at http://localhost:3710.

Configuration can come from built-in defaults, the global file, an optional project-level cortex.config.json, and CORTEX_* environment variables. Exclusion rules and restricted paths are managed through CLI commands.

Tools and capabilities

The gzoonet/cortex MCP server provides:

• getstatus for checking the system state.
• listprojects for listing registered projects.
• findentity for locating entities in the graph.
• querycortex for asking natural-language questions against the indexed knowledge.

The broader application also supports contradiction reports, entity expansion, source citations, semantic search, project watching, and dashboard-based graph exploration.

Limitations and notes

Node.js 20 or newer is required. Cloud routing needs an API key for the selected provider, while local-only operation requires Ollama. Semantic search needs a separately configured embeddings provider and is not enabled by default. Initial existing content requires an explicit ingest because the watcher does not re-ingest all files when it starts. The README documents direct MCP integration with Claude Code; it does not specify configuration for Claude Desktop, Cursor, Windsurf, or Cline.