Content
# codex-context-mcp
`codex-context-mcp` is a Model Context Protocol server built for Codex CLI. It reduces context waste by keeping raw repo scans, log files, XML reports, and diff text in local storage, then returning short bounded summaries plus searchable artifact handles.
This project is aimed at the main Codex CLI limitation: Codex has no hook system, so it cannot reliably force heavy analysis through a context-saving layer. Instead of wrapping generic shell commands, this MCP exposes task-shaped tools that are more useful than raw reads for large inputs.
## What it does
The server exposes five tools:
- `repo_gather`: scan a repository locally, summarize architecture and hotspots, and persist the full raw corpus.
- `file_analyze`: inspect a large file such as a log, JUnit XML report, Markdown report, patch, or generic text file.
- `result_search`: query a previously stored artifact by handle and return only relevant snippets.
- `stats`: show session-level raw bytes, returned bytes, estimated returned tokens, and estimated saved tokens.
- `reset_stats`: clear the current session stats so you can start a fresh measurement window.
All raw data is stored in a local SQLite database under `artifacts/store/`. Only the bounded summary comes back into the Codex conversation.
Session stats are kept in memory by the running MCP process, so they reset automatically when the server restarts.
## Requirements
- Node.js `22.17+`
- Codex CLI installed and working
Notes:
- This project uses Node's built-in `node:sqlite` module. On some Node releases it may still print an experimental warning even though the server works.
- The comparison script expects `codex exec` to be available on your `PATH`.
## Install
1. Clone the repository somewhere on your machine.
2. Install dependencies.
3. Register the MCP in your Codex config.
4. Restart Codex CLI.
### Clone and install
```bash
git clone https://github.com/kevinwolf85/codex-context-mcp.git
cd codex-context-mcp
npm install
```
### Register in Codex CLI
Add this MCP server to your Codex config file.
Typical config paths:
- macOS/Linux: `$HOME/.codex/config.toml`
- Windows: `%USERPROFILE%\\.codex\\config.toml`
Example entry:
```toml
[mcp_servers."codex-context-mcp"]
command = "node"
args = ["/absolute/path/to/codex-context-mcp/src/server.js"]
```
Use an absolute path that exists on your own machine. Do not copy a path from this repository or from another user.
## Recommended Codex routing
This MCP works best when you tell Codex to use it for heavy local analysis work.
Suggested `AGENTS.md` guidance:
```md
Use `codex-context-mcp` for large local analysis tasks.
- Prefer `repo_gather` for repository discovery, architecture summaries, or hotspot detection.
- Prefer `file_analyze` for large logs, XML reports, Markdown reports, and patch files.
- Prefer `result_search` for follow-up questions against a previously returned `artifact_id`.
- Use `stats` when you want a quick session report on estimated bytes and tokens saved.
- Use `reset_stats` before a benchmark run or before starting a new measurement window.
- Keep normal file reads for files you are about to edit.
- Keep direct shell usage for short-output commands.
```
## Local development
Install dependencies:
```bash
npm install
```
Run the tests:
```bash
npm test
```
Run synthetic benchmarks:
```bash
npm run bench
```
Run the non-interactive Codex comparison harness:
```bash
npm run compare
```
To include `context-mode` in the same comparison, enable it explicitly:
```bash
CODEX_CONTEXT_INCLUDE_CONTEXT_MODE=1 npm run compare
```
On PowerShell:
```powershell
$env:CODEX_CONTEXT_INCLUDE_CONTEXT_MODE="1"
npm run compare
```
Artifacts are written to:
- `artifacts/benchmarks/`
- `artifacts/comparison/`
These folders are ignored by git.
## Tool behavior
### `repo_gather`
Inputs:
- `rootPath`
- `questions` optional
Output includes:
- short summary
- `artifact_id`
- raw/returned byte counts
- estimated returned token count
- compression gain
### `file_analyze`
Inputs:
- `filePath`
- `intent` optional
Current analyzers handle:
- `.log`
- `.xml`
- `.md`
- `.diff`
- `.patch`
- generic text files
### `result_search`
Inputs:
- `artifactId`
- `query`
- `limit` optional
Use this after a prior `repo_gather` or `file_analyze` call when you want a narrower follow-up answer without re-ingesting the raw file.
### `stats`
Inputs:
- none
Output includes:
- session tool call count
- total raw bytes processed
- total bytes returned to Codex
- estimated returned tokens
- estimated saved tokens
- per-tool breakdown
This is an estimate based on byte counts, not a billing-grade token counter from the model provider.
### `reset_stats`
Inputs:
- none
Use this to clear the current in-memory session stats before running a new benchmark or comparison pass.
## Benchmark intent
The included benchmark and comparison scripts are designed to answer two separate questions:
- `npm run bench`: how much text each tool keeps out of the response relative to the raw source data
- `npm run compare`: how Codex performs end-to-end with plain Codex and the local `codex-context-mcp` server
If `CODEX_CONTEXT_INCLUDE_CONTEXT_MODE=1` is set and `context-mode` is already installed in your Codex environment, the comparison also includes `context-mode`.
Those are different measurements. A tool can have strong per-call compression and still lose in an end-to-end Codex run if it takes more turns or produces more final output.
## Current limitations
- Codex CLI cannot be forced to choose these tools. Good routing instructions still matter.
- Repository and diff summarization are useful, but log and structured-file analysis are currently the strongest cases.
- The comparison harness assumes a working Codex CLI environment and is meant for local validation, not CI by default.
## License
MIT
