codebase-context-mcp

codebase-context-mcp

适用于所有平台的代码库索引与搜索 MCP 服务——包括 Raspberry Pi 和 Apple Silicon 等大多数替代方案无法运行的 ARM64 设备。

问题

热门的代码库索引 MCP 服务（例如 @zilliz/claude-context-mcp）依赖原生 C++ 绑定（tree-sitter、faiss-node），而这些绑定只为 x86_64 提供预编译二进制文件。如果你使用 ARM64 设备——例如 Raspberry Pi、Apple Silicon Mac、AWS Graviton 或其他 arm64 主机——npm install 会因缺少预编译文件且没有备用方案而失败。除非自行交叉编译原生模块，否则别无他法。

解决方案

此软件包用 WASM 等效方案替换所有原生依赖。tree-sitter 解析器以 WebAssembly 运行，搜索使用纯 JS BM25 实现，索引则以普通 JSON 格式存储。没有原生绑定，意味着在 任何架构上首次运行 npm install 都能成功：ARM64、x86_64、macOS、Linux 和 Windows。

可直接替换使用——通过标准 MCP stdio 传输提供相同的核心工具（索引、搜索、大纲、摘要）。

工具

工具	描述
index_codebase	将目录解析为符号／代码块，并缓存为 JSON
search_symbols	按名称或模式查找函数、类和类型
search_code	在已索引文件中进行 BM25 全文搜索
get_file_outline	文件结构：函数、类、导入项和导出项及其行号
get_project_summary	技术栈、按语言统计的文件数量、目录结构

支持的语言

TypeScript、TSX、JavaScript、Python、C#、VB.NET、XML、CSS、JSON

安装

Claude Code（推荐）

claude mcp add codebase-context -s user -- npx codebase-context-mcp

或从本地克隆版本安装：

git clone https://github.com/Jhackman2019/codebase-context-mcp.git
cd codebase-context-mcp
npm install && npm run build
claude mcp add codebase-context -s user -- node /path/to/codebase-context-mcp/dist/index.js

MCP 设置（JSON）

{
  "mcpServers": {
    "codebase-context": {
      "command": "npx",
      "args": ["codebase-context-mcp"]
    }
  }
}

工作原理

• 解析： web-tree-sitter（WASM）——与原生 tree-sitter 具有相同的 AST 质量，可在任何架构上运行
• 搜索： BM25 文本排名（纯 JS）＋符号名称匹配
• 存储： JSON 文件索引，路径为 ~/.codebase-context-mcp/<project-hash>.json
• 传输： 通过 @modelcontextprotocol/sdk 使用 MCP stdio
• 增量处理： 重新索引时跳过内容哈希未变化的文件

安全限制

限制	值
最大文件数	20,000
最大文件大小	512KB
默认忽略项	node_modules、.git、dist、build、.venv、二进制文件、锁定文件
.gitignore	遵循（根目录级别）

开发

npm install
npm run build    # Build with tsup
npm run dev      # Watch mode
npm start        # Run the server

许可证

MIT