Skip to main content
Glama
repo-explorer-mcp

repo-explorer-mcp

by kwitsch

repo-explorer-mcp

一个 Rust MCP 服务器,通过 rmcp stdio 传输暴露 explore_repository 工具,为 Linux(x86_64-unknown-linux-gnu)和 Windows(x86_64-pc-windows-msvc)发布。它驱动一个内部 LLM 探索循环,基于 codebase-memory-mcp 后端和 ripgrep/rtk 文本搜索。

安装(推荐:npx 设置脚本)

设置脚本会检测你的操作系统/架构,检查/安装运行时依赖,下载并校验匹配的发布归档,安装二进制文件,报告 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)。它从不修改你的 shell 配置文件或系统 PATH——只报告安装目录是否在 PATH 中。ripgrep 在 Linux 上通过 apt/dnf/pacman 自动安装,在 Windows 上通过 winget 安装;如果这些都不可用,脚本会发出警告并指向 ripgrep 自己的安装文档,而不是自行安装。rtk 和 codebase-memory-mcp 仅报告:如果缺失,脚本会告知你并指向其上游安装文档(rtk 是可选的;搜索会回退到纯 ripgrep)。

Related MCP server: mnemo

安装(手动备用)

从源码构建:

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 不在启动 cwd 中,请将 "--config", "<path>" 添加到 args。仓库内开发形式则通过 cargo run --release --quiet -p repo-explorer-mcp -- 启动。

构建与测试

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

故障排除

配置加载快速失败并带有命名错误:

错误

原因

修复

EmptyProviderList

llm.providers 为空

至少添加一个 [[llm.providers]]。

DuplicateProviderName

两个提供者共享一个 name

使每个提供者的 name 唯一。

MissingEnvVar

api_key_env 指定了一个未设置的变量

启动前 export 指定的变量。

MissingCodebaseMemoryConnection

既未设置 command 也未设置 endpoint

在 [codebase_memory] 下恰好设置一个。

ConflictingCodebaseMemoryConnection

同时设置了 command 和 endpoint

只保留一个。

参见 docs/smoke-test.md 以端到端验证下载的发布工件。

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      B
      maintenance
      Enables read-only querying of a local repository through a deterministic tree-sitter symbol and edge graph, exposing keyword search with exact file:line hits, regex text search, per-file symbol skeletons, caller/callee traversal, and directory-level maps of clusters, hubs, and hotspots over stdio.
      10
      85 npm
      1
      Apache 2.0
    • A
      license
      Not graded
      quality
      C
      maintenance
      Serves local-first project memory over stdio, exposing tools to inspect project state, search and retrieve context, report memory, and create Git-aware checkpoints for coding agents.
      1
      Apache 2.0
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables MCP clients such as Claude Desktop and Claude Code to query an indexed source repository through path-guarded tools for hybrid keyword-and-vector code search, file snippets, symbol explanations, reference lookups, and test-skeleton suggestions. Serves those results over stdio with cited file:line locations so agents can answer questions about a codebase and drive grounded code review.
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables coding agents to find code by behavior across an authorized repository, returning exact source excerpts with paths and line numbers. It exposes a single semantic search tool over stdio so agents can locate relevant code without knowing file names or symbols.
      1
      MIT