Cortex MCP server
Commit Sep 19, 2026Provides an offline-first codebase knowledge graph and structural context to AI coding agents via MCP and CLI.
Also known as fazalur076/Cortex
- Stars
- 7
- Tools
- 13
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Sep 19, 2026
- License
- MIT
What is Cortex MCP?
Cortex provides an offline-first codebase knowledge graph and structural context to AI coding agents via MCP and CLI. It exposes 13 tools, such as ctx_project_summary, ctx_feature, ctx_symbol.
Summary generated from the project's README
About Cortex MCP server
Providing structural codebase intelligence to AI coding agents is what Cortex enables through a local, offline-first knowledge graph. Developers using tools like Cursor, Claude Code, Antigravity, or VS Code can connect this engine via MCP or the CLI to gain deterministic context without relying on fuzzy vector search or expensive cloud APIs. It works by parsing local source files into a SQLite graph, allowing for precise symbol lookups and dependency tracing across various languages including TypeScript, Go, Python, and Rust.
Users interact with the system through the `ctx` command or native MCP tools to perform complex tasks like impact analysis and schema drift detection. The engine operates entirely on the local machine with zero network calls, ensuring privacy and eliminating API costs. It features a specialized lean mode to reduce token consumption for LLM prompts and includes a real-time watcher to update the structural index in under 200ms as files change.
What you can do with it
- 1Analyze code change impactDetermine the cumulative blast radius and affected tests for all staged or modified files in a git diff.
- 2Detect database schema driftIdentify mismatches between database migrations and active code queries to prevent deployment errors.
- 3Extract feature context for agentsGenerate a structured summary of all services, controllers, and routes associated with a specific feature module.
- 4Reduce LLM token usageProvide high-density, single-line summaries of symbols and impacts to save context window space.
Written from the project's README. Every use case is checked against a quote from it.
Cortex MCP tools 13
Detected from the READMEctx_project_summaryctx_featurectx_symbolctx_impactctx_planctx_searchctx_schema_driftctx_sql_driftctx_doctorctx_check_routesctx_audit_targetctx_suggest
| ctx_project_summary | — | |
| ctx_feature | — | |
| ctx_symbol | — | |
| ctx_impact | — | |
| ctx_plan | — | |
| ctx_search | — | |
| ctx_schema_drift | — | |
| ctx_sql_drift | — | |
| ctx_doctor | — | |
| ctx_check_routes | — | |
| ctx_audit_target | — | |
| ctx_suggest | — |
Show all 13 toolsShow fewer tools
ctx_feat_extract
| ctx_feat_extract | — |
Automated checks
Ran Nov 15, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablefazalur076/cortex is public and reachablegithub.com/fazalur076/cortex ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-09-19github.com/fazalur076/cortex ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model13 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNo tool named like delete, drop or execPass
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubCortex (cortex / ctx)
Fast, fully offline repository intelligence engine and MCP context server for AI coding agents and developers.
Cortex is a single-binary repository intelligence engine. It doesn't generate code, call cloud APIs, or require API keys. Instead, it reads your local source files, parses structural relationships (AST symbols, imports, API routes, UI components), and stores them in a local SQLite graph.
Whether you are using Cursor, Claude Code, Antigravity, VS Code, or working directly in the terminal, Cortex gives AI tools and human developers instant structural codebase context with zero API keys and zero cloud bills.
AI Coding Tools
Claude Code • Cursor • Antigravity • VS Code
│
queries via MCP / CLI
▼
┌───────────────────┐
│ Cortex (`ctx`) │
└─────────┬─────────┘
│
Local SQLite Knowledge Graph
(~/.cortex/repos/your-app)
Why Cortex?
Most AI context tools rely on fuzzy vector search (RAG) or force your AI agent to read thousands of lines of raw files over and over.
This causes two major issues:
- High Token Bills & Sluggish Response: Reading whole repositories burns 100k+ tokens per prompt.
- AI Guesses & Breaking Changes: Vector embeddings only find text that looks similar. They cannot reliably tell you if editing
AuthServicewill affect React pages, API endpoints, permissions, or tests.
Cortex solves this deterministically:
- Zero Cloud Calls: 100% local compiled Go binary. Zero code leaves your computer.
- Evidence-backed Dependencies: Uses structural graph traversal with explicit evidence confidence. Go declarations use the native Go parser; other language extractors currently use heuristics.
- Whole-Changeset Git Diff Impact (
ctx diff-impact/ctx impact --diff): Computes cumulative blast radius and reverse dependency paths across all staged, modified, and untracked files in the working tree in a single call. - Database Schema Drift (
ctx schema-drift/ctx sql-drift): Statically cross-references database migration columns against active code queries to catch phantom queries, column drift, and dropped columns before deploy. - Token-Lean Mode (
--lean/--llm): High-density single-line outputs saving up to 85% context tokens for agent prompts across symbol, impact, and schema drift checks. - Feature Context (
ctx explain): Gives structured feature overviews aggregating services, controllers, models, components, and routes without reading unrelated files. - Cross-Repository Feature Extraction (
ctx feat-extract): Slices AST symbol definitions, 2-hop import dependency graphs, and source code ranges into portable markdown reference artifacts for AI agents. - Local & Global Scoping (
--local/--global/--exclude-current): Query strictly within the active project or search across all indexed repos on your machine. - Pre-Change Impact Analysis (
ctx impact): Shows statically discovered dependents and routes before code is changed; compiler and tests remain the correctness checks. - Real-Time Watcher (
ctx watch): Listens to OS kernel file saves (fsnotify) and updates AST diffs in under 200ms with periodic hash verification (--verify).
The important split is simple:
- Cortex CLI commands produce deterministic repository facts.
- Cortex MCP tools expose those same facts, plus compact evidence packets for planning, explanation, review, and verification.
- The connected MCP host LLM performs reasoning and synthesis. Cortex itself does not run hosted inference.
Features
- Whole-Changeset Git Diff Impact (
ctx diff-impact [ref]orctx impact --diff): Analyzes the cumulative blast radius, changed files, and affected tests across working-tree modifications or git commits in one unified command. - Database Schema Drift Detector (
ctx schema-drift/ctx sql-drift): Detects column drift, queries targeting dropped columns, and phantom table columns by cross-referencing database migrations with codebase queries. - Token-Lean Output Mode (
--lean/--llm): Generates compact, single-line summaries tailored specifically for AI agent context windows, dramatically reducing token consumption across symbol, impact, and schema checks. - Tiered Impact Summaries (
--summary) & Path Scoping (--path): Quickly summarizes blast radius in structured tiers and allows monorepo engineers to scope impact analysis to specific sub-packages (e.g.--path apps/web). - Code-Only & Noise Filtering: Automatically ignores
.agents/,.cursor/,.claude/,.gemini/, and documentation markdown files (.md,.markdown,.mdx) during AST symbol lookups to prevent agent configuration and documentation from polluting code results. - Cross-Stack Route Tracing: Deterministically bridges frontend TypeScript/JavaScript API client calls (
apiClient.get(...),fetch(...),axios(...)) to backend route configurations (e.g. Djangourls.pywith path converters andinclude()mount prefixes) and backend view handlers (views.py). - Feature Context (
ctx explain <feature>): Aggregates services, controllers, models, components, hooks, and API routes associated with a feature module into a single structured summary. - Cross-Repository Feature Extraction (
ctx feat-extract): Slices AST symbol definitions, file dependencies, import DAG graphs, and exact line ranges from another local repository into a standalone workspace reference Markdown file (<feature>-ref.md). Supports auto-searchingglobalor targetproject-refwith--max-files,--no-migrations,--no-tests. - Local & Global Query Scoping (
--local/--global/--exclude-current): Restrict searches to the active workspace (--local), query across all indexed repositories in~/.cortex/repos/(--global), or optionally exclude the current repository (--exclude-current). - Blazing Fast: Built in Go with SQLite WAL mode. Scans and indexes 1,000+ files in under 1.5 seconds.
- 100% Offline & Private: Zero network calls, zero LLMs required for indexing, zero API keys.
- AST Symbol Lookup (
ctx symbol <symbol>): Performs exact structural inspection of functions, classes, interfaces, and UI components with source locations, line numbers, and token-lean--leanoutput. - Impact Analysis (
ctx impact <symbol>): Calculates the statically discovered blast radius (affected files, routes, tests) before making code edits. - API Contract Intelligence (
ctx contracts,ctx api-diff): Compares frontend API calls, backend routes, request/response fields, duplicate route ambiguity, and supported SQL database constraints using deterministic evidence. - Route Parameter Validator (
ctx check-routes): Validates backend route/path-parameter contracts. For duplicate route ambiguity and frontend/backend API compatibility, usectx contracts. - Platform Scope Leak Auditor (
ctx audit-target): Flags browser-only globals (window,document) leaking into shared server or mobile packages. - Behavior Facts (
ctx behavior-data <symbol>): Returns deterministic local behavior facts such as calls, reads, writes, conditions, returns, throws, permission checks, and persistence markers. - Permission and Lineage Intelligence (
ctx permissions,ctx lineage): Traces authorization evidence and supported static cross-layer field/data flow. SQL schema evidence is connected when detected; ORM-only database evidence is reported as unknown rather than inferred. - Test Discovery (
ctx tests <target>): Recommends likely focused tests based on imports, references, routes, and feature naming. - Agent Hook Integrations (
ctx integrations): Manages native context hooks across Claude Code, Cursor, Codex, Antigravity, and generic workflows. - Health & Diagnostics (
ctx doctor): Runs environment checks, verifies SQLite DB integrity, index health, file permissions, and MCP configuration. - Native MCP Server (
ctx serve): Plugs natively into Cursor, Claude Code, Antigravity, and other MCP-compatible tools via stdio with 13 built-in tools, full local/global scoping, and feature extraction. - Strict MCP JSON-RPC Protocol Validation: Standardized parameter validation for native MCP tools, returning standard JSON-RPC error code
-32602 Invalid paramsfor missing or malformed fields. - Auto AI Rules Generator (
ctx init): On first run, automatically writes Cortex usage rules into.agents/AGENTS.mdso coding agents understand when to use Cortex, when to inspect source directly, and when to avoid wasteful tool calls. - Polyglot UI & Template Tree Indexing: Indexes UI renders and template inheritance across React/Next.js (
<DataTable>), Vue (<script setup>), Svelte (<Header/>), Django/Flask (render(request, 'list.html'),{% include %}), Flutter (Widget(...)), Android Jetpack Compose (@Composable), and SwiftUI (VStack), enabling instant blast-radius impact analysis (ctx search <UIComponent>). - Polyglot Framework Support: TypeScript/React, Next.js, Vue, Angular, Svelte, Go, Python/Django/FastAPI, Dart/Flutter, Rust, Java/Kotlin, Swift, PHP, C#/.NET, C/C++.
Installation
Download the pre-compiled binary package for your operating system from GitHub Releases.
macOS (Apple Silicon & Intel)
- Download
cortex-macos.zipfrom Releases - Extract and run the installer:
unzip cortex-macos.zip
cd release
bash install.sh
Linux (x86_64 & ARM64)
- Download
cortex-linux.zipfrom Releases - Extract and run the installer:
unzip cortex-linux.zip
cd release
bash install-linux.sh
Windows (PowerShell 5.1 & 7+)
- Download
cortex-windows.zipfrom Releases - Extract and run the installer in PowerShell:
Expand-Archive cortex-windows.zip -DestinationPath release
cd release
.\install.ps1
Note: The installer configures both cortex and ctx commands in your system PATH automatically.
Quickstart
Run inside any software repository:
# 1. Initialize project config and generated .agents/AGENTS.md policy
ctx init
# 2. Build full knowledge graph (< 2 seconds)
ctx build
# 3. View high-level tech stack & module summary
ctx summary
# 4. Inspect feature context and related modules
ctx explain authentication
# 5. Check what breaks before editing a symbol or class
ctx impact AuthMiddleware
# 6. Check cumulative blast radius of all working-tree changes / git diff
ctx impact --diff
# or: ctx diff-impact HEAD~1
# 7. Audit database migrations for column drift or phantom code queries
ctx schema-drift
# or: ctx sql-drift --lean
# 8. Direct AST symbol lookup (with token-lean 1-line output for LLM prompts)
ctx symbol AuthMiddleware --lean
# 9. Search locally inside current project only
ctx search "userRole" --local
# 10. Search globally across all indexed local repositories on your machine
ctx search "authentication" --global
# 11. Search globally while excluding the current repository
ctx search "login" --global --exclude-current
# 12. Cross-Repository Feature Extraction: extract AST symbols, import DAG, & code snippets for AI context
ctx feat-extract global authentication auth-ref.md --max-files 10 --no-migrations
# 13. Inspect deterministic behavior facts for a symbol
ctx behavior-data AuthMiddleware
# 14. Check agent hook integrations (Cursor, Claude, Codex, Antigravity)
ctx integrations status
# 15. Run system health & index diagnostics
ctx doctor
# 16. Start live background watcher with periodic hash verification for real-time AST updates (<200ms)
ctx watch --verify
Note on ctx init and generated agent policy: Running ctx init writes Cortex repository intelligence guidance into .agents/AGENTS.md. Existing Cortex policy sections are upgraded in place, so repeated ctx init runs do not duplicate the policy. AI tools such as Cursor, Claude Code, and Antigravity can use that policy to treat Cortex as the default structural navigation layer without blindly running every Cortex command for every task.
Flags & Options (Useful for Power Users & CI/CD)
ctx build --full: Forces a full repository rebuild and SQLite database schema/format reconciliation.ctx watch --verify: Starts the file watcher and periodically reconciles file hashes against the SQLite index to handle branch swaps cleanly.ctx impact <symbol>:-d, --diff: Computes whole-changeset blast radius across modified/untracked files.--lean(or--llm): High-density 1-liner output saving up to 85% prompt tokens.--summary: Tiered impact summary buckets.--path <dir>: Scopes blast radius to a sub-directory (essential for monorepos).
ctx diff-impact [ref]: Computes cumulative blast radius for working tree or specific git ref (--summary,--lean).ctx schema-drift(aliasctx sql-drift):--lean(or--llm): Compact 1-line summary of database migration drift.--json: Machine-readable JSON output of detected phantom/dropped columns.
ctx symbol <name>:--lean(or--llm): High-density 1-liner with signature, file:line, and caller count.-l, --local: Restrict lookup strictly to current repository.-g, --global: Search symbol across all indexed repositories in~/.cortex/repos/.
ctx search <query>:-l, --local: Restrict search strictly to current repository.-g, --global: Search across all indexed repositories in~/.cortex/repos/.--exclude-current: Exclude active workspace repository from global results.
ctx feat-extract [project-ref|global] <feature> [output-path]:--max-files <int>: Caps maximum number of files extracted (default: 15).--no-migrations: Excludes database migration files (default: true).--no-tests: Excludes test files from extraction.
--json: Outputs command results in structured JSON format (great for CLI scripting, CI/CD workflows, or custom editor extensions).
CLI Command Surface
Cortex CLI commands are deterministic and local. They do not run an LLM, call cloud APIs, or require model/API-key configuration.
Deterministic CLI Commands
| CLI Command | Purpose |
|---|---|
ctx init |
Initializes Cortex config and generated .agents/AGENTS.md policy |
ctx build |
Builds or refreshes the local SQLite knowledge graph (--full for clean rebuild) |
ctx watch |
Watches local files and incrementally refreshes the index (--verify for periodic hash checks) |
ctx doctor |
Checks index health, database integrity, freshness, and environment state |
ctx summary |
Shows repository architecture, language breakdown, modules, and stats |
ctx search <query> |
Searches symbols, files, routes, and indexed source text (--local, --global, --exclude-current) |
ctx symbol <name> |
Shows AST-backed symbol details and usages (--lean for 1-liner token-efficient output) |
ctx impact <target> |
Computes blast radius for a symbol, file, or working tree diff (--diff, --summary, --path, --lean) |
ctx diff-impact [ref] |
Analyzes cumulative blast radius and affected tests across working-tree diff or git ref |
ctx schema-drift |
Detects column drift, dropped column queries, and phantom columns against database migrations (alias: ctx sql-drift) |
ctx routes |
Lists backend API routes discovered from source |
ctx check-routes |
Validates backend route/path-parameter contracts and catches duplicate route strings |
ctx contracts [route] |
Audits frontend/backend/API/supported SQL DB contract evidence, including duplicate route ambiguity |
ctx api-diff |
Audits API contracts touched by the current working-tree diff |
ctx lineage [target] |
Traces matched static data and field flow evidence; unmatched targets return uncertainty |
ctx permissions [target] |
Traces frontend/backend/matrix permission evidence (--role to simulate role) |
ctx tests [target] |
Recommends likely focused tests based on imports, references, routes, and feature naming |
ctx behavior-data <symbol> |
Returns deterministic raw behavior facts for a symbol |
ctx context [task] |
Fast deterministic context packet retrieval for agent hooks |
ctx integrations |
Manages agent hook integrations (status, install, remove for claude/cursor/codex/antigravity) |
ctx known-issues [target] |
Shows current deterministic known issues |
ctx workflows [target] |
Shows evidence-backed local workflow recipes (ctx workflow <name> for specific recipe) |
ctx gate |
Runs Cortex's built-in deterministic regression/self-test precision gates |
ctx audit-target |
Audits shared packages for platform scope leaks (window, document) |
ctx conventions |
Shows detected architectural conventions |
ctx patterns |
Shows local cross-repository pattern memory |
ctx explain <feature> |
Shows deterministic feature context aggregating services, models, routes, and components |
ctx feat-extract ... |
Extracts focused local repository context into standalone Markdown |
ctx serve |
Starts the native MCP server over stdio |
MCP-Only Reasoning Guidance Commands
When run from the CLI, these commands provide operational guidance for connecting and utilizing MCP tools:
| CLI Command | Purpose |
|---|---|
ctx plan |
Guidance for task planning with ctx_plan |
ctx behavior |
Guidance for behavior explanation with ctx_explain_behavior and ctx_behavior_data |
ctx verify-diff |
Guidance for diff review with ctx_review_diff |
ctx verify-task |
Guidance for task verification with ctx_verify_task |
ctx suggest |
Guidance for architectural recommendations with ctx_suggest |
CLI Commands Without Direct MCP Equivalents
These commands are intentionally CLI/local-runtime operations rather than MCP tools:
| CLI Command | Why It Is CLI-Only |
|---|---|
ctx init |
Creates local project configuration and generated repository policy files |
ctx build |
Writes and refreshes the local SQLite index |
ctx watch |
Runs a long-lived local filesystem watcher |
ctx serve |
Starts the MCP server itself |
ctx integrations |
Installs/removes agent hook files in .cursor/, .claude/, etc. |
ctx conventions |
Local convention display command |
ctx patterns |
Local cross-repository pattern-memory display command |
ctx gate |
Precision regression gate execution |
DB Evidence Boundary
Cortex currently treats detected SQL schema/constraint evidence as deterministic DB evidence. Unsupported ORM-only schema representations are reported as UNKNOWN/unsupported rather than inferred. ctx contracts and ctx lineage must not be read as confirmed DB lineage unless the output includes concrete DB evidence.
AI Editor Integration (Universal MCP Server)
To give your AI coding tools (Cursor, Claude Code, Antigravity, VS Code) instant access to Cortex, add this single global entry to your editor's MCP config file (e.g. ~/.cursor/mcp.json or claude_desktop_config.json):
{
"mcpServers": {
"cortex": {
"command": "ctx",
"args": [
"serve"
]
}
}
}
Native MCP Tools (13 Built-in Tools)
Cortex provides 13 native MCP tools running over stdio for AI coding agents:
| MCP Tool | Description | Inputs / Options |
|---|---|---|
ctx_project_summary |
Returns high-level architecture, language breakdown, modules, stats, and conventions across workspace repositories | none |
ctx_feature |
Resolves feature context: services, controllers, models, components, hooks, routes, files, and tests | name (required) |
ctx_symbol |
Inspects symbol AST definition, file location, signature, and usages | name (or symbol/target/file), scope (local/global), global (bool), lean (bool) |
ctx_impact |
Computes blast radius for a symbol, file, or whole working tree diff | target (or symbol/file), scope, global, diff (bool), ref (string), lean (bool), summary (bool), path_scope (string) |
ctx_plan |
Returns a compact deterministic evidence packet for MCP-host task planning | task (required), max_files (int, default 8) |
ctx_search |
Searches indexed symbols, files, routes, and source snippets across local workspace or all repos | query (required), scope (local/global), global (bool), exclude_current (bool) |
ctx_schema_drift |
Detects column drift, dropped column queries, and phantom columns against database migrations | lean (bool) |
ctx_sql_drift |
Alias for ctx_schema_drift; audits SQL query/schema drift against migrations |
lean (bool) |
ctx_doctor |
Returns runtime health status and diagnostic checks | none |
ctx_check_routes |
Validates route parameter contracts and catches hardcoded duplicate route strings | none |
ctx_audit_target |
Flags platform scope leaks (window, document, process.env) in shared packages |
none |
ctx_suggest |
Returns architectural refactoring recommendations (file length, route conflicts, scope leaks) | none |
ctx_feat_extract |
Slices feature AST symbols, file dependencies, and line snippets into a workspace Markdown reference | project_ref (string), feature (required), output_path, no_migrations, no_tests, max_files |
CLI and MCP Parity
Deterministic CLI commands and their MCP equivalents are semantically aligned for the same repository state. For example:
ctx impact AuthMiddleware --lean
produces the exact same token-lean blast radius string as calling the MCP tool:
{
"name": "ctx_impact",
"arguments": {
"target": "AuthMiddleware",
"lean": true
}
}
Use MCP when your coding agent can consume structured tool results directly. Use CLI when working manually in the terminal, scripting, or running CI checks.
How It Works (Under the Hood)
- AST & Route Scanner: Reads source files and extracts symbols (functions, classes, interfaces, React components, API routes, route handlers) with exact line numbers.
- Directed Import Graph (DAG): Connects relative and aliased imports (
./auth,@/components) into a directional node graph with 2-hop dependency resolution. - SQLite FTS5 Search Engine: Stores symbols, file entries, and routes in a local SQLite database (
~/.cortex/repos/<project>/context.db) with an inverted search index for sub-5ms lookups. - Kernel Event Watcher & Verifier: Listens for OS
fsnotifyfile saves and computes incremental AST diffs to update modified files, route tables, and search indexes in under 200ms.
Read the Cortex Launch Article:
Why I Built Cortex: A 100% Offline, Sub-15ms Repository Intelligence Engine for AI Coding Agents
Documentation & Releases:
Released under the MIT License. Copyright (c) 2026 Fazalur-Rahman.
Cortex MCP questions
What tools does Cortex MCP provide?
It exposes 13 tools, including ctx_project_summary, ctx_feature, ctx_symbol, ctx_impact, ctx_plan.