ContextCortex (v2.25.0)

ContextCortex is a multi-repository Model Context Protocol (MCP) server providing syntax-aware Code RAG, Hybrid Retrieval (Dense + BM25), Tree-sitter AST chunking, Pluggable Dual-Engine Storage (PostgreSQL 16 + pgvector & SQLite), MCP 2026-07-28 OAuth 2.1 + 3-Tier RBAC, and Universal Git Provider indexing with an integrated Web Admin Dashboard.

🖼️ View Dashboard Components

Overview	Git Repositories
Codebase Navigator	Search & Inspector
Files & Storage	Settings
Diagnostics & Logs	Add Repository Modal

🎨 Multi-Theme Appearance (4 Palettes)

Deep Ocean (Dark Default)	Midnight Blue (Dark Space)
Petrol spruce #07181b with cyan #0891b2 & mint	Obsidian navy #0a0f1d with royal blue #3b82f6 & teal
Lavender Haze (Light Purple)	Amber Warmth (Light Sandstone)
:---:	:---:
Lilac canvas #f5f3ff with purple #7c3aed & fuchsia	Sandstone #fdf8f4 with terracotta #ea580c & amber

---

🌟 Key Features

• Pluggable Dual-Engine Storage:
  • PostgreSQL 16 + pgvector: Production profile with vector(384) HNSW cosine indexing, tsvector GIN full-text search, and psycopg3 pooling.
  • SQLite + Qdrant: Zero-configuration embedded profile with WAL journaling (15000ms busy timeout) and embedded or remote Qdrant RRF fusion.
  • Live Vector Backend Switching: Test and switch vector backends (pgvector <-> Qdrant) from the Settings UI or REST API without restarts.
• MCP 2026-07-28 OAuth 2.1 & 3-Tier RBAC:
  • RFC 9728 Discovery: Exposes /.well-known/oauth-protected-resource for OAuth resource indicators and scopes.
  • JWT/OIDC & API Keys: Validates RS256/ES256 bearer tokens via JWKS and SHA-256 hashed cc_... API keys across admin, editor, and viewer roles (AUTH_ENABLED=false enables local dev bypass).
