codectx

codectx builds AST graph and embedding-backed context for TypeScript/NestJS codebases, then exposes that context to coding agents through MCP.

For a deeper overview of the indexing pipeline, graph model, retrieval flow, and MCP server, see Architecture.

Install

npm install -g @neetesh-better/codectx

Index a Repo

cd /path/to/typescript-repo
OPENAI_API_KEY=... codectx .

This creates graph and embedding artifacts in a global cache:

~/.codectx/repos/<repo-name>-<fingerprint>/

Set CODECTX_HOME to use a different cache root.

CLI

codectx ask "How does auth work?"
codectx search "validation schema"
codectx routes
codectx explain GET:/users/:id
codectx report
codectx doctor
codectx list

Re-run codectx . after meaningful code changes to refresh the index.

MCP

Print an MCP config snippet:

codectx mcp-config

The generated config launches:

codectx mcp

MCP Client Setup

VS Code

Open Command Palette with Command+Shift+P, run MCP: Open User Configuration, then add the following under servers:

"codectx": {
  "command": "codectx",
  "args": ["mcp"]
}

Codex

Go to Codex App -> Settings -> MCP server -> Add server.

• Command to launch: codectx
• Arguments: mcp
• Environment variable: add OPENAI_API_KEY

Save the server configuration.

Claude

Run:

claude mcp add --scope user --transport stdio codectx -- codectx mcp

codectx mcp starts a repo-aware MCP server. Agents should call list_indexed_repos first, then pass the returned repoId to other tools. Tools can also accept repoPath for manual or debugging use.

The server exposes tools such as list_indexed_repos, search_codebase, explain_endpoint, list_routes, find_node, get_validation_schemas, and find_callers_callees.

Environment

OPENAI_API_KEY=...
CODECTX_HOME=~/.codectx
EMBEDDING_MODEL=text-embedding-3-large
EMBEDDING_DIMENSIONS=3072
EMBEDDING_BATCH_SIZE=100
ANSWER_MODEL=gpt-4o-mini