codeloupe-mcp

codeloupe-mcp

一个模型上下文协议（MCP）服务，为编码 Agent 提供快速、本地优先的大型代码库访问能力。它使大模型能够检查文件、搜索文本、比较目录、读取符号，并通过有界工具响应应用结构化编辑，而不是将整个文件或仓库树倾倒到上下文中。

codeloupe-mcp 与 shell 工具的比较

此软件包提供用于探索仓库和编辑代码的 MCP 接口。

如果你使用的是编码 Agent，shell 命令仍然适用于简洁的构建／测试工作流。当模型需要在整个聊天会话中获取结构化、可重复且了解仓库情况的代码上下文时，codeloupe-mcp 最有用。

• Shell／CLI：最适用于确定性命令，例如 cargo test、npm run lint、项目脚本、一次性 rg 搜索，以及本身已经简洁的构建日志。
• MCP：最适用于能从工具架构、工作区感知的路径解析、有界输出、持久索引以及精准读取（例如符号主体、代码片段、浅层项目映射和目录差异）中受益的 Agent 循环。

当你希望 Agent 按需获取所需代码上下文时，请使用 codeloupe-mcp：例如某个行范围、符号主体、有界搜索结果、模糊文件匹配、工作区摘要或源目录比较。

主要功能

• 快速且轻量。通过 stdio 运行的本地 Rust 服务；无需外部索引服务、网络调用或遥测。
• 适合大模型的输出。工具会返回有界的 JSON／Markdown，专为 Agent 的上下文窗口设计。
• 仓库感知索引。使用 LMDB 存储路径元数据，并可选择为每个工作区建立 Tantivy 内容索引。
• 精准读取代码。读取指定行范围、代码片段、符号主体、导入项、导出项、调用图、定义和引用。
• 范围限定的搜索。支持字面量和正则表达式搜索，可按路径限定范围、使用包含／排除 glob、提供回退诊断，并设置大型仓库保护措施。
• 目录比较。比较两个源目录，并生成新增／删除／修改／重命名摘要及有界差异。
• 结构化编辑。创建、编辑、转换、删除、批量编辑和撤销文件，并提供可预测的成功／错误元数据。

要求

• 支持本地 stdio 服务的 MCP 客户端。
• 使用 npx 时，需要 Node.js 18 或更高版本。
• 使用已发布的 npm 软件包或原生发行版二进制文件时，无需 Rust 工具链。
• 仅从源代码构建时需要 Rust 1.98.1；rust-toolchain.toml 会通过 rustup 安装指定版本的工具链。

入门

首先，使用客户端安装 codeloupe-mcp 服务。

标准配置适用于大多数 MCP 客户端：

{
  "mcpServers": {
    "codeloupe-mcp": {
      "command": "npx",
      "args": ["-y", "@ndhkaeru/codeloupe-mcp@latest"]
    }
  }
}

你也可以使用 GitHub Releases 页面上的原生二进制文件：

{
  "mcpServers": {
    "codeloupe-mcp": {
      "command": "/absolute/path/to/codeloupe-mcp",
      "args": []
    }
  }
}

在 Windows 上原生安装时，将 command 指向 .exe 文件，例如 C:\path\to\codeloupe-mcp.exe。

"amp.mcpServers": {
  "codeloupe-mcp": {
    "command": "npx",
    "args": ["-y", "@ndhkaeru/codeloupe-mcp@latest"]
  }
}

amp mcp add codeloupe-mcp -- npx -y @ndhkaeru/codeloupe-mcp@latest

{
  "mcpServers": {
    "codeloupe-mcp": {
      "command": "npx",
      "args": ["-y", "@ndhkaeru/codeloupe-mcp@latest"]
    }
  }
}

claude mcp add codeloupe-mcp -- npx -y @ndhkaeru/codeloupe-mcp@latest

claude mcp add codeloupe-mcp -- /absolute/path/to/codeloupe-mcp

{
  "mcpServers": {
    "codeloupe-mcp": {
      "command": "npx",
      "args": ["-y", "@ndhkaeru/codeloupe-mcp@latest"]
    }
  }
}

{
  "mcpServers": {
    "codeloupe-mcp": {
      "command": "C:\\path\\to\\codeloupe-mcp.exe",
      "args": []
    }
  }
}