• FastMCP 2.0 Dual Transports: Exposes SSE (/sse + /messages/) and Streamable HTTP (/mcp) with bounded JSON pagination across all tools and resources.
• Universal Git Provider Indexing:
  • Supports GitHub, GitLab, Gitea/Forgejo, Bitbucket, Generic HTTP/HTTPS, and SSH (git@... / ssh://...) with a 4-tier credential hierarchy.
  • Shallow Clone & Commit Retention: Configure persistent --depth 1 clones (keep_shallow) for instant source navigation and retain 0..50 recent commits (retain_commits_count) for the Web UI and /admin/api/repos/{name}/commits endpoint.
• Multi-Language AST & Forensic Intelligence:
  • Extracts AST symbols, call graphs, and HTTP routes across Python, TypeScript/JS/TSX, C#, COBOL, Go, Rust, Java, and C/C++.
  • Provides multi-repo regex/literal grep_code, stack-trace diagnose_issue triage, cross-repo HTTP trace_path, and vector-chunk read_file reconstruction.
• Managed Local Storage & Enterprise Private-CA Support:
  • Upload, replace, preview, read, and delete files in LOCAL_STORAGE_PATH with immediate incremental indexing and path-traversal protection.
  • Bootstraps private CA certificates (certs/*.crt), custom OpenAI-compatible gateways (OPENAI_API_URL, LLM_EXTRA_HEADERS), and restricted-network mirror builds (docker-compose.enterprise.yml).

---

🛠️ MCP Tools, Resources & Prompts

See the full MCP Tools, Resources, and Pagination Reference for complete schemas, pagination conventions, tool parameter bounds, resource templates, and workflow prompts.

Tools & RBAC Permissions (10 Default Tools + Optional manage)

By default, ContextCortex registers 10 read/search/code-mode tools (including execute_script) so the entire tool surface fits on Page 1 in MCP clients. Set MCP_ENABLE_WRITE_TOOLS=true to also expose the gated manage admin/write tool (11 tools total).

Tool	Role	Key Parameters & Bounds	Description
search	viewer	query, scope (code|docs|all), repo, language, category, tag, mode, dense_weight, limit (1..25), offset, max_snippet_chars (200..6000)	Hybrid semantic + BM25 search across AST code chunks and docs/runbooks/ADRs/PDFs.
grep_code	viewer	pattern, repo, path_glob, is_regex, case_sensitive, context_lines (0..10), limit (1..100), offset	Literal/regex search with AST attribution; truncates lines > 400 chars cleanly.
diagnose_issue	viewer	issue_text, repo, context_lines (1..15), limit (1..20)	Forensic triage resolving stack traces, error literals, routes, and semantic candidates.
find_symbol	viewer	name, repo, exact (True), limit (1..100, default 30), offset	Deterministic exact or substring AST symbol lookup without broad token scans.
read_file	viewer	path, repo, start_line, end_line, outline_only (False), limit (1..500, default 150), offset	Reads bounded 1-based line slices (next_start_line) or inspects AST outlines (outline_only=True).
trace_path	viewer	symbol, repo, direction, depth (1..5), limit (1..200, default 50), offset, include_permalinks (False)	Traverses AST callers/callees and cross-repo HTTP route/client boundaries via BFS.
find_routes	viewer	query, kind (handlers|callers|both), method, repo, limit (1..200, default 50), offset	Discovers HTTP route handlers (kind='handlers'), client callers (kind='callers'), or both.
get_architecture	viewer	repo (opt)	Synthesizes language distribution, manifests, entry points, modules, hub symbols, and ADRs.
list_repositories	viewer	repo, source_type (all|git|monitored_path|local_storage), path_prefix, file_extension, include_files, include_status, limit (1..500), offset	Lists Git repos, local paths, and storage inventory, with optional paginated files or index health status.
execute_script	viewer (each tool call keeps its own role check)	script/code, arguments/args	Code Mode: one sandboxed JavaScript script chains several tool calls and returns only the final result (limits: 30 s, 50 tool calls, 64 MB).
manage (gated)	editor/viewer	action (sync_repo|upload|replace|delete|read|preview), repo, file_path, content, category	Exposed only when MCP_ENABLE_WRITE_TOOLS=true. Triggers repo syncs or manages local storage files with immediate indexing.

Resources & Paginated Resource Templates

Resource URI / Template	MIME Type	Pagination / Scope	Description
knowledge://catalog/summary	application/json	Compact (<= 40 sample files)	Global catalog summary plus resource_templates discovery metadata.
contextcortex://code-mode/sdk.d.ts	text/plain	Single	TypeScript declarations of every tool that an execute_script script can call.
knowledge://repo/{repo}/summary	application/json	Per-repo	Status, commit SHA, language breakdown, symbol/route/ADR counts, and sub-resource URIs.
knowledge://repo/{repo}/architecture	application/json	Per-repo	Synthesized architecture overview (manifests, entry points, modules, hub symbols).
knowledge://repo/{repo}/files/{page}	application/json	100 files / page	1-indexed paginated file inventory (total_files, total_pages, has_more, next_uri).
knowledge://repo/{repo}/routes/{page}	application/json	50 routes / page	1-indexed paginated API routes (total_routes, total_pages, has_more, next_uri).
knowledge://repo/{repo}/adrs	application/json	Per-repo	Architecture Decision Records registered for {repo}.

Workflow Prompts (5 Prompts)

Prompt Name	Arguments	Description
search_infrastructure_docs	topic	Guided workflow across search(scope='docs'), knowledge://repo/{repo}/adrs, and read_file.
find_implementation_symbol	symbol, repo (opt)	Locates symbol definitions, AST outlines (read_file(..., outline_only=True)), line slices, and call paths.
onboard_repository	repo	Maps architecture, HTTP routes (find_routes(kind='handlers')), and file outlines (read_file(..., outline_only=True)) for {repo}.
triage_error	issue_text, repo (opt)	Diagnoses stack traces or failing routes down to root-cause lines.
investigate_change_impact	symbol, repo (opt)	Evaluates blast radius across internal callers, cross-repo API clients (find_routes(kind='callers')), and tests.

---

⚙️ Environment Variables

Variable	Description	Default
DATABASE_URL	SQLAlchemy URL (postgresql+psycopg://... or sqlite:////app/data/index_cache.db)	sqlite:////app/data/index_cache.db
POSTGRES_DB / POSTGRES_USER / POSTGRES_PASSWORD	PostgreSQL container credentials (POSTGRES_PORT default 5432)	contextcortex / cortexsecret
LOCAL_STORAGE_PATH	Managed local storage root for direct uploads and incremental indexing	/app/data/storage
AUTH_ENABLED	Enable MCP 2026-07-28 OAuth 2.1 and API Key RBAC	false
AUTH_OIDC_ISSUER / AUTH_JWKS_URI	OIDC Issuer URL and optional custom JWKS URI override	None
AUTH_RESOURCE_INDICATOR	RFC 8707 / RFC 9728 OAuth Resource Indicator	https://contextcortex.local
ADMIN_INITIAL_KEY	Bootstrap admin API key on container startup	None
MCP_ENABLE_WRITE_TOOLS	Expose the manage admin/write MCP tool (sync_repo, local storage CRUD)	false
VECTOR_STORE_PROVIDER	Vector backend (pgvector or qdrant)	pgvector (PG) / qdrant (SQLite)
VECTOR_STORE_MODE	Vector mode (embedded or remote)	embedded (Qdrant) / remote (PG)
COLLECTION_NAME	Active vector collection name	knowledge_rag_v1
QDRANT_URL / QDRANT_STORAGE_PATH	Remote Qdrant URL or embedded storage path	http://localhost:6333 / /app/data/qdrant_storage
OPENAI_API_URL / OPENAI_API_KEY	OpenAI-compatible gateway base URL and Bearer key	http://litellm:4000/v1 / dummy
LLM_EXTRA_HEADERS	JSON object of custom HTTP headers sent to the AI gateway	None
EXTRA_CA_CERTS_DIR	Directory of private *.crt CA certificates trusted at startup (certs/README.md)	/certs
GITHUB_TOKEN / GITLAB_TOKEN	Optional global Personal Access Tokens for private Git hosts	None
CACHE_DB_PATH	Persistent SQLite database path when DATABASE_URL is unset	/app/data/index_cache.db
CHUNK_SIZE / CODE_CHUNK_SIZE / CHUNK_OVERLAP	Markdown chunk limit, AST code function/symbol chunk limit, and overlap window	1500 / 4000 / 200

---

🚀 Three Ways to Deploy ContextCortex

Deployment Mode	Relational Metadata DB	Vector Store	Best For
1. Docker Compose (Recommended)	PostgreSQL 16 (or SQLite)	pgvector or Qdrant	Production, homelab, and enterprise containers (docker-compose.yml)
2. Windows Portable Bundle	Embedded PostgreSQL 16	Embedded pgvector or Qdrant	Zero-admin Windows workstations (scripts/build_portable_windows.ps1)
3. Local Python (venv)	SQLite (or external Postgres)	Embedded Qdrant	Local development and lightweight CLI/MCP workflows

Mode 1: Docker Compose (Recommended)

git clone git@github.com:spelech/contextcortex.git
cd contextcortex
cp .env.example .env
docker compose up -d

Sub-Configuration	Relational DB (DATABASE_URL)	Vector Store	Configuration
1A. PostgreSQL 16 + pgvector (Default)	postgresql+psycopg://...@postgres:5432/contextcortex	pgvector (remote)	Default in docker-compose.yml.
1B. PostgreSQL + Remote Qdrant	postgresql+psycopg://...	qdrant (remote)	Set VECTOR_STORE_PROVIDER=qdrant, QDRANT_URL=http://qdrant:6333.
1C. PostgreSQL + Embedded Qdrant	postgresql+psycopg://...	qdrant (embedded)	Stores vectors on /app/data/vector_storage.
1D. Single-Container SQLite + Qdrant	sqlite:////app/data/index_cache.db	qdrant (embedded)	Use docker-compose.enterprise.yml overrides without Postgres.

Open http://localhost:3000/admin/ -> Settings -> AI & Model Gateway to test OPENAI_API_URL and select your Embedding, Chat, and Vision OCR models. For corporate TLS proxies, private CAs (certs/*.crt), and internal package mirrors, see Restricted-Network Builds & Enterprise Deployment:

docker compose -f docker-compose.yml -f docker-compose.enterprise.yml up -d --build

Mode 2: Windows Standalone Portable Deployment

Packages a frozen contextcortex.exe, user-space PostgreSQL 16, pre-compiled pgvector, private CA loader, and React Dashboard into dist\contextcortex-windows-x64:

.\scripts\build_portable_windows.ps1
.\dist\contextcortex-windows-x64\start-contextcortex.bat

Set PORTABLE_POSTGRES_ENABLED=true (default 127.0.0.1:54329 + pgvector) or PORTABLE_POSTGRES_ENABLED=false with VECTOR_STORE_PROVIDER=qdrant in dist\contextcortex-windows-x64\.env.

Mode 3: Local Python (venv)

Requires Python 3.11+, Node.js 20+, and Git:

git clone git@github.com:spelech/contextcortex.git
cd contextcortex
./setup.sh            # Windows PowerShell: .\setup.ps1
source venv/bin/activate
python3 main.py

Default endpoints on port 3000:

• Web Dashboard: http://localhost:3000/admin/
• MCP Streamable HTTP / SSE: http://localhost:3000/mcp and http://localhost:3000/sse
• OAuth Metadata & Health: http://localhost:3000/.well-known/oauth-protected-resource, /health, /ready

---

📡 Connecting MCP Clients

Configure Cursor, VS Code, Antigravity CLI, Claude Desktop, or Windsurf via Streamable HTTP (/mcp) or SSE (/sse):

{
  "mcpServers": {
    "contextcortex": {
      "url": "http://localhost:3000/mcp",
      "headers": {
        "Authorization": "Bearer cc_live_your_api_key_here"
      }
    }
  }
}

(Omit headers when running locally with AUTH_ENABLED=false.)

---

🌐 REST Administration APIs & OAuth 2.1

All /admin/api/* routes enforce RBAC (viewer, editor, admin):

Endpoint Group	Routes	Role	Purpose
Navigator	GET /admin/api/navigator/{tree,file-outline,symbol-impact}	viewer	File hierarchy, AST outlines, and caller/callee impact graphs.
Local Storage	POST /upload, PUT|DELETE|GET /file, GET /tree under /admin/api/storage	editor / viewer	Upload, replace, delete, read, and browse managed storage files.
Ingestion Catalog	GET /admin/api/ingestion/catalog	viewer	Multi-source inventory across Git repos, watched paths, and storage.
API Keys	POST /admin/api/auth/keys	admin	Issue scoped cc_... keys (viewer, editor, admin).

# Discover RFC 9728 OAuth metadata
curl http://localhost:3000/.well-known/oauth-protected-resource

# Issue a Viewer API key
curl -X POST http://localhost:3000/admin/api/auth/keys \
  -H "Authorization: Bearer cc_admin_key" -H "Content-Type: application/json" \
  -d '{"name": "Agent Viewer Key", "role": "viewer"}'

---

📚 Documentation & Verification

• Interactive Documentation Site (VitePress) (npm run docs:dev / npm run docs:build)
• MCP Tools, Resources, and Pagination Reference (docs/mcp-tools-and-resources.md)
• Benchmarks & Performance Baselines (docs/reference/benchmarks.md) (benchmarks/README.md)
• Restricted-Network & Enterprise Builds (docs/guide/enterprise-build.md)
• Software Requirements (REQUIREMENTS.md) | Architecture (ARCHITECTURE.md) | Developer Docs (DEVELOPER_DOCS.md) | Test Coverage (docs/TEST_COVERAGE.md)

# Backend Pytest Suite
pytest -v --cov=app

# Frontend Unit (Vitest) & E2E (Playwright) Suites
cd frontend && npm run test && npx playwright test

# Isolated MCP Schema, Latency & OpenCode A/B Benchmarks (uses :18021)
./benchmarks/setup_and_run_server.sh start
python3 benchmarks/measure_tool_schemas.py
python3 benchmarks/run_micro_bench.py --runs 3
python3 -u benchmarks/run_benchmark.py --tasks-file benchmarks/examples/custom_tasks.example.json
./benchmarks/setup_and_run_server.sh stop