Codex Context Engine

Codex Context Engine is a local MCP server that indexes a workspace and exposes code-navigation tools to Codex.

It parses JavaScript and TypeScript files with Babel, uses simple regex-based indexing for Python, Go, and Rust, writes an index to .codex-context.json, and generates a CODEBASE_MAP.md report.

The project is useful for quick local navigation, reference lookup, dependency checks, and lightweight audits. It is not a replacement for a compiler, language server, type checker, or dedicated security scanner.

What It Does

• Indexes source files with these extensions: .js, .jsx, .ts, .tsx, .mjs, .cjs, .py, .go, .rs.

• Ignores common generated or heavy paths such as node_modules, .git, dist, build, package lockfiles, and its own index file.

• Extracts symbols, imports, exports, and call expressions into a JSON index.

• Watches the workspace for changes and updates indexed files incrementally. If recursive fs.watch is not available, it falls back to polling.

• Provides MCP tools over stdio for local Codex integrations.

• Runs locally and does not call external APIs during indexing.

Related MCP server: MCP Indexer

Current Limits

• JavaScript and TypeScript support is AST-based, but it is still a static heuristic indexer. It does not type-check code or resolve every dynamic pattern.

• Python, Go, and Rust support is regex-based and intentionally shallow.

• Reference and call-graph results are best-effort. Dynamic dispatch, aliasing, reflection, generated code, and complex module resolution may be missed.

• semantic_query is keyword scoring over names, paths, and comments. It is not embeddings or AI semantic search.

• audit_security detects common secret patterns and source map files. It can miss secrets and can produce false positives.

• estimate_semver_impact requires a Git repository and compares exported JavaScript/TypeScript signatures heuristically.

Architecture

graph TD
    A[Codex Agent] <-->|JSON-RPC over stdio| B[MCP Server]
    B <--> C[Query Engine]
    B <--> D[Codebase Indexer]
    D -->|JS/TS AST parsing| E[Babel Parser]
    D -->|Python/Go/Rust regex parsing| H[Regex Fallbacks]
    D -->|Watches files| F[fs.watch or polling]
    D -->|Writes JSON| G[.codex-context.json]
    D -->|Generates report| I[CODEBASE_MAP.md]

MCP Tools

Installation

Requires Node.js 18 or newer.

npm install

Running Locally

npm start

The server communicates over stdio, so normal diagnostic output is written to stderr to avoid corrupting MCP JSON-RPC messages on stdout.

Codex MCP Configuration

Project-scoped example:

[mcpServers.codex-context-engine]
command = "node"
args = ["/absolute/path/to/codex-context-engine/src/server.js"]

Global config locations commonly used by Codex:

• Windows: %USERPROFILE%\.codex\config.toml

• macOS/Linux: ~/.codex/config.toml

This repository also includes .mcp.json for plugin-style configuration:

{
  "mcpServers": {
    "codex-context-engine": {
      "command": "node",
      "args": ["./src/server.js"]
    }
  }
}

Generated Files

• .codex-context.json: local index cache. It is ignored by Git.

• CODEBASE_MAP.md: generated workspace report. This repository currently tracks it as a sample/report artifact.

Testing

npm test

The test suite covers:

• JS/TS symbol indexing and doc extraction.

• CommonJS imports and exports.

• Destructured bindings.

• Basic Python, Go, and Rust regex indexing.

• Circular dependency and unused export detection.

• Git-based SemVer impact estimation.

• Security-audit masking for common patterns.

• Polling watcher fallback.

• MCP stdio safety for indexer diagnostics.