{
  "mcpServers": {
    "codeloupe-mcp": {
      "type": "stdio",
      "command": "npx",
      "timeout": 60,
      "args": ["-y", "@ndhkaeru/codeloupe-mcp@latest"],
      "disabled": false
    }
  }
}

codex mcp add codeloupe-mcp -- npx -y @ndhkaeru/codeloupe-mcp@latest

[mcp_servers.codeloupe-mcp]
command = "npx"
args = ["-y", "@ndhkaeru/codeloupe-mcp@latest"]

{
  "mcpServers": {
    "codeloupe-mcp": {
      "type": "local",
      "command": "npx",
      "tools": ["*"],
      "args": ["-y", "@ndhkaeru/codeloupe-mcp@latest"]
    }
  }
}

npx -y @ndhkaeru/codeloupe-mcp@latest

{
  "mcpServers": {
    "codeloupe-mcp": {
      "command": "npx",
      "args": ["-y", "@ndhkaeru/codeloupe-mcp@latest"]
    }
  }
}

droid mcp add codeloupe-mcp "npx -y @ndhkaeru/codeloupe-mcp@latest"

{
  "mcpServers": {
    "codeloupe-mcp": {
      "command": "npx",
      "args": ["-y", "@ndhkaeru/codeloupe-mcp@latest"]
    }
  }
}

npx -y @ndhkaeru/codeloupe-mcp@latest

{
  "mcpServers": {
    "codeloupe-mcp": {
      "command": "npx",
      "args": ["-y", "@ndhkaeru/codeloupe-mcp@latest"]
    }
  }
}

{
  "mcpServers": {
    "codeloupe-mcp": {
      "command": "npx",
      "args": ["-y", "@ndhkaeru/codeloupe-mcp@latest"]
    }
  }
}

{
  "mcpServers": {
    "codeloupe-mcp": {
      "command": "npx",
      "args": ["-y", "@ndhkaeru/codeloupe-mcp@latest"]
    }
  }
}

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "codeloupe-mcp": {
      "type": "local",
      "command": ["npx", "-y", "@ndhkaeru/codeloupe-mcp@latest"],
      "enabled": true
    }
  }
}

{
  "servers": {
    "codeloupe-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@ndhkaeru/codeloupe-mcp@latest"]
    }
  }
}

code --add-mcp '{"name":"codeloupe-mcp","command":"npx","args":["-y","@ndhkaeru/codeloupe-mcp@latest"]}'

{
  "mcpServers": {
    "codeloupe-mcp": {
      "command": "npx",
      "args": ["-y", "@ndhkaeru/codeloupe-mcp@latest"]
    }
  }
}

配置

codeloupe-mcp 接受可重复的 --workspace <path> / --workspace=<path> 参数，以及 MCP 服务进程中的环境变量。除非索引模式为 off，否则显式指定的命令行和环境变量工作区均获准进行索引。--help 和 --version 会立即输出结果，不会启动 stdio 服务；未知命令行选项会导致失败，而不会静默启动服务。

升级服务后，请重新连接或重启 MCP 客户端，使其获取当前的 tools/list 架构。Claude Code 等长时间运行的客户端可能会保留上一会话的工具参数，直到重新连接。

旧版 codeloupe_mcp_* 和 CODEBASE_MCP_* 名称仍受支持，以保持兼容性；大写的 CODELOUPE_MCP_* 名称优先。

在 Windows 上，npm 启动器会将原生二进制文件复制到 %LOCALAPPDATA%\codeloupe-mcp\runtime\<version>-<sha256 prefix>\ 并运行该副本。Windows 会锁定正在运行的可执行文件，因此，直接从 node_modules 运行会导致 npx -y @ndhkaeru/codeloupe-mcp@latest 升级失败并出现 EBUSY，或者在另一个 MCP 会话仍在使用该服务时遗留 npm 临时目录。后续启动时会删除已闲置一天的副本。通过 1.1.1 或更早版本的启动器启动的服务仍从 node_modules 运行；如果升级报告 EBUSY，请停止这些 codeloupe-mcp.exe 进程一次，然后重新连接。

