ContextCortex (v2.12.0)

A high-performance, multi-repo Model Context Protocol (MCP) server providing syntax-aware Code RAG, Hybrid Retrieval (Dense + BM25), Tree-sitter AST chunking, Pluggable Dual-Engine Architecture (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 (ContextCortex) and real-time Diagnostic Observability.

🌟 Key Features

• Pluggable Dual-Engine Architecture:

  • PostgreSQL 16 + pgvector Profile: Containerized production deployment with native vector(384) HNSW cosine distance indexing (vector_cosine_ops), JSONB metadata payload queries, and robust connection pooling (psycopg3).

  • SQLite Profile: Zero-configuration, zero-dependency embedded disk mode with automatic WAL journaling, 5000ms busy timeout, and resilient relational caching.

• SQLAlchemy 2.0 Core Unified Schema: Single source of truth relational schema (metadata) shared seamlessly between SQLite and PostgreSQL, with startup connection retry loops (wait_for_db) and automatic metadata seeding.

• MCP 2026-07-28 OAuth 2.1 & RBAC Security Engine:

  • RFC 9728 Protected Resource Metadata: Standard discovery endpoint at /.well-known/oauth-protected-resource exposing resource indicators, authorization server issuers, and MCP scopes.

  • JWT & OIDC Discovery: Validates RS256/ES256 signed bearer tokens with automatic JWKS key discovery and cached key rotation.

  • Database-Backed API Keys: Cryptographically secure cc_... API keys with SHA-256 hash verification, expiration timestamps, and one-click revocation.

  • 3-Tier RBAC Hierarchy: admin (Level 30 / mcp:admin), editor (Level 20 / mcp:editor), and viewer (Level 10 / mcp:viewer).

  • Zero-Friction Local Dev Bypass: Runs in unrestricted admin mode when AUTH_ENABLED=false for local developer velocity.

• FastMCP 2.0 Native Architecture: Built on the official Model Context Protocol Python SDK 2.0.0+ (FastMCP), supporting modern decorator patterns, typed schemas, dynamic catalog resources, and custom agent prompts.

• Dual MCP Transports:

  • Server-Sent Events (SSE): Full streaming events at /sse with POST message routing at /messages/.

  • Streamable HTTP: Bidirectional JSON-RPC transport endpoint at /mcp.

• Multi-Vector Database Backends:

  • pgvector: PostgreSQL 16 vector extension with HNSW cosine search.

  • Qdrant: High-scale vector engine supporting dense + sparse BM25 multi-vectors with Reciprocal Rank Fusion (RRF) in both embedded disk and remote server modes.

  • ChromaDB: Lightweight, zero-dependency embedded disk or remote vector store with automatic fallback.

  • Dynamic Backend Switching: Test and switch vector backends live from the Settings UI or REST API without server restarts.

• Universal Git Provider Support:

  • Ingest repositories from any source where Git lives: GitHub, GitLab (Cloud, Enterprise & Self-Hosted), Gitea & Forgejo, Bitbucket (Cloud & Server), and Generic Git HTTP/HTTPS.

  • Provider-Aware Permalinks: Automatically generates exact deep-links for code results (/blob/, /-/blob/, /src/branch/, /src/commit/, /src/#lines-).

  • Custom Git Host Credential Vault: Register per-host tokens and authentication types for private internal domains (e.g. gitlab.company.internal or http://git.lan:3000).

• AST-Aware Code Chunking (Tree-sitter): Understands syntax structures across Python, TypeScript/JavaScript, Go, Rust, C#, C++, Java, Ruby, PHP, and more. Chunks along class, method, and function boundaries with exact line numbers and symbol names.

• Ephemeral Repository Ingestion: Authenticated shallow clones (--depth 1) extract AST symbols and hybrid vectors and immediately remove the cloned repository from disk to conserve storage.

• Multi-Tier Git Authentication Hierarchy:

  1. Per-repository override token & optional username.

  2. Domain-level Custom Git Host Vault (git_host_credentials).

  3. Global provider tokens (GITHUB_TOKEN, GITLAB_TOKEN, GITEA_TOKEN in DB or Settings UI).

  4. Environment variable fallback.

• Managed Local Storage Option & Real-Time Incremental Indexing:

  • Direct file upload, replace, read, and delete operations within a managed directory (LOCAL_STORAGE_PATH / /app/data/storage).

  • Real-time incremental AST extraction, semantic chunking, embedding generation, and vector store upserts with zero delay.

  • Strict path sanitization preventing directory traversal attacks (.., leading slashes, null bytes).

  • Immediate vector point and relational metadata purging upon file deletion.

• Unified Ingestion Catalog (what_is_ingested):

  • Comprehensive inspection of all ingested Git repositories, monitored local directory vaults, and uploaded local storage files.

  • Granular multi-dimensional filtering by source_type (all, git, monitored_path, local_storage), repo_name, path_prefix, and file_extension.

  • Flexible granularity (summary for totals and status; detailed for hierarchical file trees).

• Fast Deterministic Symbol Lookup: Built-in symbol table (ast_symbols) powers instantaneous symbol searches (find_symbol) and file outlines (get_file_outline) without token bloat.

• High-Performance 3-Pane Codebase Navigator:

  • Pane 1 (Files & Modules): Virtualized folder & file tree hierarchy with symbol/route counts, instant filtering, and one-click expand/collapse.

  • Pane 2 (Symbols & Routes): Language-aware AST symbol declarations with category chip filtering (All, Functions, Classes, Routes), signature previews, and search.

  • Pane 3 (Code Intelligence & Impact): Deep architectural intelligence displaying incoming callers, outgoing callees, imported modules, REST API route mappings (POST, GET, etc.), signature code blocks, docstrings, and one-click caller navigation jump.

  • Customizable Layout Density: Persisted Compact (IDE density), Balanced (default), and Spacious (cards) modes with zero horizontal overflow across devices.

• Diagnostic Logging & Observability: In-memory ring buffer (500 events) capturing server warnings, errors, indexing lifecycle events, and expandable stack traces with a REST API (/admin/api/logs).

• Multi-Theme Engine & Modern Tabbed Web Dashboard (/admin/):

  • Appearance & Theme Settings: Instant zero-latency switching between 4 distinct dark and light themes (Deep Ocean, Midnight Blue, Lavender Haze, and Amber Warmth) with live palette swatches and browser persistence.

  • Overview: Real-time stats, vector counts, AST symbols, model specs, topic tag cloud, and manual full reindexing trigger.

  • Codebase Navigator: High-performance 3-pane architectural file tree, AST symbol outline, and code impact/route inspector.

  • Git Repositories: Register repos across GitHub, GitLab, Gitea, Bitbucket, or Generic Git, trigger shallow clone syncs, inspect commit SHAs, and manage sources.

  • Local Paths: Monitor local workspaces and notes vaults with recursive directory scanning and filesystem browser modal.

  • Local Storage: Managed file explorer, direct file upload modal with folder categorization, and file preview/replacement.

  • Ingestion Catalog: Unified multi-source explorer with source type filters, repository lookup, and file listings.

  • Search & Inspector: Interactive live hybrid search tester with RRF score previews, target type toggle (Code vs Docs), and syntax highlighted results.

  • Settings: Vector Database manager (pgvector, Qdrant, & ChromaDB switcher & connection tester), LiteLLM Model Discovery with dynamic categorized model dropdowns (Embeddings, Vision OCR, and Chat models), multi-provider token cards, GitHub rate limit monitor, and interactive Custom Git Host Credential Vault table/modal.

  • Diagnostics & Logs: Real-time log viewer with level filtering (ALL, INFO, WARNING, ERROR, DEBUG), keyword search, traceback modal/drawer, and buffer clearing.

🛠️ MCP Tools, Resources & Prompts

Tools & RBAC Permissions

Resources

Prompts

⚙️ Environment Variables

🚀 Running via Docker Compose (Recommended)

ContextCortex provides a production-ready multi-container configuration with PostgreSQL 16 + pgvector:

# 1. Clone the repository
git clone git@github.com:spelech/contextcortex.git
cd contextcortex

# 2. Copy and customize environment variables (optional)
cp .env.example .env

# 3. Launch PostgreSQL 16 + pgvector and ContextCortex
docker compose up -d

docker-compose.yml Architecture:

version: '3.8'

services:
  postgres:
    image: pgvector/pgvector:pg16
    container_name: contextcortex-postgres
    restart: unless-stopped
    environment:
      POSTGRES_DB: ${POSTGRES_DB:-contextcortex}
      POSTGRES_USER: ${POSTGRES_USER:-contextcortex}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:-cortexsecret}
    volumes:
      - postgres_data:/var/lib/postgresql/data
    ports:
      - "${POSTGRES_PORT:-5432}:5432"
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U $$POSTGRES_USER -d $$POSTGRES_DB"]
      interval: 5s
      timeout: 5s
      retries: 5

  contextcortex:
    build:
      context: .
      dockerfile: Dockerfile
    container_name: contextcortex-app
    restart: unless-stopped
    depends_on:
      postgres:
        condition: service_healthy
    ports:
      - "${PORT:-3000}:3000"
    environment:
      DATABASE_URL: postgresql+psycopg://${POSTGRES_USER:-contextcortex}:${POSTGRES_PASSWORD:-cortexsecret}@postgres:5432/${POSTGRES_DB:-contextcortex}
      AUTH_ENABLED: ${AUTH_ENABLED:-false}
      AUTH_OIDC_ISSUER: ${AUTH_OIDC_ISSUER:-}
      AUTH_JWKS_URI: ${AUTH_JWKS_URI:-}
      AUTH_RESOURCE_INDICATOR: ${AUTH_RESOURCE_INDICATOR:-https://contextcortex.local}
      ADMIN_INITIAL_KEY: ${ADMIN_INITIAL_KEY:-}
      LOCAL_STORAGE_PATH: ${LOCAL_STORAGE_PATH:-/app/data/storage}
    volumes:
      - repo_cache:/app/data

volumes:
  postgres_data:
  repo_cache:

💻 Running Locally (Bare-Metal)

ContextCortex can be run directly on Linux, macOS, or Windows without Docker dependencies. By default, it operates with zero external services required by leveraging embedded Qdrant/ChromaDB, local SQLite (index_cache.db), and in-process CPU embeddings via FastEmbed/ONNX.

1. Prerequisites

• Python 3.11+

• Node.js 20+ & npm

• Git (available on system PATH)

2. Automated Setup (Recommended)

Clone the repository and run the automated setup script for your platform:

Linux / macOS (Bash):

git clone git@github.com:spelech/contextcortex.git
cd contextcortex
./setup.sh

Windows (PowerShell):

git clone git@github.com:spelech/contextcortex.git
cd contextcortex
.\setup.ps1

# 1. Create and activate a Python virtual environment
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# 2. Install Python dependencies
pip install -r requirements.txt

# 3. Build the React 19 administrative dashboard frontend
cd frontend
npm install
npm run build
cd ..

3. Start the Server

# Activate virtual environment (if not already active)
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Run ContextCortex with embedded vector store and local SQLite database
python3 main.py

The server starts on port 3000:

• Web Dashboard: Access the admin interface at http://localhost:3000/admin/

• MCP SSE Transport: http://localhost:3000/sse

• MCP Streamable HTTP Transport: http://localhost:3000/mcp

• OAuth Protected Resource Metadata: http://localhost:3000/.well-known/oauth-protected-resource

• Health Check: http://localhost:3000/health

📡 Connecting MCP Clients

Connect any MCP client (VS Code, Cursor, Antigravity CLI, Claude Desktop, or Windsurf) using either Server-Sent Events (SSE) or Streamable HTTP.

Server-Sent Events (SSE) Configuration (claude_desktop_config.json / Cursor)

Unauthenticated (Local Dev Bypass):

{
  "mcpServers": {
    "contextcortex": {
      "url": "http://localhost:3000/sse"
    }
  }
}

Authenticated (API Key or Bearer Token):

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

Streamable HTTP Configuration

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

🌐 REST Administration APIs

ContextCortex provides REST endpoints under /admin/api/* protected by RBAC authentication (Role.VIEWER, Role.EDITOR, Role.ADMIN):

Codebase Navigator (/admin/api/navigator/*)

Local Storage (/admin/api/storage/*)

Ingestion Catalog (/admin/api/ingestion/*)

🔐 OAuth 2.1 & API Key Management

Protected Resource Discovery

ContextCortex implements RFC 9728 Protected Resource Metadata. Clients can discover OAuth capabilities:

curl http://localhost:3000/.well-known/oauth-protected-resource

Response:

{
  "resource": "https://contextcortex.local",
  "authorization_servers": ["https://auth.company.com/realms/master"],
  "scopes_supported": ["mcp:admin", "mcp:editor", "mcp:viewer"],
  "bearer_methods_supported": ["header"],
  "resource_documentation": "https://github.com/spelech/contextcortex"
}

Generating API Keys (Admin API)

# Create 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": "Cursor Agent Key", "role": "viewer"}'

📚 Documentation & Specifications

The documentation follows the ASD-STE100 Simplified Technical English (Issue 9) standard for maximum clarity and technical precision.

• Interactive Documentation Site (VitePress): Complete user guide with component screenshots, interactive Mermaid architecture diagrams, REST API reference, and software requirements specification.

  • Run locally: npm run docs:dev

  • Build static site: npm run docs:build

  • Preview production build: npm run docs:preview

• Software Requirements Specification (REQUIREMENTS.md): Authoritative functional and non-functional requirements with test traceability matrix and Mermaid ERD data models.

• System Architecture (ARCHITECTURE.md): FastMCP 2.0 transport topologies, component interaction diagrams, SQLAlchemy 2.0 schema ERD, and vector store data models.

• Developer Documentation (DEVELOPER_DOCS.md): Setup, configuration, development workflow, and testing guidelines.

• Test Coverage Reports (docs/TEST_COVERAGE.md): Pytest, Vitest, and Playwright verification metrics.

🧪 Testing & Verification

Run the full automated test suites across backend and frontend:

# Python Backend Tests & Code Coverage
pytest -v --cov=app

# Synchronize Requirements Catalog
python3 scripts/generate_requirements.py

# Frontend Unit & Component Tests (Vitest)
cd frontend && npm run test

# Frontend End-to-End Tests (Playwright)
cd frontend && npx playwright test