ALPHA VERSION

RepoRelay is a self-hosted code context engine for MCP.

1. Add repositories from any source — GitHub, GitLab, Bitbucket, on-premise, or local disk
2. Index the refs you need — pick the branches and tags that matter; each gets its own versioned snapshot
3. Use them everywhere — every indexed repo is instantly available as MCP tools in Claude Desktop, Cursor, Windsurf, OpenCode, or any other MCP-capable client

Manage everything through the REST API or the admin dashboard. Register once, query from any project in any editor. RepoRelay parses files with tree-sitter, extracts symbols and imports, and stores everything in a hybrid search index (BM25 + pgvector).

RepoRelay runs entirely on your infrastructure — no third-party indexing service, no telemetry, no repo uploads. Code only leaves your network via the providers you explicitly configure: snippets requested by the LLM you connect via MCP (e.g. Claude, GPT), and chunks sent to your embedding provider during indexing (cloud providers like OpenAI see the code; a local Ollama setup keeps everything on-box).

Demo

Highlights

Quick Start

git clone https://github.com/chwoerz/reporelay.git
cd reporelay
cp .env.example .env

docker compose up -d

# Register a remote repo
curl -sS -X POST http://localhost:3001/api/repos \
  -H 'content-type: application/json' \
  -d '{"name":"my-lib","remoteUrl":"https://github.com/org/my-lib.git"}'

# Trigger indexing for a specific branch
curl -sS -X POST http://localhost:3001/api/repos/my-lib/sync \
  -H 'content-type: application/json' \
  -d '{"ref":"main"}'

# Index a tagged release — each version is stored independently
curl -sS -X POST http://localhost:3001/api/repos/my-lib/sync \
  -H 'content-type: application/json' \
  -d '{"ref":"v2.0.0"}'

# Search across all indexed repos and versions
curl -sS 'http://localhost:3001/api/search?query=handleAuth'

git clone https://github.com/chwoerz/reporelay.git
cd reporelay
pnpm install

docker compose up -d postgres

cp .env.example .env
# Defaults work for local development — no edits needed

# All-in-one dev script (Postgres + worker + web API)
pnpm dev

# Or individual services
pnpm dev:worker   # Background indexing worker
pnpm dev:mcp      # MCP server (HTTP on :3000)
pnpm dev:web      # REST API on :3001
pnpm dev:proxy    # MCP proxy (connects to MCP server)
pnpm dev:ui       # Angular dashboard on :4200

# Register a local repo
curl -sS -X POST http://localhost:3001/api/repos \
  -H 'content-type: application/json' \
  -d '{"name":"my-app","localPath":"/absolute/path/to/my-app"}'

# Register a remote repo
curl -sS -X POST http://localhost:3001/api/repos \
  -H 'content-type: application/json' \
  -d '{"name":"my-lib","remoteUrl":"https://github.com/org/my-lib.git"}'

# Trigger indexing for a specific branch
curl -sS -X POST http://localhost:3001/api/repos/my-app/sync \
  -H 'content-type: application/json' \
  -d '{"ref":"main"}'

# Index a tagged release — each version is stored independently
curl -sS -X POST http://localhost:3001/api/repos/my-lib/sync \
  -H 'content-type: application/json' \
  -d '{"ref":"v2.0.0"}'

# Search across all indexed repos and versions
curl -sS 'http://localhost:3001/api/search?query=handleAuth'

# Check status
curl -sS http://localhost:3001/api/repos

Supported Git Hosts

RepoRelay works with any Git repository accessible over HTTPS or on the local filesystem. There is no vendor lock-in — your repos can come from any combination of:

• GitHub (github.com and GitHub Enterprise)
• GitLab (gitlab.com and self-managed)
• Bitbucket (Cloud and Data Center)
• Azure DevOps
• Gitea / Forgejo
• Any on-premise Git server (Gerrit, cgit, etc.)
• Local repositories on disk

For private repos, set a GIT_TOKEN_<HOST> environment variable and RepoRelay handles authentication automatically. Host-specific username defaults are built-in for GitHub, GitLab, and Bitbucket — any other host uses GIT_USER_<HOST> or falls back to oauth2.

# Example: authenticate with GitHub and a self-hosted GitLab
GIT_TOKEN_GITHUB_COM=ghp_xxxxxxxxxxxx
GIT_TOKEN_GITLAB_INTERNAL_CORP_COM=glpat-xxxxxxxxxxxx

MCP Client Setup

Claude Desktop / Cursor

Clients connect via the MCP proxy, which auto-detects your project's languages and forwards requests to the RepoRelay HTTP server:

{
  "mcpServers": {
    "reporelay": {
      "command": "npx",
      "args": ["reporelay", "--server", "http://localhost:3000/mcp"]
    }
  }
}

See the full documentation for OpenCode, remote server, and other client configurations.

MCP Proxy

The MCP proxy is a lightweight local binary that sits between your IDE and the RepoRelay HTTP server. It:

1. Detects languages from the developer's working directory
2. Connects to the RepoRelay MCP server over HTTP
3. Forwards all MCP requests, injecting detected languages into tool calls

# Via CLI argument
npx reporelay --server http://localhost:3000/mcp

# Or via environment variable
REPORELAY_URL=http://localhost:3000/mcp npx reporelay

For a remote server, just change the URL:

{
  "mcpServers": {
    "reporelay": {
      "command": "npx",
      "args": ["reporelay", "--server", "https://reporelay.example.com/mcp"]
    }
  }
}

The proxy injects languages into 4 tools that support language filtering: search_code, get_symbol, find, and list_repos. Per-request languages values provided by the caller take priority over auto-detected ones.

Language Auto-Detection

When MCP_LANGUAGES is not set, the MCP server automatically detects the host project's language by scanning the working directory for well-known manifest files:

Detected languages are used to filter which repos are served — only repos whose language_stats contain a matching language above the threshold are included.

MCP_LANGUAGE_THRESHOLD (default: 10) controls the minimum percentage a language must represent in a repo ref's file breakdown. Set to 0 to disable repo filtering entirely.

{
  "mcpServers": {
    "reporelay": {
      "command": "npx",
      "args": ["tsx", "src/mcp/main.ts"],
      "env": {
        "DATABASE_URL": "postgresql://reporelay:reporelay@localhost:5432/reporelay",
        "MCP_LANGUAGE_THRESHOLD": "0"
      }
    }
  }
}

Documentation

Full documentation is available at the RepoRelay docs site, including:

• Indexing pipeline deep-dive
• MCP tools, resources & prompts reference
• REST API reference (18 endpoints)
• Configuration reference
• Database design
• Project structure
• Tech stack

Testing

Comprehensive test suite (unit + integration) covering every module.

pnpm test              # All tests
pnpm test:unit         # Unit tests only
pnpm test:integration  # Integration tests (requires Docker)
pnpm test:watch        # Watch mode

Integration tests use real ParadeDB containers via Testcontainers.

Tech Stack

TypeScript (ESM, strict) / Node.js 22+ / Fastify 5 / Drizzle ORM / ParadeDB (BM25 + pgvector) / pg-boss / tree-sitter / MCP SDK / Angular 21 / Vitest + Testcontainers / Docker

License

MIT