工作区来源按以下顺序处理：可重复指定的 CLI 参数、显式工作区环境变量、MCP 客户端根目录（workspaceFolders、roots、rootUri 或 clientInfo.workspaceRoot）、类似项目的进程当前目录，最后是从工具路径推断出的工作区根目录。在 ask 模式下，只有 CLI/环境变量根目录以及已记住的 workspace_index(action="enable") 决策会获准建立索引；客户端根目录、当前工作目录和工具路径仍只是候选项。auto 会在相同的受保护路径、扫描和磁盘预算限制下为符合条件的候选项建立索引。off 会禁用索引和建议。相对工具路径会依次优先使用当前活动工作区上下文、活动索引工作区、从当前工作目录发现的工作区、当前工作目录本身、其他已配置工作区，最后是已加载的索引工作区。 写入根目录是规范化后的 MCP 客户端根目录和显式 --workspace／工作区环境根目录；如果未配置根目录，则使用类似项目的进程当前工作目录，此外还包括 CODELOUPE_MCP_WRITE_ROOTS。在写入根目录内写入不会产生位置警告；其他目标则会收到风险警告，详见工具。发现祖先仓库根目录可能会扩展索引／搜索上下文，但绝不会将写入根目录扩展到声明的根目录之外。workspace_index(action="enable") 仅授予索引权限，不会添加写入根目录。在 .git 下写入，以及通过规范化的联接／符号链接逃逸出写入根目录，均属于严重风险：在调用方重试并设置 acknowledge_risk=true 之前，会通过 risk_confirmation_required 停止操作，不进行任何文件系统更改。

自定义索引目录示例：

{
  "mcpServers": {
    "codeloupe-mcp": {
      "command": "npx",
      "args": ["-y", "@ndhkaeru/codeloupe-mcp@latest"],
      "env": {
        "CODELOUPE_MCP_INDEX_DIR": "/path/to/cache"
      }
    }
  }
}

工具

工具按用途分组。每个响应都采用标准 MCP content 数组结构，并限制输出大小，以适应 Agent 上下文。

服务会协商支持的 MCP 协议版本（2024-11-05、2025-03-26、2025-06-18 和 2025-11-25），对 ping 返回空对象，并且绝不响应通知。通知形式的 tools/call 消息会被忽略，不会执行。notifications/cancelled 会抑制匹配的活动响应，并传播协作式取消；多文件扫描工具会报告协作式进度，并在取消时提前停止。作为服务扩展，请求形式的 tools/call 可将 params.timeout_seconds 设为 60 到 600 之间的整数；超出范围或非整数的值会返回 JSON-RPC -32602，而不是被静默调整。超时响应是结构化 JSON，包含已用时间、观察到的扫描进度、范围更窄的候选路径，以及有条件提供的 index_advice。

file_hash 和 read_file_range 会通过有界内存流式 I/O 计算完整文件的 SHA-256 摘要。edit_file、delete_file 以及 edit_files.files 中的每个条目都可以将该摘要指定为 expected_hash；过时或格式错误的前置条件会在修改前被拒绝，单文件工具还会在写入或删除前立即重新检查摘要。成功的编辑响应会包含修改前后的摘要。

成功的写入响应内容精简，不包含多余的 success、message 和默认值状态字段。如果操作后文件仍存在，文件修改会返回 path、history_entry_id 和 sha256_after，并附带 replacements、bytes_removed 或 undone_entry_id 等操作专属字段；仅在发生异常情况时才会报告这些情况。edit_files 会对每个已更改文件应用相同的约定，而不会重复返回默认编码、验证和历史记录元数据。

写入授权使用 risk_aware 范围。在明确声明的 MCP/CLI/环境根目录内写入时，不会发出位置警告。其他目标会根据检测到的最高风险收到一条简短警告：位于已知写入根目录之外为 low；位于推断出的代码仓库其他位置为 medium；匹配已配置的敏感模式或检测到符号链接/连接点目标为 high；涉及 .git、敏感的用户主目录凭据/配置文件位置、受保护的操作系统目录，或规范化路径逃逸出声明的根目录/代码仓库为 critical。低、中、高风险写入会立即执行。critical 风险调用会在修改前返回 risk_confirmation_required；使用 acknowledge_risk=true 重试同一调用即可继续，同时保留警告。敏感的哈希不匹配响应不会暴露 actual_hash。声明根目录之外的历史记录条目会包含 outside_declared: true；workspace_index 仅控制索引，不会声明写入根目录。

validate_json 会通过流式处理验证语法，不会将文档完整载入内存。它只接受一个 UTF-8 文件路径或内嵌 JSON 字符串，并会在输入无效时报告解析器的行/列详细信息；它不执行 JSON Schema 验证。

