# Codex Context Engine

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
[![MCP Server](https://img.shields.io/badge/MCP-Protocol-orange.svg)](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.