PanchiCodex

# Codex Context Engine [](https://opensource.org/licenses/MIT) [](https://modelcontextprotocol.io/) 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 ```mermaid 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. ```bash npm install ``` ## Running Locally ```bash 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: ```toml [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: ```json { "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 ```bash 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.