写入历史记录存储在内存中，仅对正在运行的服务进程有效。最多保留 200 条记录和 256 MiB 的快照字节数，并优先淘汰最早的记录。list_history 仅返回元数据；如果路径当前内容或规范化位置与记录的操作后快照不再匹配，undo_change 会拒绝覆盖该路径。服务重启后，历史记录不会保留。

read_file_range 支持按行读取、使用 tail 读取最后 N 行、使用有界的 start_byte 窗口读取超长行，以及通过 RFC 6901 流式选择 json_pointer。文本响应会移除开头的 BOM，将 CRLF 和经典 CR 行结束符规范化为 LF，报告 bom/is_binary，并且绝不会返回包含 NUL 的二进制内容。如果未指定 max_bytes，按行、tail 和 start_byte 读取默认使用 64 KiB 输出窗口；首行超出窗口时，会返回该行前缀，并附带 line_truncated: true 和 next_start_byte。json_pointer 默认使用 1 MiB 的序列化值预算。read_snippets 接受相同的单次请求选择器，并返回基于行或字节的续读位置。

符号查询同时接受 Class.method 和 Class::method，也支持更深层的限定名称。get_symbols 会返回 qualified_name 和 start_line；read_symbol_body、get_call_graph 以及 compare_symbols 的每一侧都接受可选的 line 选择器。若非限定查询匹配到多个 AST 结果，则会返回 ambiguous: true 和 candidates，而不是静默选择第一个匹配项。若任一侧存在歧义，compare_symbols 会省略 same_content 和 unified_diff。

对于支持的语言，find_definition 使用 Tree-sitter，并区分符号名称的大小写；这些结果会标记为 resolution: "ast"。对于不受支持的代码扩展名，则使用声明正则表达式备用方法，并标记为 resolution: "heuristic"。find_references 执行令牌匹配，而非绑定或类型解析；对于 Tree-sitter 支持的文件，会返回 match_kind: "code" | "comment" | "string" 和 classification: "ast"，将声明名称匹配项标记为 is_definition: true，普通引用则不添加标记。不受支持的扩展名会返回 match_kind: "unknown" 和 classification: "text_fallback"。

find_definition 和 find_references 会在顶层保留结果数据及 complete/限制元数据。扫描计数器、路径索引/文件系统策略、备用方法计数、跳过文件详情和取消状态，仅会在结果不完整、筛选器提示结果为零或设置 verbose=true 时出现在 diagnostics 下。可推断的默认结果元数据会省略；例如，普通 AST 代码引用不会重复包含 classification: "ast"、match_kind: "code" 或 line_truncated: false。 代码智能输出统一使用 path。单文件工具返回一个规范化路径，而 find_definition 和 find_references 返回共享的 root，以及匹配项和跳过文件详情的相对路径。对于含义不明确的 get_call_graph 候选项，会省略重复路径，因为顶层的 path 适用于所有候选项。

compare_directories 默认返回仅含清单的 JSON 结果；需要统一差异时，设置 include_content_diff=true。compare_symbols 返回统一差异和符号元数据，不会在 left 和 right 中重复包含两个完整的符号正文。

字节大小输出字段统一使用 _bytes 后缀：单个条目使用 size_bytes，目录比较使用 left_size_bytes/right_size_bytes。

有界集合输出使用 complete、limit_reached 和 limit_reason。有界嵌套列表使用 entries_complete、details_complete 或 candidates_complete 等名称；只有实际缩短了返回的文本或字节内容时，才使用 truncated。

支持的语言

基于 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、Python、Go、Java 和 C#。Python 导出遵循公共名称约定（顶层声明名称不以下划线 _ 开头）；Go 导出遵循导出标识符首字母大写的规则。文件、搜索和工作区工具适用于任何语言的文本文件。

共享文件限制

文件内容限制集中定义在 src/limits.rs 中；当这些限制会影响结果时，架构或响应中会报告相关信息。

会跳过超大文件的扫描工具会返回有界的路径、大小和限制详情，并在需要时附上省略详情的数量。

大型仓库指南

