codex-context-mcp

Read-only, local stdio MCP tools that give Codex bounded source evidence instead of automatically sending whole files. Codex does the reasoning. No additional LLM, embeddings, API key, network service, or UI. Initial implementation; not yet a published npm release.

Install from source

Requires Node.js 22 or 24 and npm. Clone the repository first, then run in this checkout:

git clone https://github.com/RunIron/codex-context-mcp.git
cd codex-context-mcp
npm ci
npm test
npm run benchmark
npm run smoke

npm test builds first. Register the built server using absolute paths (replace both paths):

codex mcp add bounded-context -- node /absolute/path/codex-context-mcp/dist/cli.js --root /absolute/path/your-repository

On Windows, use C:/... paths and quote paths containing spaces; an absolute node.exe path avoids PATH wrappers. Registration changes your Codex configuration; the test suite does not register anything. codex mcp add --help documents the command. No npm registry installation is promised before publication.

Related MCP server: mcp-developer-server

Workflow and tools

1. Ask Codex to choose concrete identifiers/literal fragments from your task.

2. Call context_search with {"terms":["RETRY_LIMIT","retry"]}.

3. Inspect incomplete, reasons, and each hit's clipped flag.

4. Call read_range with {"path":"src/retry.ts","start":20,"end":45} for exact evidence before editing or concluding.

5. file_inventory with {} is optional when filenames are unknown.

Search is case-sensitive literal substring matching, not regex or semantic search. Each matching line scores the number of distinct terms it contains. Sort is score descending, then relative path (code-unit order), then line ascending. Snippets contain up to 500 UTF-16 code units around the first match, and carry file/1-based line references. A snippet can omit later matched terms; exact reads resolve this. No task understanding or answer-quality guarantee is implied. Results are plain JSON in one MCP text content block (not duplicated as structured content).

read_range returns complete source lines without line endings, normalizing CRLF separators. It never silently clips a returned line. At the output cap it returns truncated and nextLine. A single source line exceeding the cap cannot be returned; inspect it locally. Ranges beyond EOF return the available lines or an empty array.

Bounds and exclusions

MCP framing/JSON escaping adds wire bytes beyond the inner JSON budget. File inventory is also output bounded; search uses that inventory and inherits incompleteness. Incomplete scans may examine different subsets on different filesystems or under time limits; ranking of collected hits is deterministic, not a promise of exhaustive or globally best matches. Limits apply per call, not per session. OS operations can block beyond cooperative time checks. No runtime token estimates are reported because byte/character counts are not model token counts.

All paths must be root-relative with / separators. Absolute paths, traversal, backslashes, Windows device/alternate-stream aliases, symlinks/junctions, and multi-link files are denied. Default exclusions include .git, node_modules, vendor, dist, build, coverage, .next, .cache, .ssh, .aws, .azure, .gnupg, .env and variants, credentials/secrets/service-account names, .npmrc, .netrc, SSH private-key names, and .pem/.key/.p12/.pfx files. Defaults cannot be negated.

Root .gitignore and .contextignore use gitignore syntax and are loaded at startup (restart after changing them). Nested .gitignore files and global Git exclusions are not loaded. Example .contextignore:

private-data/
*.log
customer-export.csv

Inventory lists eligible names, not a guarantee their content is readable. Filename exclusions do not detect all secrets: review the root and add ignores. Tool results can contain sensitive source data and are sent to your MCP client/model. Read SECURITY.md before using untrusted workspaces.

Reproducible benchmark

npm run benchmark creates and removes 40 synthetic files of 200 lines each. Two known constants are injected at exact file/line coordinates. It compares JSON containing every full file against bounded search plus exact evidence reads and asserts both answers and references. Token counts use js-tiktoken's o200k_base, not an assertion about the tokenizer of your Codex model.

This is a deliberately selective, synthetic payload-only comparison. It excludes prompts, tool schemas, reasoning, retries, and model output. It cannot establish end-to-end token savings, latency, or answer quality. See docs/validation.md for actual local results and pending checks.

Development

Official TypeScript MCP SDK v2 split packages: server/client 2.3.1, pinned with lockfile. The implementation uses supported McpServer.registerTool, Zod object schemas, StdioServerTransport, and SDK client subprocess tests. Reference: https://ts.sdk.modelcontextprotocol.io/v2/servers/tools and https://ts.sdk.modelcontextprotocol.io/v2/api/%40modelcontextprotocol/server/server/mcp.html . The direct transport path is intentionally used rather than the newer factory convenience API; real Codex compatibility is a separate integration gate.

CI covers Linux/Windows × Node 22/24; all four initial validation jobs passed. See validation evidence and real Codex workflow results, including limitations. npm run format formats source/tests/scripts. MIT © RunIron. Traditional Chinese: README.zh-TW.md.