Opengrok

OpenGrok MCP Server

English

MCP (Model Context Protocol) server for OpenGrok code search. Designed for AOSP 15 scale codebases.

Features

• 25 MCP tools — full OpenGrok REST API coverage: search (6 variants), file content, definitions, history, annotation, suggestions, directory listing, projects, groups, repository properties, system info
• Dual transport — stdio (docker exec) and Streamable HTTP (axum + rmcp)
• Flexible auth — Bearer token or HTTP Basic Auth to OpenGrok
• Custom CA — TLS with corporate/self-signed certificates via OPENGROK_CA_CERT / SSL_CERT_FILE
• DNS rebinding protection — allowed_hosts validation for Streamable HTTP (rmcp security check, configurable per deployment)
• Optimized for AOSP — result caching (TTL + eviction), rate limiting (token bucket), HTML tag stripping, pagination with has_more hints
• Health & metrics — /healthz, /readyz, /metrics (Prometheus)
• Docker — multi-stage build (UPX-compressed 23 MB image), docker-compose

Quick Start

Local

cp config/config.example.toml config/config.toml
# Edit config.toml — set base_url and auth mode
export OPENGROK_USERNAME="user"
export OPENGROK_PASSWORD="pass"
cargo run --release

Docker (local dev)

# Set credentials in config/.env (see config.example.toml)
docker compose up -d

Docker Hub (pre-built image)

Pre-built multi-arch images (linux/amd64, linux/arm64) are available on Docker Hub:

# Pull the latest release
docker pull rd2w/opengrok-mcp:latest

# Or from GitHub Container Registry
docker pull ghcr.io/rd2w/opengrok-mcp-server:latest

# Use the docker-compose file for pre-built images
docker compose -f docker-compose.hub.yml up -d

# Or run directly with docker run:
docker run -d \
  --name opengrok-mcp \
  -p 8080:8080 \
  -v ./config:/config:ro \
  --env-file ./config/.env \
  rd2w/opengrok-mcp:latest

The docker-compose.hub.yml uses image: instead of build:, so it pulls the pre-built image directly — no local Rust toolchain or compilation needed.

Docker (remote / air-gapped deployment)

For hosts without internet access (common in corporate environments), build the image on a connected machine, then transfer the archive:

# 1. Build on a machine with internet (all dependencies baked in)
docker build -t opengrok-mcp:latest .

# 2. Export as a single portable archive (~23 MB, UPX-compressed)
docker save opengrok-mcp:latest | gzip > opengrok-mcp.tar.gz

# 3. Transfer to the air-gapped host (USB drive, scp, etc.)
scp opengrok-mcp.tar.gz docker-compose.yml remote-host:~/mcp/

# 4. On the remote host — load and run (no internet needed)
ssh remote-host
cd ~/mcp/
docker load < opengrok-mcp.tar.gz               # imports the image
mkdir -p config
cp /path/to/config.toml config/                 # your config
cp /path/to/your-ca.crt config/certs/           # CA cert (if needed)
# Create config/.env with secrets (never commit this file)
echo 'OPENGROK_TOKEN=your-token' > config/.env
docker compose up -d

The multi-stage build produces a fully self-contained Alpine-based image — no network access is required at runtime. TLS root certificates and all OpenGrok client dependencies are baked into the image.

Configuration

See config/config.example.toml for all options. Key sections:

MCP server-side token auth

When mcp_auth_token is non-empty (set in config.toml or via MCP_AUTH_TOKEN env var), the HTTP transport requires Authorization: Bearer <token> on every incoming MCP request. Token comparison uses subtle::ConstantTimeEq (timing-safe). This is inbound auth for the MCP server — separate from the OpenGrok outbound auth configured in [opengrok.auth].

Streamable HTTP & DNS rebinding protection

When mode = "http", rmcp validates the Host header of incoming requests against allowed_hosts. Requests with non-matching hosts receive 403 Forbidden.

For Docker deployments where clients connect via container name:

[transport]
mode = "http"
bind_addr = "0.0.0.0:8004"
allowed_hosts = ["localhost", "127.0.0.1", "opengrok-mcp", "opengrok-mcp:8004"]

Documentation

Full documentation is available in docs/en/:

• Overview — capabilities and project status
• Installation — requirements, build, Docker
• Usage — config reference, transport modes, all 25 MCP tools
• Architecture — workspace layout, crate responsibilities, data flow
• Development — contributing, testing, CI, conventions

Development

cargo test                    # 185 tests
cargo fmt --all -- --check
cargo clippy --workspace --all-targets -- -D warnings

Project structure

crates/opengrok-core/    # Library — domain models, HTTP client, TLS, cache, rate-limit
crates/opengrok-mcp/     # Binary — MCP server, config, transport (stdio + HTTP)
config/                  # Configuration files (gitignored): config.toml, .env, certs/

License

GPL-3.0-or-later

Русский

MCP (Model Context Protocol) сервер для поиска по коду OpenGrok. Разработан для кодовых баз масштаба AOSP 15.

Возможности

