Codebase RAG MCP

A local-first, no API Key codebase retrieval MCP Server. It scans specified repositories, chunks code by code windows, and performs hybrid ranking via BM25, symbol names, file paths, and exact matches. It can be directly connected to Codex and also provides standard search / fetch tools for ChatGPT knowledge retrieval scenarios.

Features

• Uses git ls-files preferentially, respects nested .gitignore files of the repository; non-Git directories use filesystem scanning.

• Supports common text code formats such as TypeScript, JavaScript, Python, Go, Rust, Java, C/C++, C#, Ruby, Shell, SQL, Markdown, Vue, Svelte.

• Automatically splits camelCase, snake_case, and path words, supports common Chinese code query expansions, e.g., "用户登录认证".

• Returns precise file paths, line numbers, code snippets with line numbers, match reasons, and stable IDs for further reading.

• Path reading is restricted to the configured repository root; symbols links, binaries, secrets, environment variable files, minified code, and large files are skipped by default.

• Supports both local stdio and stateless Streamable HTTP /mcp.

Quick Start

Requires Node.js 20 or higher.

Get the project from GitHub:

git clone https://github.com/sudoriaa/codebase-rag-mcp.git
cd codebase-rag-mcp

Install dependencies and build:

npm install
npm run build
node dist/cli.js --root C:/path/to/your-repository

The last command starts the stdio MCP Server, which waits for an MCP client to connect, so it is normal for the terminal to keep running.

Connecting to Codex

Put the following into the user-level %USERPROFILE%/.codex/config.toml, or a trusted repository's .codex/config.toml:

[mcp_servers.codebase-rag]
command = "C:/Program Files/nodejs/node.exe"
args = [
  "C:/absolute/path/codebase-rag-mcp/dist/cli.js",
  "--root",
  "C:/absolute/path/your-repository"
]
cwd = "C:/absolute/path/codebase-rag-mcp"
startup_timeout_sec = 60
tool_timeout_sec = 120

It is recommended to use / for Windows TOML paths. Only fill in the executable for command, and put other parameters in args respectively. The PATH inherited by desktop applications may differ from PowerShell, so it is recommended to use the absolute path of node.exe for long-term use.

You can also register via the CLI:

codex mcp add codebase-rag -- "C:\Program Files\nodejs\node.exe" "C:\absolute\path\codebase-rag-mcp\dist\cli.js" --root "C:\absolute\path\your-repository"
codex mcp get codebase-rag --json

After configuration, restart the Codex desktop application or IDE extension. See examples/codex-config.toml for an example configuration.

Starting HTTP MCP

node dist/cli.js --root C:/path/to/your-repository --transport http --host 127.0.0.1 --port 3000

Endpoints:

• MCP: http://127.0.0.1:3000/mcp

• Health check: http://127.0.0.1:3000/health

• Reference source file: http://127.0.0.1:3000/source/:documentId

By default, it only listens to the local machine. When deploying to other machines, TLS, authentication, and access control should be added at the reverse proxy layer, and use --public-base-url to set the canonical address accessible by the model.

When listening directly on 0.0.0.0 or other non-local addresses, the service requires a Bearer Token:

$env:CODEBASE_MCP_TOKEN = "replace-with-a-long-random-token"
node dist/cli.js --root C:/path/to/your-repository --transport http --host 0.0.0.0 --port 3000

The client then needs to send Authorization: Bearer <token> for /mcp and /health. The reference addresses returned by the service will automatically include an HMAC signature, so users can directly open the corresponding /source link; manually accessing unsigned /source addresses still requires the Bearer Token. When publishing via a local reverse proxy, the service can continue to listen on 127.0.0.1, and the proxy handles external authentication.

MCP Tools

Recommended calling order:

1. Use search_code to find implementations and related snippets.

2. Use get_code_context to expand high-scoring snippets.

3. Use find_symbol for precise definition location.

4. Only use fetch when the full file is truly necessary.

Search Methodology

The index runs entirely in local memory:

1. Code files are sliced into chunks of up to 120 lines with a 20-line overlap.

2. Symbols like class, interface, type, enum, function, method are extracted from common language declarations.

3. The body text uses BM25 retrieval; symbols and paths are ranked separately.

4. Reciprocal-rank fusion is used to combine scores from body text, symbols, paths, and exact matches.

5. By default, at most two snippets are returned per file to avoid filling up results with duplicate boilerplate code.

This version has no external vector database and does not upload source code. For large-scale multi-repository, cross-language semantic retrieval, embedding retrieval or rerankers can be added before or after the existing CodebaseIndex.search, without changing the MCP tool contract.

Configuration

--root PATH
--transport stdio|http
--host HOST
--port PORT
--public-base-url URL
--max-file-bytes N
--max-files N

The corresponding environment variables are:

CODEBASE_ROOT
CODEBASE_TRANSPORT
CODEBASE_HOST
CODEBASE_PORT
CODEBASE_PUBLIC_BASE_URL
CODEBASE_MCP_TOKEN
CODEBASE_MAX_FILE_BYTES
CODEBASE_MAX_FILES

Default single file size limit is 1 MiB, file count limit is 20,000.

Development and Verification

npm run build
npm test

Tests cover index building, .gitignore, Chinese query expansion, symbol and path filtering, path traversal, standard search/fetch, in-memory MCP, real stdio subprocesses, and Streamable HTTP.

The MCP Inspector can also directly inspect the HTTP service:

npx @modelcontextprotocol/inspector

Then select Streamable HTTP and fill in http://127.0.0.1:3000/mcp.

The implementation follows the OpenAI Official MCP Server Guide and the standard search / fetch data shapes.

Current Boundaries

• The index is rebuilt after a process restart; there is no persistent cache.

• Git repositories fully respect Git ignore rules; non-Git directories currently read the root .gitignore.

• Symbol extraction uses lightweight declaration parsing and is not equivalent to a full compiler AST.

• Call refresh_index after file changes; file watching is not enabled in the current version.

License

MIT