cortex

Cortex MCP

@danielblomma/cortex-mcp is a local, repo-scoped context platform for coding assistants. It indexes your codebase into structured entities (files, rules, ADRs) and exposes that context over MCP (JSON-RPC over stdio).

Why Use Cortex

• Semantic search across code and documentation.
• Graph relationships between entities and architectural constraints.
• Local-first: your code and context stay on your machine.
• Incremental updates keep context fresh as the repo changes.
• Works with Claude Code/Desktop and Codex MCP clients.

Core Features

• Semantic search across files, rules, and ADRs.
• Graph relationships between entities and architectural constraints.
• Architectural rules and ADR context for implementation decisions.
• Live TUI dashboard showing what Cortex adds to your repo.

Requirements

• Node.js 18+
• Git repository
• Optional for auto-connection: claude and/or codex CLI in PATH

Install

npm i -g @danielblomma/cortex-mcp

Quick Start

From the repository you want to index:

cortex init --bootstrap

This will:

• scaffold .context/, scripts/, mcp/, .githooks/, and docs files
• activate git hooks for checkout, pull/merge, commit, and rewrite events
• build and prepare the local MCP server
• try to auto-register MCP connections for Claude/Codex (if installed)
• start background sync unless disabled

Disable watcher setup:

cortex init --bootstrap --no-watch

Check context status:

cortex status

Verify MCP Connection

Claude:

claude mcp list

Codex:

codex mcp list

Claude Plugin Marketplace

Install via Claude Code plugin marketplace:

/plugin marketplace add DanielBlomma/cortex
/plugin install cortex@cortex-marketplace
/plugin enable cortex

Then initialize Cortex in your target repository:

cortex init --bootstrap

Manual MCP Configuration

If auto-registration is unavailable, configure MCP manually.

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "cortex": {
      "command": "cortex",
      "args": ["mcp"],
      "env": {
        "CORTEX_PROJECT_ROOT": "/absolute/path/to/your-project"
      }
    }
  }
}

Codex (~/.config/codex/mcp-config.json):

{
  "mcpServers": {
    "cortex-myproject": {
      "command": "cortex",
      "args": ["mcp"],
      "cwd": "/absolute/path/to/your-project"
    }
  }
}

MCP Tools

context.search

Ranked context search across indexed entities.

Input:

• query (string, required)
• top_k (int, 1-20, default 5)
• include_deprecated (bool, default false)
• include_content (bool, default false)

context.get_related

Fetch entity relationships from the graph.

Input:

• entity_id (string, required)
• depth (int, 1-3, default 1)
• include_edges (bool, default true)

context.get_rules

List indexed rules and optionally include inactive rules.

Input:

• scope (string, optional)
• include_inactive (bool, default false)

context.reload

Reload the RyuGraph connection after updates/maintenance.

Input:

• force (bool, default true)

Example Prompts

• "Find files that handle authentication."
• "Show related files for this ADR."
• "What active architectural rules apply to this API?"

Dashboard

A live TUI that shows what Cortex adds to your repository at a glance.

cortex dashboard

The dashboard displays: