# Cortex MCP

Cortex is an advanced Model Context Protocol (MCP) server that supercharges your AI assistant with **Domain-Driven Design Topology** and **Vector Mathematics**.

It is designed to solve the two biggest problems with AI coding assistants:
1. They hallucinate architectural boundaries (e.g. telling your frontend to query your database directly).
2. They get lost in large codebases due to context limits.

Cortex acts as a localized brain for your repository, mapping your codebase into a strict Topological Graph, and cross-referencing it with a native SQLite Vector Database.

## Setup & Installation

Setting up Cortex is a simple process. Navigate to your project root and choose your AI assistant below to copy-paste the complete initialization block:

---

### Setup for Cursor

Run this block in your project root to install Cortex globally, auto-index your documentation, and automatically attach the MCP server to Cursor:

```bash
npm install -g cortex-kb
cortex init cursor
cursor mcp add cortex -- cortex
```
*(Prefer manual GUI setup? See the [Cursor MCP Documentation](https://docs.cursor.com/advanced/models#mcp).)*

### Setup for Antigravity (AGY)

Run this block in your project root to install Cortex globally, auto-index your documentation, and automatically attach the MCP server to Antigravity:

```bash
npm install -g cortex-kb
cortex init antigravity
agy mcp install cortex cortex
```
*(Prefer manual GUI setup? See the [Antigravity MCP Documentation](https://antigravity.google/docs/mcp).)*

### Setup for GitHub Copilot

Run this block in your project root to install Cortex globally, auto-index your documentation, and automatically attach the MCP server to Copilot:

```bash
npm install -g cortex-kb
cortex init copilot
codex mcp add cortex -- cortex
```
*(Prefer manual JSON setup? See the [GitHub Copilot MCP Documentation](https://docs.github.com/en/copilot/how-tos/provide-context/use-mcp-in-your-ide/extend-copilot-chat-with-mcp).)*

### Setup for Claude CLI

Run this block in your project root to install Cortex globally, auto-index your documentation, and automatically attach the MCP server to the Claude CLI:

```bash
npm install -g cortex-kb
cortex init claude
claude mcp add cortex -- cortex
```
*(Using Claude Desktop instead of the CLI? See the [Claude Desktop MCP Documentation](https://code.claude.com/docs/en/mcp-quickstart).)*

### Setup for Codex

Run this block in your project root to install Cortex globally, auto-index your documentation, and automatically attach the MCP server to Codex:

```bash
npm install -g cortex-kb
cortex init codex
codex mcp add cortex -- cortex
```

### Setup for Windsurf

Run this block in your project root to install Cortex globally and auto-index your documentation:

```bash
npm install -g cortex-kb
cortex init windsurf
```
Then, configure the server manually. *(See the [Windsurf MCP Documentation](https://docs.devin.ai/windsurf/plugins/cascade/mcp).)*

---

## The CLI Wrapper

Cortex isn't just for AI. Engineers can use the built-in CLI:

- `cortex start`
  Starts the MCP server (this is what your AI runs).
- `cortex init [provider|file]`
  Bootstraps Cortex, injects AI rules, and auto-indexes the repository.
- `cortex index`
  Indexes all markdown documentation in the current directory into the vector DB.
- `cortex query <term>`
  Performs a lightning-fast natural language semantic search across your codebase directly from your terminal.
- `cortex visualize`
  Generates an interactive HTML visualization of your software architecture graph.

---

## The MCP Tools

When connected, your AI assistant will have access to the following tools:

### Graph Tools
- `add_entity`: Maps a new component/service into the architecture graph.
- `add_edge`: Defines relationships between entities (e.g., DEPENDS_ON).
- `search_entities`: Finds existing entities by name or type.
- `get_blast_radius`: Analyzes the impact of a component by fetching its rich markdown and all connected dependencies.
- `expand_ontology`: Adds new allowed node/edge types dynamically.
- `run_custom_query`: Runs custom SQLite `SELECT` queries against the knowledge base for advanced topology analysis.

### Vector Tools
- `index_directory`: Recursively chunks and embeds markdown documentation.
- `index_file`: Embeds a specific file.
- `semantic_search`: Finds relevant documentation based on natural language meaning using local L2 distance vector search.

## License
MIT