repo-explorer-mcp

rmcp stdio 전송을 통해 explore_repository 도구를 노출하는 Rust MCP 서버로, Linux(x86_64-unknown-linux-gnu) 및 Windows(x86_64-pc-windows-msvc)용으로 제공됩니다. codebase-memory-mcp 백엔드와 ripgrep/rtk 텍스트 검색을 기반으로 내부 LLM 탐색 루프를 구동합니다.

설치 (권장: npx 설정 스크립트)

설정 스크립트는 OS/아키텍처를 감지하고, 런타임 종속성을 확인/설치하며, 일치하는 릴리스 아카이브를 다운로드하고 체크섬을 검증한 후 바이너리를 설치하고 PATH 상태를 보고하며, 바로 사용할 수 있는 .mcp.json 스니펫을 출력합니다.

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

플래그:

• -y, --yes — 비대화형; 종속성 설치를 자동 승인합니다.

• --force — 최신 바이너리가 이미 있어도 다시 설치합니다.

• --version <x.y.z> — 특정 릴리스를 설치합니다 (기본값: 최신).

• -h, --help — 사용법.

스크립트는 ~/.local/bin(Linux) 또는 %LOCALAPPDATA%\repo-explorer-mcp(Windows)에 설치합니다. 셸 프로필이나 시스템 PATH는 절대 수정하지 않으며, 설치 디렉터리가 PATH에 있는지만 보고합니다. ripgrep은 Linux에서는 apt/dnf/pacman을, Windows에서는 winget을 통해 자동으로 설치됩니다. 해당 패키지 관리자를 사용할 수 없으면 스크립트는 경고를 표시하고 ripgrep 자체 설치 문서를 안내할 뿐 직접 설치하지는 않습니다. rtk와 codebase-memory-mcp는 보고 전용입니다. 누락된 경우 스크립트가 알려주고 업스트림 설치 문서를 안내합니다(rtk는 선택 사항이며, 검색은 일반 ripgrep으로 대체됩니다).

Related MCP server: ast-outline-mcp

설치 (수동 대체 방법)

소스에서 빌드:

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

또는 릴리스 아카이브와 해당 체크섬을 다운로드하여 검증한 후 PATH에 바이너리를 배치합니다(검증 명령은 docs/smoke-test.md 참조). 릴리스 자산은 고정된 명명 규칙을 따릅니다:

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

https://github.com/kwitsch/repo-explorer-mcp/releases에서 확인할 수 있습니다.

버전 확인:

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

구성

서버는 TOML 구성을 읽습니다. 경로 우선순위: --config <path> → REPO_EXPLORER_CONFIG 환경 변수 → ./repo-explorer.toml. 실행 작업 디렉터리가 탐색할 리포지토리 루트로 처리됩니다.

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

각 api_key_env가 가리키는 환경 변수는 실제로 환경에 설정되어 있어야 하며, 그렇지 않으면 MissingEnvVar 오류로 구성 로드가 실패합니다.

.mcp.json

설치된 바이너리 형식(설정 스크립트가 출력하는 형식):

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

Windows에서 command는 %LOCALAPPDATA%\\repo-explorer-mcp\\repo-explorer-mcp.exe입니다. repo-explorer.toml이 실행 작업 디렉터리에 없으면 args에 "--config", "<path>"를 추가하세요. 저장소 내 개발 형식은 대신 cargo run --release --quiet -p repo-explorer-mcp --로 실행합니다.

빌드 및 테스트

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

문제 해결

구성 로드는 명명된 오류와 함께 즉시 실패합니다:

다운로드한 릴리스 아티팩트를 종단 간 검증하려면 docs/smoke-test.md를 참조하세요.