Codex MCP Server

# Repository Guidelines ## Project Structure & Module Organization - `src/` TypeScript sources (ESM): - `index.ts` MCP entrypoint (stdio server) - `tools/` MCP tools (`*.tool.ts`), `registry.ts`, `index.ts` (registration) - `utils/` execution, logging, parsing helpers - `constants.ts` shared types/strings - `dist/` compiled output (generated by `tsc`). - `docs/` VitePress docs. - `scripts/` maintenance utilities (e.g., wiki deploy). Example: add a tool under `src/tools/my-feature.tool.ts`, then register it in `src/tools/index.ts` by pushing to `toolRegistry`. ## Build, Test, and Development Commands - `npm run build` — compile TypeScript to `dist/`. - `npm start` — run server from `dist/`. - `npm run dev` — compile once then run (no watch). - `npm run lint` — type-check only (`tsc --noEmit`). - Docs: `npm run docs:dev|docs:build|docs:preview` — develop/build/preview VitePress site. Requirements: Node `>=16`. The server shells out to the `codex` CLI; ensure it's installed and authenticated in your environment. ## Coding Style & Naming Conventions - Language: TypeScript (ESM, Node16 resolution). Imports use `.js` extensions in `src/` to match ESM output. - Indentation: 2 spaces; prefer single quotes in strings except where template literals or readability favors otherwise. - Filenames: `kebab-case`. Tools end with `.tool.ts` (e.g., `fetch-chunk.tool.ts`). - Types: keep `zod` schemas colocated with tools; export a `UnifiedTool` and register it. ## Testing Guidelines - Currently no automated tests (`npm test` is a stub). If adding tests, place them alongside sources (e.g., `src/**/__tests__`) and mirror filenames. - Aim for unit coverage on parsing/execution utilities in `src/utils/` and schema validation. ## Commit & Pull Request Guidelines - Commits: concise, imperative subject (e.g., `feat: add brainstorm tool`, `fix(utils): handle quota errors`). - PRs: include a clear description, linked issues, reproduction steps, and sample CLI output (stdout/stderr) when relevant. - Keep changes scoped; update docs in `docs/` or `README.md` when behavior/CLI changes. ## Agent-Specific Notes - Tools exposed: `ask-codex`, `brainstorm`, `fetch-chunk`, `ping`, `Help` (register in `src/tools/index.ts`). - Quick local run (no build): `npx tsx src/index.ts`. - Codex flags passthrough: prefer `fullAuto`, `approvalPolicy`, `sandboxMode`, `yolo`, `cd` in tool args over hardcoding flags. ## Security & Configuration Tips - Never commit secrets. Configure Codex credentials via the `codex` CLI/env locally. - Validate untrusted input through `zod` schemas; avoid spawning arbitrary commands beyond the intended `codex` CLI. ## Adding New Features ### To Add a New Tool 1. Create `src/tools/your-tool.tool.ts` 2. Define zod schema for arguments 3. Export `UnifiedTool` object with name, description, schema, and execute function 4. Register in `src/tools/index.ts` by adding to `toolRegistry.push()`