Context Zero Engine

A local code-intelligence engine for AI agents. ContextZero indexes a repository into a PostgreSQL-backed code graph and serves structured, token-budgeted context — symbols, dependencies, effects, contracts, similar code, and blast radius — over MCP and HTTP. Everything runs on your machine; nothing leaves it.

Built by ClassEve. Licensed under Apache-2.0.

The Problem

Coding agents and developer tools usually inspect source one file at a time. On a non-trivial codebase that means opening dozens of files, re-reading the same code across tasks, manually tracing transitive effects — and still missing contract assumptions or behaviorally similar code elsewhere in the repository.

ContextZero indexes the repository once and answers the same investigation with targeted queries: give me this symbol with its dependencies and contracts, what breaks if I change it, where else does this logic exist, which tests cover it. In recorded benchmark runs this cut the tokens an agent consumed by 63–92% depending on repository size (12.4x on VS Code, 12.9x across seven multi-language repos). See BENCHMARKS.md for full methodology, results, and honest caveats.

Related MCP server: ChunkHound

What It Computes

15 Languages

TypeScript, JavaScript, Python, C, C++, CUDA-flavored .cu/.cuh, Go, Rust, Java, C#, Ruby, Kotlin, Swift, PHP, Bash.

TypeScript and JavaScript use full AST analysis through the TypeScript Compiler API. Python uses LibCST with 60+ behavioral patterns. The remaining languages use tree-sitter with language-specific walkers.

How It Works

MCP-compatible client (Claude Desktop, Claude Code, Codex, Cursor, ...)
    |
    | MCP protocol (stdio)            HTTP clients
    |                                     |
ContextZero MCP Bridge (61 tools)    REST API (60 routes)
    |                                     |
    +------------------+------------------+
    |
    +-- Ingestor (15 languages, delta ingestion)
    +-- 13 Analysis Engines
    |     Behavioral | Contract | Deep Contract | Blast Radius
    |     Effect | Dispatch | Concept Families | Temporal
    |     Symbol Lineage | Runtime Evidence | Uncertainty
    |     Structural Graph | Capsule Compiler
    +-- Semantic Engine (TF-IDF, MinHash LSH, cosine similarity)
    +-- Homolog Engine (7-dimensional scoring)
    +-- Transactional Editor (sandboxed validation, rollback)
    +-- Service Layer (transport-agnostic services)
    +-- Database Driver (circuit breaker, batch loader, advisory locks)
    |
PostgreSQL 16 (all data local, nothing leaves your machine)

The scg_ prefix on tools and environment variables comes from the engine's internal name for its data model — the structural code graph.

Deep dives: ARCHITECTURE.md (subsystems and tool registry) and TECHNICAL_DESIGN.md (data structures, algorithms, engine internals).

Install

Prerequisites

• Node.js 20+ (22 recommended)

• PostgreSQL 14+ (16 recommended) with the pg_trgm extension

• Python 3 with libcst (optional — only for Python source analysis)

Bootstrap (recommended)

git clone https://github.com/classeve-public/context-zero-engine.git context-zero-engine
cd context-zero-engine

Windows:

powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\bootstrap.ps1 -Client claude

macOS / Linux:

scripts/bootstrap.sh --client claude

The bootstrap installs dependencies, creates .env, builds, runs database migrations, runs diagnostics (npm run doctor), and optionally writes the MCP config for your client (claude, codex, cursor, or all).

Manual install

npm install

createdb scg_v2
psql -d scg_v2 -c "CREATE EXTENSION IF NOT EXISTS pg_trgm;"

cp .env.example .env    # set DB_USER / DB_PASSWORD / SCG_ALLOWED_BASE_PATHS

npm run build
npm run db:migrate
npm run doctor          # verifies node, database, python, env

Full options, client config paths, and troubleshooting: docs/INSTALL.md and docs/OPERATIONS.md.

Quickstart

1. Wire it into an MCP client

The bundled installer writes the config (with a timestamped backup of the existing file) for Claude Desktop, Codex, or Cursor:

npm run mcp:install -- --client claude

Or generate config snippets without touching client files (npm run mcp:config), or register manually — for example with the Claude Code CLI:

claude mcp add contextzero -s user \
  -e CONTEXTZERO_ENV_FILE=/absolute/path/to/context-zero-engine/.env \
  -- node /absolute/path/to/context-zero-engine/dist/mcp-bridge/index.js

Any MCP client that speaks stdio works: the server is node dist/mcp-bridge/index.js with the DB_*/SCG_* environment (or a single CONTEXTZERO_ENV_FILE pointing at your .env).

2. Index a repository

From the MCP client, call:

scg_health_check                      → should report status: healthy
scg_register_repo / scg_ingest_repo   → index a repo under SCG_ALLOWED_BASE_PATHS

Then start asking: scg_smart_context, scg_blast_radius, scg_compile_context_capsule, scg_find_homologs, scg_semantic_search, ...

Three native tools (scg_native_codebase_overview, scg_native_symbol_search, scg_native_search_code) work immediately without a database — they analyze the filesystem directly.

3. Or run it as an HTTP server

npm run build
npm start          # HTTP server on port 3100

curl http://localhost:3100/health
curl -X POST http://localhost:3100/scg_codebase_overview \
  -H "X-API-Key: <your key>" -H "Content-Type: application/json" \
  -d '{"repo_id": "..."}'

60 routes (7 GET + 53 POST) mirror the MCP tool surface plus health, readiness, Prometheus metrics, cache, and admin endpoints. All POST routes require API-key authentication (X-API-Key or Authorization: Bearer).

Docker (self-hosted server + bundled PostgreSQL)

cp .env.docker.example .env
# Set DB_PASSWORD and SCG_API_KEYS to strong secrets.
docker compose up -d

When registering repositories from Docker, use paths under /repos — that is where SCG_REPOS_PATH is mounted inside the container.

MCP Tool Surface (61 tools)

The complete registry is in ARCHITECTURE.md.

Security

• Local by design — no telemetry, no external APIs; analysis and storage stay on your machine

• SQL injection protection — parameterized queries plus table/column allowlists for dynamic queries

• 5-layer path traversal protection — null bytes, URL encoding, backslash handling, symlink escape checks, base-path boundary enforcement

• Fail-closed authentication — timing-safe comparison, 32-character minimum keys, per-IP brute-force lockout with exponential backoff

• Sandboxed validation — resource limits, process groups, SIGKILL escalation, environment sanitization

• Hardened HTTP surface — per-route rate limits and body-size limits, input validation on every route, sanitized error responses (no stack traces, paths, or SQL)

See SECURITY.md for the deployment hardening checklist and how to report a vulnerability.

Benchmarks

Methodology, per-repo tables, reproduction scripts, and the cases where the gain is small: BENCHMARKS.md.

Testing

npm test              # full unit suite (40 suites, 1,400+ tests)
npm run test:db       # opt-in integration test against a real PostgreSQL
npm run test:ci       # with coverage
npm run typecheck     # TypeScript strict mode
npm run lint

Documentation

About

Built and maintained by ClassEve — engineering for AI agents and developer tooling. Project page: classeve.com/public/context-zero-engine.

License

Apache License 2.0 — see LICENSE. Copyright 2026 ClassEve.