mcp-codebase: Instructions file for Codex

AGENTS.md

Guidance for AI coding agents working in this repository. Assumes no prior knowledge of the project.

Documentation workflow (required)

Detailed project documentation lives in docs/ as Markdown files (start from docs/README.md). For every task, follow this workflow:

1. Read the docs first. Before starting a task, read the parts of docs/ related to the task, and only then do the work.
2. Docs must match the code. If you find a discrepancy between the documentation and the actual code, update the documentation to reflect the code.
3. Keep docs current. After any code change, update the affected documentation in docs/ as part of the same change — a task is not done until the documentation is updated.
4. Commit and push. When the task is complete (code + docs), commit with a clear message and push to the remote repository.

Project overview

mcp-codebase is an MCP (Model Context Protocol) server that gives an AI agent semantic navigation over a codebase. It crawls a target project, parses source files into symbols, imports, and exports, stores them in PostgreSQL, and exposes six high-level MCP tools over stdio:

• search_symbols — find symbols by name with wildcards (*, ?), OR (|), and fuzzy trigram matching; filter by kind, language, file path.
• get_symbol_details — source code, signature, docstring, file imports, sibling symbols.
• explore_module — directory overview: file counts, key symbols, subdirectories, top imports.
• find_usages — grep-style reference search for a symbol name across the project.
• get_module_dependencies — what a file imports, what it exports, which files import it.
• reindex — full or incremental reindex of the target project.

Note: this server indexes an external codebase (pointed at by PROJECT_ROOT), not itself.

Tech stack and requirements

• Node.js 18+, TypeScript (ES2022 target, NodeNext modules, strict mode), pure ESM ("type": "module" in package.json).
• PostgreSQL 14+ with the pg_trgm extension (created automatically) for fuzzy symbol search.
• Key dependencies: @modelcontextprotocol/sdk (stdio transport), pg (connection pool), typescript (TS/JS parsing via the Compiler API), chokidar (watch mode), ignore (.gitignore handling), zod (tool input validation).