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 (files, rules, ADRs).
• Graph relationships between entities and constraints.
• Architectural rules and ADR context for implementation decisions.

Advanced Features (Experimental)

Cortex can extract function-level chunks and build call graphs in experimental builds:

• context.find_callers - what calls this function?
• context.trace_calls - what does this function call?
• context.impact_analysis - what is impacted if this function changes?
• Requires JavaScript/TypeScript codebase and semantic chunking/call graph indexing enabled.

These APIs are experimental and may not be exposed in every installation.

Chunking Strategy (Code)

When semantic chunking is enabled, large function/method chunks are split into overlap windows during ingest.

Defaults:

• CORTEX_CHUNK_WINDOW_LINES=80
• CORTEX_CHUNK_OVERLAP_LINES=16
• CORTEX_CHUNK_SPLIT_MIN_LINES=120
• CORTEX_CHUNK_MAX_WINDOWS=8

Behavior:

• Chunks are split only when the chunk body exceeds the split threshold.
• Windows slide forward using configured overlap (next_start = previous_end - overlap).
• The last allowed window always stretches to the end of the chunk body.
• Window chunks inherit metadata (status, source_of_truth) from their parent chunk.
• Window chunks inherit parent graph edges for CALLS and IMPORTS to keep traversal/ranking consistent.

Verification:

• Overlap and windowing regressions are covered in tests/context-regressions.test.mjs.

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
• 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 semantic search readiness:

cortex status

Look for semantic_search=embedding+lexical (ready) to confirm full semantic mode.

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?"

Common Commands

cortex init [path] [--force] [--bootstrap] [--connect] [--no-connect] [--watch] [--no-watch]
cortex connect [path] [--skip-build]
cortex mcp
cortex bootstrap
cortex update
cortex status
cortex watch [start|stop|status|run|once] [--interval <sec>] [--debounce <sec>] [--mode <auto|event|poll>]
cortex note <title> [text]
cortex plan
cortex todo [text|list|done <id>|reopen <id>|remove <id>]
cortex help

Automated Release

This repository includes two GitHub Actions workflows:

• Release Bump (.github/workflows/release-bump.yml)

  • Manual workflow_dispatch from main
  • Bumps semver (patch/minor/major)
  • Syncs release metadata files (package.json, server.json, plugin manifests)
  • Runs tests
  • Commits and tags vX.Y.Z

• Release Publish (.github/workflows/release-publish.yml)

  • Triggers on tag push v*.*.*
  • Verifies tag/version sync
  • Runs root tests + MCP build/tests
  • Publishes @danielblomma/cortex-mcp to npm

Required GitHub secret:

• NPM_TOKEN (npm automation token with publish rights for @danielblomma/cortex-mcp)

Limitations

• Requires repo initialization (cortex init --bootstrap).
• Each repository has its own local Cortex context instance.
• No cloud sync by design (privacy-first local storage).

Security and Privacy

• Cortex stores context data locally under .context/.
• No source code upload is required for core functionality.

Troubleshooting

• mcp/dist/server.js missing: Run cortex bootstrap (or re-run cortex init --bootstrap).
• claude or codex not found during init: Auto-registration is skipped; use manual config above.
• MCP tools return stale context: Run cortex update, then reconnect MCP or call context.reload from your MCP client.

Support

• Issues: https://github.com/DanielBlomma/cortex/issues
• Marketplace prep notes: docs/MCP_MARKETPLACE.md

License

MIT