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_hostsvalidation 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_morehints - 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.ymlusesimage:instead ofbuild:, 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
