repo-explorer-mcp

Un servidor MCP en Rust que expone la herramienta explore_repository a través de un transporte rmcp stdio, distribuido para Linux (x86_64-unknown-linux-gnu) y Windows (x86_64-pc-windows-msvc). Impulsa un bucle interno de exploración con LLM sobre un backend codebase-memory-mcp y búsqueda de texto con ripgrep/rtk.

Instalación (recomendado: script de configuración npx)

El script de instalación detecta tu SO/arquitectura, comprueba/instala las dependencias de ejecución, descarga y verifica la suma de comprobación del archivo de versión correspondiente, instala el binario, informa del estado de PATH e imprime un fragmento .mcp.json listo para usar.

npx github:kwitsch/repo-explorer-mcp
# After the package is published to npm:
# npx repo-explorer-mcp-setup

Opciones:

• -y, --yes — no interactivo; aprueba automáticamente las instalaciones de dependencias.

• --force — reinstala incluso si ya hay un binario actualizado.

• --version <x.y.z> — instala una versión específica (por defecto: la última).

• -h, --help — uso.

El script instala en ~/.local/bin (Linux) o %LOCALAPPDATA%\repo-explorer-mcp (Windows). Nunca edita tu perfil de shell ni el PATH del sistema; solo informa de si el directorio de instalación está en PATH. ripgrep se instala automáticamente mediante apt/dnf/pacman en Linux o winget en Windows; si ninguno de esos está disponible, el script avisa y remite a la documentación de instalación de ripgrep en lugar de instalarlo por sí mismo. rtk y codebase-memory-mcp son solo informativos: si faltan, el script te lo indica y remite a su documentación de instalación original (rtk es opcional; la búsqueda recurre a ripgrep simple).

Related MCP server: ast-outline-mcp

Instalación (alternativa manual)

Compilar desde el código fuente:

cargo build --release --workspace
# binary at target/release/repo-explorer-mcp

O descarga un archivo de versión y su suma de comprobación, verifícalo y coloca el binario en PATH (consulta docs/smoke-test.md para los comandos de verificación). Los archivos de versión siguen el contrato de nomenclatura fijo:

repo-explorer-mcp-<version>-x86_64-unknown-linux-gnu.tar.gz (+ .sha256)
repo-explorer-mcp-<version>-x86_64-pc-windows-msvc.zip       (+ .sha256)

desde https://github.com/kwitsch/repo-explorer-mcp/releases.

Verifica la versión:

repo-explorer-mcp --version # prints: repo-explorer-mcp 0.1.0

Configuración

El servidor lee una configuración TOML. Precedencia de rutas: --config <path> → variable de entorno REPO_EXPLORER_CONFIG → ./repo-explorer.toml. El directorio de trabajo de lanzamiento se trata como la raíz del repositorio a explorar.

Ejemplo de repo-explorer.toml:

[llm]
# Failover cooldown after a provider errors, in seconds.
cooldown_seconds = 90

# Providers are tried in file order (= failover order).
[[llm.providers]]
name = "primary"
kind = "anthropic"
api_key_env = "ANTHROPIC_API_KEY"   # names an env var; never the key itself
model = "claude-sonnet-4"

[[llm.providers]]
name = "secondary"
kind = "openai"
api_key_env = "OPENAI_API_KEY"
model = "gpt-4o"

# Exactly one of `command`+`args` (stdio) XOR `endpoint` (network).
[codebase_memory]
command = "codebase-memory-mcp"
args = ["--stdio"]

[search]
prefer_rtk = false        # true prefers `rtk rg`; false uses plain ripgrep
timeout_seconds = 45
# rtk_path / ripgrep_path may be set explicitly; omitted => auto-detected on PATH.

[logging]
level = "info"            # trace | debug | info | warn | error

La variable de entorno indicada por cada api_key_env debe estar realmente definida en el entorno; de lo contrario, la carga de la configuración falla con MissingEnvVar.

.mcp.json

Forma de binario instalado (lo que imprime el script de instalación):

{
  "mcpServers": {
    "repo-explorer": {
      "command": "/home/you/.local/bin/repo-explorer-mcp",
      "args": [],
      "env": {}
    }
  }
}

En Windows, el command es %LOCALAPPDATA%\\repo-explorer-mcp\\repo-explorer-mcp.exe. Añade "--config", "<path>" a args si tu repo-explorer.toml no está en el directorio de trabajo de lanzamiento. La forma de desarrollo dentro del repositorio, en cambio, se lanza mediante cargo run --release --quiet -p repo-explorer-mcp --.

Compilación y pruebas

cargo build --workspace
cargo test --workspace
cargo clippy --all-targets -- -D warnings
cargo fmt --check

Solución de problemas

La carga de la configuración falla rápidamente con un error con nombre:

Consulta docs/smoke-test.md para verificar de principio a fin un artefacto de versión descargado.