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.

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

Tool	Parameters	What it returns
index_workspace	None	Rebuilds the workspace index.
find_definitions	symbolName: string	Definition locations, line ranges, docs when available, and code snippets.
find_references	symbolName: string	Import and call-expression references found in the indexed files.
get_call_graph	functionName: string, direction?: "incoming" | "outgoing"	Best-effort caller/callee data from indexed call expressions.
semantic_query	queryText: string, limit?: number	Weighted keyword matches over symbol names, docs, and file paths.
detect_circular_dependencies	None	Cycles found in resolved internal imports.
find_unused_exports	None	Exports that are not imported elsewhere in the indexed workspace.
estimate_semver_impact	refBranch?: string	Heuristic SemVer suggestion based on Git diff against a ref.
audit_security	None	Common credential-pattern warnings, source map files, and sensitive config filenames.
get_file_outline	filePath: string	Symbols, import count, and export count for one indexed file.

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.