Skip to main content
Glama
Codex Context Engine

Codex Context Engine

by Elioz404

Codex Context Engine

License: MIT MCP Server

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

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.

Available Tools

10 tools
audit_securityA

Scans the workspace to identify sensitive credentials (API keys, private keys, database connection strings) and build source map files (.map) that might leak source structure.

Inputs: no named parameters.

detect_circular_dependenciesA

Analyzes module imports to locate dependency cycles (e.g. A imports B, B imports A) which lead to runtime errors.

Inputs: no named parameters.

estimate_semver_impactB

Estimates the semantic versioning impact (Major/Minor/Patch) of current changes by comparing code signatures with a reference commit or branch.

Inputs: refBranch.

find_definitionsA

Returns definition details, lines, and exact code snippet for a given function, class, or method name.

Inputs: symbolName (required).

find_referencesA

Searches the workspace for references to a given symbol name. Returns file paths, line numbers, caller names, and matching code snippets.

Inputs: symbolName (required).

find_unused_exportsA

Scans the project to identify exported classes, functions, or variables that are never imported anywhere in the codebase.

Inputs: no named parameters.

get_call_graphA

Generates caller-callee trees to trace program execution pathways for a given function or method.

Inputs: functionName (required), direction.

get_file_outlineB

Returns a structured outline of all symbols (classes, functions, methods, variables) declared inside a specific file from the index.

Inputs: filePath (required).

index_workspaceA

Triggers a re-scan of the workspace, parsing all JavaScript/TypeScript files to rebuild the symbol and call graph index.

Inputs: no named parameters.

semantic_queryA

Performs a weighted search over symbols and comments using query keywords to locate code by intent (e.g., "jwt parsing").

Inputs: queryText (required), limit.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.9/5.0

    Scored across 10 tools

    Disambiguation5/5

    Each tool has a clear and distinct purpose: security auditing, circular dependency detection, semver estimation, symbol definition/reference lookup, unused export detection, call graph generation, file outlining, workspace indexing, and semantic querying. No overlap is apparent.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern in snake_case (e.g., audit_security, find_definitions, get_file_outline), making them predictable and easy to distinguish.

    Tool Count5/5

    With 10 tools, the server covers a comprehensive range of code analysis tasks without being overwhelming. Each tool serves a distinct analytical purpose, justifying its inclusion.

    Completeness4/5

    The tool set covers essential code analysis operations like indexing, symbol lookup, call graph, security scan, etc. Minor gaps exist (e.g., no tool for refactoring or package-level dependency listing), but the surface is largely complete for a context engine.

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      A local server that provides powerful code analysis and search capabilities for software projects, helping AI assistants and development tools understand codebases for tasks like code generation and refactoring.
      4
      -
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables semantic code search across multiple repositories using natural language queries. Provides intelligent code discovery, symbol lookups, and cross-repo dependency analysis for AI coding agents.
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Provides AI coding agents with structured access to indexed codebases via semantic search, symbol analysis, and file reading tools.
      13
      Server Side Public , v 1
    • A
      license
      Not graded
      quality
      D
      maintenance
      Provides IDE-like code navigation and search for local repositories, enabling AI assistants to perform symbol search, trigram indexing, and semantic navigation.
      AGPL 3.0