ContextCortex (v2.7.0)

A high-performance, multi-repo Model Context Protocol (MCP) server providing syntax-aware Code RAG, Hybrid Retrieval (Dense + BM25), Tree-sitter AST chunking, Multi-Vector Database Backends (Qdrant & ChromaDB), and Universal Git Provider indexing with an integrated Web Admin Dashboard (ContextCortex) and real-time Diagnostic Observability.

🌟 Key Features

• 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:

  • 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: The server performs authenticated shallow clones (--depth 1), extracts AST symbols and hybrid vectors, and immediately removes 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.

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

• 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).

• Modern Tabbed Web Dashboard (/admin/) - ContextCortex Dashboard:

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

  • 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.

  • 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 (Qdrant & ChromaDB switcher & connection tester), 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.

Related MCP server: localrag

🛠️ MCP Tools, Resources & Prompts

Tools

Resources

Prompts

⚙️ Environment Variables

🚀 Running via Docker

Docker Compose

services:
  contextcortex:
    image: ghcr.io/spelech/contextcortex:latest
    container_name: contextcortex
    restart: unless-stopped
    ports:
      - "8021:3000"
    environment:
      - VECTOR_STORE_PROVIDER=qdrant
      - EMBEDDING_PROVIDER=local
      - EMBEDDING_MODEL=BAAI/bge-small-en-v1.5
      - GITHUB_TOKEN=ghp_your_optional_token
      - VAULT_PATH=/docs
    volumes:
      - /path/to/my/docs:/docs:ro
      - ./data:/app/data

📡 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)

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

Streamable HTTP Configuration

{
  "mcpServers": {
    "contextcortex-http": {
      "url": "http://localhost:3000/mcp"
    }
  }
}

📚 Documentation & Specifications

• 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, SQLite 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

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

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