codesearch-mcp

Semantic codebase search for Claude. Indexes your local projects into a PostgreSQL vector database and exposes search via the Model Context Protocol (MCP).

Ask Claude things like "where is the payment retry logic?" or "show me how auth tokens are validated" — across all your projects at once.

Alpha — works well locally, API may change before 1.0.

See CHANGELOG.md for version history.

How it works

1. rag-index scans your projects, chunks source files, embeds them with bge-m3 via Ollama, and stores vectors in PostgreSQL
2. rag-mcp exposes an MCP server — Claude calls it automatically when you ask about code
3. Incremental — only changed files are re-indexed on subsequent runs

Stack: TypeScript · TypeORM · PostgreSQL + pgvector · Ollama (bge-m3) · LangChain text splitters · ts-morph

Requirements

• Node.js 18+
• Docker (for local DB + Ollama) — or bring your own PostgreSQL with pgvector + Ollama

Installation

npm install -g codesearch-mcp

Setup

rag-setup

Walks you through:

• Local Docker — copies docker-compose.yml, starts PostgreSQL + Ollama, pulls bge-m3 automatically
• Remote DB — enter connection details for Supabase, Railway, or self-hosted; connection is verified before saving
• Logging — choose log level and directory (defaults: error level, ~/.config/codesearch-mcp/logs/)

Config is saved to ~/.config/codesearch-mcp/.env.

Index your projects

rag-index /home/user/Projects

On first run you will be prompted to select which projects to index. Selections are saved in .ragprojects / .ragskip at the workspace root.

rag-index /path --select          # re-run project selection
rag-index /path --reindex         # force re-embed all files (use after model change)
rag-index /path --select --reindex

Register with Claude Code

claude mcp add codesearch-mcp -s user -- rag-mcp

Then ask Claude anything about your code — it will use the tools below automatically.

MCP Tools

| Tool | Description | |------|-------------| | search_codebase | Semantic search across all indexed projects | | list_projects | List projects with metadata and chunk counts | | find_symbol | Find a function, class, or type by exact name — faster than semantic search | | list_files | Browse the directory tree of a project | | read_file | Read a complete file by absolute path | | read_file_range | Read a specific line range from an indexed file | | get_dependencies | Show what files a given file imports | | get_dependents | Show which files import a given file |

Project metadata

Add .ragmeta.json to a project root to enrich list_projects and generate a visual dependency graph:

{
  "description": "Main API server",
  "stack": "NestJS, GraphQL, PostgreSQL",
  "relations": {
    "consumed_by": ["crm-frontend"],
    "consumes": ["billing-service", "auth-service"]
  }
}

After each indexing run an interactive project-graph.html is written to the workspace root.

Excluding files

Create .ragignore in a project root — same syntax as .gitignore:

src/gql/graphql.ts
**/__snapshots__/**
src/generated/

Logging

Logs are written to ~/.config/codesearch-mcp/logs/ by default (separate subdirectories for indexer and MCP). Only errors are logged unless configured otherwise.

# Read logs
tail -f ~/.config/codesearch-mcp/logs/indexer/current.log
npx pino-pretty < ~/.config/codesearch-mcp/logs/indexer/current.log

# Detailed indexing diagnostics (timing per file: deps / embed / db)
LOG_LEVEL=debug rag-index /path/to/workspace

# Disable file logging
LOG_DIR=false rag-index /path/to/workspace

Environment variables

All set by rag-setup. Override any of them in ~/.config/codesearch-mcp/.env.

| Variable | Default | Description | |----------|---------|-------------| | DB_HOST | — | PostgreSQL host | | DB_PORT | 5433 | PostgreSQL port | | DB_USER | — | PostgreSQL user | | DB_PASS | — | PostgreSQL password | | DB_NAME | rag_<os-username> | Database name — auto-created on first run | | WORKSPACE_ROOT | — | Root of your projects directory | | OLLAMA_HOST | http://localhost:11434 | Ollama API URL | | OLLAMA_MODEL | bge-m3 | Embedding model | | SIMILARITY_THRESHOLD | 0.6 | Max cosine distance — raise if search returns nothing | | AUTO_TRANSLATE | false | Translate non-English queries to English before embedding | | TRANSLATE_MODEL | llama3.2 | Ollama model for translation (requires ollama pull llama3.2) | | LOG_LEVEL | error | Log level written to file: error | warn | info | debug | | LOG_DIR | ~/.config/codesearch-mcp/logs | Base log directory, or false to disable |

License

MIT