• 25 инструментов MCP — полное покрытие OpenGrok REST API: поиск (6 вариантов), содержимое файлов, определения, история, аннотация, подсказки, список директорий, проекты, группы, свойства репозиториев, системная информация
• Двойной транспорт — stdio (docker exec) и Streamable HTTP (axum + rmcp)
• Гибкая аутентификация — Bearer-токен или HTTP Basic Auth для OpenGrok
• Пользовательские сертификаты — TLS с корпоративными/самоподписанными сертификатами через OPENGROK_CA_CERT / SSL_CERT_FILE
• Защита от DNS rebinding — проверка allowed_hosts для Streamable HTTP (механизм безопасности rmcp, настраивается под развёртывание)
• Оптимизации для AOSP — кэширование результатов (TTL + вытеснение), ограничение частоты (token bucket), очистка HTML-тегов, пагинация с подсказками has_more
• Health и метрики — /healthz, /readyz, /metrics (Prometheus)
• Docker — многоэтапная сборка (образ 23 МБ, сжат UPX), docker-compose

Быстрый старт

Локально

cp config/config.example.toml config/config.toml
# Отредактируйте config.toml — укажите base_url и режим аутентификации
export OPENGROK_USERNAME="пользователь"
export OPENGROK_PASSWORD="пароль"
cargo run --release

Docker (локальная разработка)

# Задайте учётные данные в config/.env (см. config.example.toml)
docker compose up -d

Docker Hub (готовый образ)

Готовые multi-arch образы (linux/amd64, linux/arm64) доступны на Docker Hub:

# Загрузка последнего релиза
docker pull rd2w/opengrok-mcp:latest

# Или из GitHub Container Registry
docker pull ghcr.io/rd2w/opengrok-mcp-server:latest

# Используйте docker-compose файл для готовых образов
docker compose -f docker-compose.hub.yml up -d

# Или запустите напрямую через docker run:
docker run -d \
  --name opengrok-mcp \
  -p 8080:8080 \
  -v ./config:/config:ro \
  --env-file ./config/.env \
  rd2w/opengrok-mcp:latest

Файл docker-compose.hub.yml использует image: вместо build:, поэтому загружает готовый образ напрямую — локальный Rust toolchain и компиляция не нужны.

Docker (удалённый / изолированный деплой)

Для хостов без доступа в интернет (корпоративные среды) образ собирается на машине с сетью, затем переносится архивом:

# 1. Сборка на машине с интернетом (все зависимости вкомпилированы в образ)
docker build -t opengrok-mcp:latest .

# 2. Экспорт в один переносимый архив (~23 МБ, сжатый UPX)
docker save opengrok-mcp:latest | gzip > opengrok-mcp.tar.gz

# 3. Перенос на изолированный хост (USB-накопитель, scp и т.д.)
scp opengrok-mcp.tar.gz docker-compose.yml remote-host:~/mcp/

# 4. На удалённом хосте — загрузка и запуск (интернет не нужен)
ssh remote-host
cd ~/mcp/
docker load < opengrok-mcp.tar.gz               # импорт образа
mkdir -p config
cp /path/to/config.toml config/                 # ваша конфигурация
cp /path/to/your-ca.crt config/certs/           # CA-сертификат (если нужен)
# Создайте config/.env с учётными данными (никогда не коммитьте этот файл)
echo 'OPENGROK_TOKEN=ваш-токен' > config/.env
docker compose up -d

Многоэтапная сборка создаёт полностью самодостаточный образ на базе Alpine — сеть не требуется во время работы. Корневые TLS-сертификаты и все зависимости OpenGrok-клиента вкомпилированы в образ.

Конфигурация

Все опции в config/config.example.toml. Основные секции:

Токен-аутентификация MCP-сервера

Если mcp_auth_token не пуст (задан в config.toml или через MCP_AUTH_TOKEN), HTTP-транспорт требует заголовок Authorization: Bearer <токен> на каждом входящем MCP-запросе. Сравнение токена — subtle::ConstantTimeEq (timing-safe). Это входящая аутентификация MCP-сервера — отдельно от исходящей аутентификации к OpenGrok в [opengrok.auth].

Streamable HTTP и защита от DNS rebinding

В режиме mode = "http" rmcp проверяет заголовок Host входящих запросов по списку allowed_hosts. Запросы с несовпадающим хостом получают 403 Forbidden.

Для Docker, где клиенты подключаются по имени контейнера:

[transport]
mode = "http"
bind_addr = "0.0.0.0:8004"
allowed_hosts = ["localhost", "127.0.0.1", "opengrok-mcp", "opengrok-mcp:8004"]

Документация

Полная документация в docs/ru/:

• Обзор — возможности и статус проекта
• Установка — требования, сборка, Docker
• Использование — справочник по конфигурации, режимы транспорта, все 25 инструментов MCP
• Архитектура — структура workspace, зоны ответственности крейтов, поток данных
• Разработка — участие, тестирование, CI, соглашения

Разработка

cargo test                    # 185 тестов
cargo fmt --all -- --check
cargo clippy --workspace --all-targets -- -D warnings

Структура проекта

crates/opengrok-core/    # Библиотека — доменные модели, HTTP-клиент, TLS, кэш, rate-limit
crates/opengrok-mcp/     # Бинарный — MCP-сервер, конфигурация, транспорт (stdio + HTTP)
config/                  # Файлы конфигурации (в gitignore): config.toml, .env, certs/

Лицензия

GPL-3.0-or-later