内容
## codeloupe-mcp
一个模型上下文协议（MCP）服务器，为编码代理提供快速、本地优先的大型代码库访问。它使LLM能够检查文件、搜索文本、比较目录、读取符号，并通过有界工具响应应用结构化编辑，而不是将整个文件或存储库树转储到上下文中。
### codeloupe-mcp vs shell 工具
该软件包提供了一个MCP接口，用于存储库探索和代码编辑。
如果你正在使用**编码代理**，shell命令对于简洁的构建/测试工作流仍然很有用。`codeloupe-mcp`在模型需要跨聊天会话的、结构化的、可重复的、存储库感知的代码上下文时最为有用。
- **Shell / CLI**：最适合确定性命令，如`cargo test`、`npm run lint`、项目脚本、一次性`rg`和已经压缩的构建日志。
- **MCP**：最适合于受益于工具模式、workspace-aware路径解析、有界输出、持久索引和精确读取（如符号体、代码段、浅项目映射和目录差异）的代理循环。
在需要代理询问确切的代码上下文时使用`codeloupe-mcp`：一行范围、一个符号体、有界搜索结果、模糊文件匹配、workspace摘要或源目录比较。
### 主要功能
- **快速且轻量级**：本地Rust服务器通过`stdio`；无外部索引服务，无网络调用，无遥测。
- **LLM友好输出**：工具返回为代理上下文窗口设计的限定JSON/Markdown。
- **存储库感知索引**：LMDB路径元数据加上每个工作区的可选Tantivy内容索引。
- **精确代码读取**：读取聚焦的行范围、代码段、符号体、导入、导出、调用图、定义和引用。
- **作用域搜索**：字面和正则搜索，带有路径作用域、包含/排除通配符、备用诊断和大型存储库防护措施。
- **目录比较**：比较两个源目录，带有添加/删除/修改/重命名的摘要和限定差异。
- **结构化编辑**：创建、编辑、转换和删除文件，带有可预测的成功/错误元数据。
### 要求
- 一个支持本地`stdio`服务器的MCP客户端。
- 使用`npx`时，Node.js 18或更新版本。
- 使用已发布的npm包或原生发布二进制文件时，不需要Rust工具链。
- 从源代码构建时，需要稳定的Rust。
### 入门指南
首先，使用您的客户端安装`codeloupe-mcp`服务器。
**标准配置**在大多数MCP客户端中有效：
```json
{
"mcpServers": {
"codeloupe-mcp": {
"command": "npx",
"args": ["-y", "@ndhkaeru/codeloupe-mcp@latest"]
}
}
}
```
您也可以使用[GitHub Releases](https://github.com/ndhkaeru/codeloupe-mcp/releases)页面上的原生二进制文件：
```json
{
"mcpServers": {
"codeloupe-mcp": {
"command": "/absolute/path/to/codeloupe-mcp",
"args": []
}
}
}
```
在Windows原生安装中，指向`.exe`文件，例如`C:\path\to\codeloupe-mcp.exe`。
<details>
<summary>Amp</summary>
通过Amp VS Code扩展设置屏幕或更新设置JSON添加：
```json
"amp.mcpServers": {
"codeloupe-mcp": {
"command": "npx",
"args": ["-y", "@ndhkaeru/codeloupe-mcp@latest"]
}
}
```
Amp CLI设置：
```bash
amp mcp add codeloupe-mcp -- npx -y @ndhkaeru/codeloupe-mcp@latest
```
</details>
<details>
<summary>Antigravity</summary>
通过Antigravity设置或更新MCP配置文件添加：
```json
{
"mcpServers": {
"codeloupe-mcp": {
"command": "npx",
"args": ["-y", "@ndhkaeru/codeloupe-mcp@latest"]
}
}
}
```
</details>
<details>
<summary>Claude Code</summary>
使用Claude Code CLI：
```bash
claude mcp add codeloupe-mcp -- npx -y @ndhkaeru/codeloupe-mcp@latest
```
原生二进制文件替代：
```bash
claude mcp add codeloupe-mcp -- /absolute/path/to/codeloupe-mcp
```
</details>
<details>
<summary>Claude Desktop</summary>
按照MCP安装指南并使用标准配置：
```json
{
"mcpServers": {
"codeloupe-mcp": {
"command": "npx",
"args": ["-y", "@ndhkaeru/codeloupe-mcp@latest"]
}
}
}
```
原生Windows二进制文件替代：
```json
{
"mcpServers": {
"codeloupe-mcp": {
"command": "C:\\path\\to\\codeloupe-mcp.exe",
"args": []
}
}
}
```
</details>
<details>
<summary>Cline</summary>
按照Cline的MCP服务器配置流程，并在`cline_mcp_settings.json`中添加：
```json
{
"mcpServers": {
"codeloupe-mcp": {
"type": "stdio",
"command": "npx",
"timeout": 60,
"args": ["-y", "@ndhkaeru/codeloupe-mcp@latest"],
"disabled": false
}
}
}
```
</details>
<details>
<summary>Codex</summary>
使用Codex CLI：
```bash
codex mcp add codeloupe-mcp -- npx -y @ndhkaeru/codeloupe-mcp@latest
```
或者，创建或编辑`~/.codex/config.toml`:
```toml
[mcp_servers.codeloupe-mcp]
command = "npx"
args = ["-y", "@ndhkaeru/codeloupe-mcp@latest"]
```
</details>
<details>
<summary>Copilot</summary>
使用Copilot MCP添加流程，或将以下内容添加到您的MCP配置中：
```json
{
"mcpServers": {
"codeloupe-mcp": {
"type": "local",
"command": "npx",
"tools": ["*"],
"args": ["-y", "@ndhkaeru/codeloupe-mcp@latest"]
}
}
}
```
</details>
<details>
<summary>Cursor</summary>
前往`Cursor Settings` -> `MCP` -> `Add new MCP Server`。
使用命令类型：
```bash
npx -y @ndhkaeru/codeloupe-mcp@latest
```
或粘贴标准配置：
```json
{
"mcpServers": {
"codeloupe-mcp": {
"command": "npx",
"args": ["-y", "@ndhkaeru/codeloupe-mcp@latest"]
}
}
}
```
</details>
<details>
<summary>Factory</summary>
使用Factory CLI：
```bash
droid mcp add codeloupe-mcp "npx -y @ndhkaeru/codeloupe-mcp@latest"
```
或者，打开Factory的MCP UI并粘贴标准配置。
</details>
<details>
<summary>Gemini CLI</summary>
使用Gemini CLI MCP配置文件并添加：
```json
{
"mcpServers": {
"codeloupe-mcp": {
"command": "npx",
"args": ["-y", "@ndhkaeru/codeloupe-mcp@latest"]
}
}
}
```
</details>
<details>
<summary>Goose</summary>
前往`Advanced settings` -> `Extensions` -> `Add custom extension`。
使用`STDIO`类型和命令：
```bash
npx -y @ndhkaeru/codeloupe-mcp@latest
```
</details>
<details>
<summary>Junie</summary>
使用Junie's MCP流程，或添加到`.junie/mcp/mcp.json`：
```json
{
"mcpServers": {
"codeloupe-mcp": {
"command": "npx",
"args": ["-y", "@ndhkaeru/codeloupe-mcp@latest"]
}
}
}
```
</details>
<details>
<summary>Kiro</summary>
按照Kiro的MCP服务器文档并添加：
```json
{
"mcpServers": {
"codeloupe-mcp": {
"command": "npx",
"args": ["-y", "@ndhkaeru/codeloupe-mcp@latest"]
}
}
}
```
</details>
<details>
<summary>LM Studio</summary>
前往`Program`在右侧边栏 -> `Install` -> `Edit mcp.json`。
使用标准配置：
```json
{
"mcpServers": {
"codeloupe-mcp": {
"command": "npx",
"args": ["-y", "@ndhkaeru/codeloupe-mcp@latest"]
}
}
}
```
</details>
<details>
<summary>opencode</summary>
添加到`~/.config/opencode/opencode.json`:
```json
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"codeloupe-mcp": {
"type": "local",
"command": ["npx", "-y", "@ndhkaeru/codeloupe-mcp@latest"],
"enabled": true
}
}
}
```
</details>
<details>
<summary>Qodo Gen</summary>
打开VS Code或IntelliJ中的Qodo Gen聊天面板，选择`Connect more tools` -> `+ Add new MCP`，然后粘贴标准配置。
</details>
<details>
<summary>VS Code</summary>
使用MCP服务器配置：
```json
{
"servers": {
"codeloupe-mcp": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@ndhkaeru/codeloupe-mcp@latest"]
}
}
}
```
您也可以使用VS Code CLI安装：
```bash
code --add-mcp '{"name":"codeloupe-mcp","command":"npx","args":["-y","@ndhkaeru/codeloupe-mcp@latest"]}'
```
</details>
<details>
<summary>Warp</summary>
前往`Settings` -> `AI` -> `Manage MCP Servers` -> `+ Add`，或使用`/add-mcp`斜杠命令并粘贴标准配置。
</details>
<details>
<summary>Windsurf</summary>
按照Windsurf的MCP文档并使用标准配置：
```json
{
"mcpServers": {
"codeloupe-mcp": {
"command": "npx",
"args": ["-y", "@ndhkaeru/codeloupe-mcp@latest"]
}
}
}
```
</details>
### 配置
`codeloupe-mcp`通过MCP服务器进程中的环境变量进行配置。
| 变量 | 描述 |
|----------|-------------|
| `codeloupe_mcp_INDEX_DIR` | 覆盖持久索引缓存目录。 |
| `codeloupe_mcp_TANTIVY_ENABLED` | 启用/禁用Tantivy内容侧车。默认为`true`。 |
| `codeloupe_mcp_WALK_THREADS` | 文件系统遍历并行度。值被限制在`1..=6`。 |
| `codeloupe_mcp_BINARY` | npm包装器覆盖自定义本地二进制路径。 |
自定义索引目录示例：
```json
{
"mcpServers": {
"codeloupe-mcp": {
"command": "npx",
"args": ["-y", "@ndhkaeru/codeloupe-mcp@latest"],
"env": {
"codeloupe_mcp_INDEX_DIR": "/path/to/cache"
}
}
}
}
```
### 工具
工具按用途分组。每个响应都使用标准的MCP `content`数组形状，并保持输出限定以适应代理上下文。
<details>
<summary>文件和编辑</summary>
| 工具 | 描述 |
|------|-------------|
| `resolve_path` | 规范化路径并返回预检可访问性元数据。 |
| `read_file_range` | 读取文件或行范围，并检测编码和截断元数据。 |
| `count_file_lines` | 统计文本文件的行数，并检测编码和二进制文件。 |
| `read_snippets` | 一次读取多个文件范围。 |
| `file_summary` | 返回文件元数据、二进制检测和简短预览。 |
| `convert_file_format` | 重写文件并规范编码和换行符。 |
| `create_file` | 创建或覆盖文件。 |
| `create_directory` | 创建目录并可选地创建父目录。 |
| `edit_file` | 编辑文件并替换、追加、prepend或查找替换。 |
| `delete_file` | 删除一个文件并带有结构化成功/错误元数据。 |
</details>
<details>
<summary>搜索和工作区</summary>
| 工具 | 描述 |
|------|-------------|
| `text_search` | 字面或正则搜索，带有路径作用域、包含/排除过滤器和备用诊断。 |
| `fuzzy_find` | 跨作用域根的模糊路径和文件名搜索。 |
| `project_map` | 带有可选大小元数据的限定树视图。 |
| `workspace_stats` | 文件、行、语言和大小摘要。 |
| `compare_directories` | 比较两个源目录树，带有添加/删除/修改/重命名摘要和限定差异。 |
</details>
<details>
<summary>代码智能</summary>
| 工具 | 描述 |
|------|-------------|
| `get_symbols` | 从源文件提取Tree-sitter符号。 |
| `read_symbol_body` | 读取符号体并使用AST优先解析和备用启发式算法。 |
| `find_definition` | 在代码文件中查找可能的符号定义。 |
| `find_references` | 在代码文件中查找可能的符号引用。 |
| `list_imports` | 列出支持的语言的导入。 |
| `list_exports` | 列出支持的语言的导出。 |
| `get_call_graph` | 列出函数或符号发出的外部调用。 |
| `compare_symbols` | 比较两个解析的符号并返回元数据以及统一的差异。 |
</details>
<details>
<summary>数据和诊断</summary>
| 工具 | 描述 |
|------|-------------|
| `peek_archive` | 列出存档条目或读取存档内的一个文件。 |
| `server_health` | 报告正常运行时间、工作区和索引健康状况。 |
| `content_index_status` | 报告作用域文件或目录的Tantivy内容索引状态。 |
| `warm_content_index` | 为重复搜索预热Tantivy内容索引区。 |
| `batch_tool_calls` | 在一个MCP请求中运行一个短序列的工具。 |
</details>
### 支持的语言
AST支持的工具使用Tree-sitter，适用于Rust、C、C++、Go、Java、C#、PHP、Ruby、JavaScript、TypeScript、Python、Swift和Objective-C。
`list_imports`和`list_exports`目前支持Rust、JavaScript/TypeScript、Swift和Objective-C。文件搜索/工作区工具适用于任何文本文件，无论语言如何。
### 大型仓库指南
- 将`paths`限定为最小的有用子树。
- 尽可能优先使用字面`text_search`，以便Tantivy可以缩短文件列表。
- 使用具体的文件名或路径令牌进行`fuzzy_find`。
- 保持`project_map`浅层，例如`max_depth <= 2`。
- 使用递归排除，例如`third_party/**`、`node_modules/**`、`target/**`、`dist/**`和`out/**`。
- 在搜索结果后使用`read_snippets`而不是读取整个文件。
### 索引存储
服务器为每个规范的工作区根目录保留一个索引。
- Windows：`%LOCALAPPDATA%\codeloupe-mcp\index-v2\<workspace_hash>\`
- Linux/macOS： `$XDG_CACHE_HOME/codeloupe-mcp/index-v2/<workspace_hash>/` 或 `~/.cache/codeloupe-mcp/index-v2/<workspace_hash>/`
- 自定义根目录： `<codeloupe_mcp_INDEX_DIR>\index-v2\<workspace_hash>\`
- Tantivy 侧车： `<workspace_index_dir>\tantivy-content\`
工作区根目录是动态的：服务器使用客户端提供的`workspaceFolders`、`roots`、`rootUri`或`clientInfo.workspaceRoot`；如果没有提供，它会回落到进程当前目录，当该目录看起来像工作区根目录时。
### 发行
发行版通过两个渠道分发：
- **GitHub Releases**：semver标签，如`v1.0.0`，构建原生存档/安装程序，适用于x64/arm64上的macOS、Linux和Windows。
- **npm/npx**：`@ndhkaeru/codeloupe-mcp`发布了一个小的JavaScript启动器加上匹配的GitHub Release的原生二进制文件。
发行清单：
1. 更新`Cargo.toml`、`Cargo.lock`、`packages/npm/package.json`和`server.json`中的版本。
2. 运行`rust.yml`中的检查：格式、clippy、测试、审计、拒绝和拼写检查。
3. 推送`main`，然后检查GitHub Actions中的失败。
4. 推送semver标签，如`v1.0.0`。
5. 确认发布和npm发布工作流成功。
6. 测试`npx -y @ndhkaeru/codeloupe-mcp@<version>`。
### 开发
```bash
cargo fmt
cargo clippy --all-targets --all-features -- -D warnings
cargo test --release
```
### 许可证
Apache-2.0. 查看 [LICENSE](./LICENSE).