• 将 paths 限定在尽可能小且有用的子树中。
• 尽可能优先使用字面量 text_search，以便 Tantivy 缩小候选文件范围。
• 使用具体的基本文件名或路径标记调用 fuzzy_find。
• 保持 project_map 的深度较浅，例如 max_depth <= 2。
• 使用递归排除项，例如 third_party/**、node_modules/**、target/**、dist/** 和 out/**。
• 搜索结果出来后，使用 read_snippets，而不是读取整个文件。

text_search、compare_directories 和内容索引使用相同的生成目录／供应商目录策略，包括 build、dist、obj、out、target、node_modules、vendor 和 third_party。只有在已识别的 .NET/Java 工作区中，bin 才会被视为构建输出，因此 Node、Ruby 等项目中作为源代码目录的 bin/ 仍可搜索。若直接将 text_search 的范围指定为排除目录，则会绕过这些默认设置。

索引存储

服务会为每个经批准的规范工作区根目录保留一个索引。嵌套的客户端根目录可以共享推断出的祖先索引／搜索工作区；发现时，优先选择带有 VCS 标记（.git、.hg 或 .svn）的祖先，而不是带有嵌套语言清单的目录。推断出的祖先不会成为声明的根目录；在该仓库其他位置写入时，会收到上文所述的中风险警告。索引批准决定存储在可读的 index-v2/workspaces.json 中；已启用的工作区会在不同会话间重新加载，而拒绝建议后，30 天内不会再收到建议。

• 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\
• 上次使用记录辅助文件：<workspace_index_dir>\last-used

<workspace_hash> 是规范化规范根目录的稳定 FNV-1a 哈希，因此更改 Rust 工具链不会导致所有缓存目录都重命名。通过 meta.json 找到匹配的 1.0 之前版本缓存目录时，会在打开前将其重命名为稳定哈希。

启动时，索引 GC 会在 7 天宽限期后移除工作区已不存在的索引，移除 90 天未使用的索引，并按最近最少使用顺序将总容量限制在 2 GiB。新建索引前也会检查相同的总容量和可用空间预算。元数据扫描会在达到配置的条目数或时间预算后停止，并持久化记录 too_large，但不会创建工作区索引目录。已加载或被其他进程锁定的索引绝不会被删除。Tantivy 存储可搜索字段和文件元数据，但不存储文件内容或路径词元载荷。

工作区根目录是动态的：先批准显式 CLI／环境变量根目录；客户端根目录、类似项目的进程当前目录，以及从工具路径推断出的工作区根目录都会更新活动上下文。索引会在后台加载，使初始化和无关请求保持响应；运行时正在加载时，工具会回退到有界文件系统访问。已加载的运行时使用内存 LRU 预算，逐出后可以从磁盘索引重新打开。可识别的清单包括 Rust、Node、Python、Go、Java/Gradle、Bazel、.NET（*.sln、*.slnx、global.json、Directory.Build.props）、CMake、PHP Composer、Ruby、Elixir 和 Scala/SBT 项目。没有可识别工作区标记的工具路径仍可通过有界文件系统访问使用，但不会收到索引建议。即使没有标记，显式客户端根目录仍是有效的活动上下文；是否建立索引取决于 CODELOUPE_MCP_INDEX_MODE 或已保存的批准决定。

发布

发布通过以下两个渠道分发：

• GitHub Releases：例如 v1.0.0 这样的 semver 标签会在 macOS、Linux 和 Windows 上为 x64/arm64 构建原生归档／安装程序。Linux 归档使用静态 musl 目标，因此不需要较新的 glibc，并可在 Alpine 等基于 musl 的发行版上运行。
• npm/npx：@ndhkaeru/codeloupe-mcp 是一个小型 JavaScript 启动器。npm 会安装一个包含对应原生二进制文件的操作系统／CPU 专用可选包，而不是下载全部六个平台的包。

发布检查清单：

1. 更新 Cargo.toml、Cargo.lock、packages/npm/package.json、每个 packages/npm-platforms/*/package.json 以及 server.json 中的版本。
2. 运行 rust.yml 中的检查：格式检查、clippy、测试、审计、deny 和 typos。
3. 推送 main，然后检查 GitHub Actions 是否有失败。
4. 推送 semver 标签，例如 v1.0.0。
5. 确认发布资源、全部六个平台的 npm 包以及启动器 npm 包均已成功发布。
6. 对 npx -y @ndhkaeru/codeloupe-mcp@<version> 进行冒烟测试。

开发

cargo fmt
cargo clippy --all-targets --all-features -- -D warnings
cargo test --release

许可证

Apache-2.0。参见 LICENSE。