🔍 code-search-mcp

Zero-daemon 本地语义代码搜索 MCP 服务器，由 LanceDB 和进程内 ONNX 嵌入驱动。
别再逐字 grep 了。让您的 AI 编码助手按照含义搜索代码库。

开箱即用，支持 Claude Code、Gemini CLI、Antigravity (agy) 和 Cursor，适用 macOS、Windows 和 Linux。

☕️ 想象一个咖啡店应用

想象你正在为一家繁忙的本地咖啡店构建软件。

在你的代码库中，有一个文件处理了这样一个场景：当顾客额外点了一份燕麦拿铁，并且还能享受早间折扣时，会发生什么：

// Apply a 15% promotional deduction if the customer visits before 9 AM
export function calculateEarlyBirdReward(bill: OrderSummary): number {
  if (bill.orderHour < 9) {
    return bill.subtotal * 0.85;
  }
  return bill.subtotal;
}

现在想象你打开 AI 编码助手（如 Claude Code、Cursor 或 Gemini CLI）并问道：

“早间饮品折扣是在哪里计算的？”

如果你手上的工具只依赖传统文本搜索（如 grep），它会去搜索精确的单词 "discount"。

• 它有没有找到 calculateEarlyBirdReward？没有。

• 为什么？因为代码使用的是 promotional deduction 和 EarlyBirdReward，但从未出现过 "discount" 这个精确单词。

这就是语义搜索改变一切的地方。

Related MCP server: claude-context-local

🧠 什么是语义搜索（通俗解释）？

传统搜索查找精确的字母和单词。

语义搜索查找的是你话语背后的*含义。

工作原理：语义的地图

1. 用数字代替字母：AI 模型将一段文本（或代码）转换成一个数字列表，这些数字称为嵌入（embedding）（或向量）。

2. 地图上的坐标：把这些数字想象成一张巨大的“人类概念地图”上的 GPS 坐标。

   • "discount" 和 "promotional deduction" 在地图上紧挨在一起。

   • "espresso shot" 和 "latte" 紧挨在一起。

   • "database migration" 则位于地图另一侧远处。

3. 找到最近的邻居：当你用自然语言提问时，搜索引擎把你的问题转换为坐标，然后直接找到地图上距离它最近的代码片段。

                  [ Map of Meaning ]

   ☕️ "morning drink discount"   📍 (Your Question)
              │ (Close match!)
              ▼
   🏷 "calculateEarlyBirdReward" 📍 (Your Code)
   
   ─────────────────────────────────────────────
   
   🗄 "sql database migration"   📍 (Far Away - Ignored)

🚀 为什么语义搜索对 AI 编程是一种颠覆

当 AI 编码助手在包含数千个文件的大型代码库上运行时，它们不可能在每个 prompt 上读取每一个文件——这实在太慢，会消耗太多 token。

相反，AI 需要的是立刻找到最相关的 2 或 3 个文件。

在现实项目中，你的代码库包含了大量丰富信息：

• Markdown 文档（.md）：架构决策记录、API 指南、新手文档。

• 代码注释：解释业务规则存在的原因，例如 // Deduct beans from bean hopper inventory。

• 函数和变量名：这些命名模式在不同库之间可能各不相同。

语义搜索会将你的自然语言想法直接连接到这些 markdown 文档、注释和代码片段——即使你不记得确切的函数名，也能找到。

🛠 我们构建了什么：code-search-mcp

许多面向开发者的现有语义搜索工具都要求繁杂的环境配置：

• 安装 Python 3、虚拟环境和 pip。

• 运行一个监听网络端口的外部后台数据库服务器（如 ChromaDB）。

• 在系统上配置启动守护进程（Mac 上的 LaunchAgents、Windows 上的 Task Scheduler），这些进程会在开机时消耗电池。

• 添加复杂的 Git hooks（pre-commit），如果数据库服务器离线，可能会阻塞你的工作。

我们想要完全不同的方案：零配置、零外部守护进程、在任何项目中都能立刻运行。

为此我们构建了 code-search-mcp —— 一个面向 Node.js 的独立、跨平台 模型上下文协议（MCP） 服务器。

┌─────────────────────────────────────────────────────────────┐
│                       AI Client                             │
│       (Claude Code / Gemini CLI / Antigravity / Cursor)     │
└──────────────────────────────┬──────────────────────────────┘
                               │ MCP Protocol (JSON-RPC over stdio)
┌──────────────────────────────▼──────────────────────────────┐
│                      code-search-mcp                        │
│                                                             │
│  ┌──────────────────┐  ┌──────────────────┐  ┌───────────┐  │
│  │   Scanner &      │  │  EmbeddingEngine │  │  Watcher  │  │
│  │ Layered Ignores  │  │  (all-MiniLM-L6) │  │(chokidar) │  │
│  └────────┬─────────┘  └────────┬─────────┘  └─────┬─────┘  │
│           │                     │                  │        │
│           └───────────┬─────────┴──────────────────┘        │
│                       ▼                                     │
│              VectorStore (LanceDB)                          │
│        node_modules/.cache/code-search/                     │
└─────────────────────────────────────────────────────────────┘

⚙️ 背后的技术

🔍 内部实现原理

1. 它如何知道何时开始索引？

当你的 AI 助手启动时（例如启动 Claude Code、Antigravity 或 Gemini CLI），它会通过标准输入输出（stdio）连接到 code-search-mcp。

• MCP 服务器在 不到15毫秒 内连接。

• 后台工作进程开始扫描项目文件，不会阻塞你的对话会话。

2. 索引未完成时可以搜索吗？（“中途索引”的超能力）

可以！如果在打开项目 2 秒后就提出问题， code-search-mcp 不会阻碍或挂起。

它只搜索当前已经索引到的文件，并提供一个实时进度头部：

⚠️ [Index status: INDEXING (35% complete - 2,100/6,000 files indexed)]
Results from currently indexed files:

### Match 1: src/drinks/espresso.ts (Lines 12-30) [Score: 54.2%]

3. 初次运行需要耐心——过程只有一次！⏳

对于包含 5,000+ 文件的大型代码仓库，首次索引扫描需要几分钟，因为本地 AI 模型是在你的机器上首次为每个代码片段生成嵌入。

好消息如下：

• 永远只付这一次国钱： 生成的向量数据库会永久存储在 node_modules/.cache/code-search/lancedb/。

• 后续启动瞬间完成： 在未来每次会话或编辑器重启时，服务器都会在 <15ms 内连接，无需重新索引。

• 增量实时更新： 你每天写代码时，监听器只更新你刚修改过的一个文件，保存后约 ~150ms 内完成更新。

• 等待零等待： 你可以立刻提问和搜索——助手会搜索已经在后台索引到的内容。

4. 索引存储在哪个位置？

默认情况下，数据库存储在： 📁 node_modules/.cache/code-search/lancedb/

为什么选择 node_modules/.cache？

• 在 100% 的项目中，node_modules 都已经在 Git 中被忽略。

• 零 Git 噪音：仓库中不会出现任何未跟踪的文件夹或不必要的 diff 内容。

• （如果项目没有 node_modules，则会自动回退到 .code-search/）。

5. 切换 Git 分支时会发生什么？🔀

当你执行 git checkout、git switch 或 git pull 时：

1. 实时监听检测：Git 更新磁盘上的文件，内置的 chokidar 监听器会实时发现新增、修改或删除的文件。

2. 快速差异性重新扫描：只对两个分支之间发生变化的具体修改的文件重新索引（耗时 1–2 秒，而不是几十秒）。

3. 自动清理：之前分支留下的已删除文件或旧代码块会自动从 LanceDB 中移除。

4. 手动同步：如果在一个大型合并后想强制完整重建，只需告诉助手：“执行 code_search_reindex，带 force: true”。

⚙️ 如何管理设置并忽略更多文件

默认情况下，code-search-mcp 会默认忽略二进制文件（如 .png、.mp4、.zip）、构建输出（dist/、build/）、锁文件以及任何下载超过 500 KB 的文件，同时也会尊重你已有的 .gitignore。

如果你想自定义设置或为你的项目添加额外的忽略规则，有两个简单的方法：

选项 1：创建 .codesearchignore 文件（快速简便）

在你的项目根目录创建一个 .codesearchignore 文件，遵循标准的 gitignore 语法：

# Ignore mock data and test fixtures
tests/fixtures/**
src/mocks/**

# Ignore auto-generated files
src/models/*.generated.ts
locales/**

选项 2：创建 .codesearchrc.json 文件（高级设置）

在你的项目根目录创建 .codesearchrc.json 文件，用于控制索引行为、批处理大小和文件大小限制：

{
  "maxFileSizeKb": 300,
  "batchSize": 50,
  "customExcludes": [
    "legacy_vendor/**",
    "docs/archive/**"
  ],
  "supportedExtensions": [
    ".ts", ".tsx", ".js", ".vue", ".py", ".md", ".json"
  ]
}

📦 如何安装该工具

你可以使用以下任意一种方法安装并运行该工具：

步骤 1：选择安装方式

方法 A：通过 npx 直接从 GitHub 运行（无需 npm 发布）

任何 AI 客户端都可以直接从你的 GitHub 仓库按需运行它：

npx -y github:your-username/code-search-mcp

(Node 会自动下载仓库、构建 bundle，并执行 MCP 服务器)

方法 B：从 npm Registry 安装（发布后）

如果把该包发布到 npm ：

npx -y code-search-mcp
# or global install:
npm install -g code-search-mcp

方法 C：本地开发 / 链接（本地启动速度最快）

如果直接从本地源码目录运行：

cd /path/to/code-search-mcp
npm install
npm run build
npm link

现在， code-search-mcp 已经在系统中注册为一个全局命令了！

步骤 2：连接到你的 AI 客户端

1. Claude Code

# If running via GitHub:
claude mcp add code-search -s user -- npx -y github:your-username/code-search-mcp

# If running locally (linked):
claude mcp add code-search -s user -- code-search-mcp

2. Antigravity CLI (agy)

在终端中运行这一行命令：

mkdir -p ~/.gemini/config/plugins/code-search && cat << 'EOF' > ~/.gemini/config/plugins/code-search/plugin.json
{ "name": "code-search" }
EOF
cat << 'EOF' > ~/.gemini/config/plugins/code-search/mcp_config.json
{
  "mcpServers": {
    "code-search": {
      "command": "npx",
      "args": ["-y", "github:your-username/code-search-mcp"]
    }
  }
}
EOF

3. Gemini CLI

添加到你的 ~/.gemini/settings.json 中：

{
  "mcpServers": {
    "code-search": {
      "command": "npx",
      "args": ["-y", "github:your-username/code-search-mcp"],
      "trust": true
    }
  }
}

4. Cursor / Claude Desktop

添加到你的 .cursor/mcp.json 中：

{
  "mcpServers": {
    "code-search": {
      "command": "npx",
      "args": ["-y", "github:your-username/code-search-mcp", "--path", "${workspaceFolder}"]
    }
  }
}

🤖 AI 助手指南与工具参考

如果你是一个正在阅读这个仓库的 AI 助手（Claude Code、Gemini CLI、Cursor、Antigravity 或 Windsurf），这里是如何使用 code-search-mcp 所提供的 MCP 工具的快速入门：

🛠️ 可用的 MCP 工具

🧭 工具决策矩阵：何时使用哪个工具

                       ┌───────────────────────────────────────────────┐
                       │ What are you looking for in the codebase?     │
                       └───────────────────────┬───────────────────────┘
                                               │
           ┌───────────────────────────────────┼───────────────────────────────────┐
           ▼                                   ▼                                   ▼
┌─────────────────────────┐         ┌─────────────────────────┐         ┌─────────────────────────┐
│ Concept / Feature /     │         │ Known Symbol / Callers  │         │ Exact Literal String /  │
│ Business Logic Intent   │         │ & Blast Radius Analysis │         │ Error Code / CSS Class  │
│ (Natural Language)      │         │ (Exact identifier)      │         │ (Exact text match)      │
└──────────┬──────────────┘         └──────────┬──────────────┘         └──────────┬──────────────┘
           ▼                                   ▼                                   ▼
┌─────────────────────────┐         ┌─────────────────────────┐         ┌─────────────────────────┐
│ 🔍 USE: code_search     │         │ 🌳 USE: codegraph       │         │ 🔎 USE: grep_search     │
│ • "where is payment..." │         │ • codegraph_explore     │         │ • "ERR_INVALID_AUTH"    │
│ • "tax calculation..."  │         │ • callers / callees     │         │ • ".btn-primary-blue"   │
└─────────────────────────┘         └─────────────────────────┘         └─────────────────────────┘

💡 给 AI 代理的专业提示

1. 对纯实现逻辑使用 codeOnly: true： 如果你要查找纯 TypeScript/JavaScript 计算公式，并排除 markdown 文档或技能指南，请始终传入 codeOnly: true。

2. 使用 pathFilter 把范围缩小到子系统： 如果用户问“计费模块中的结账是怎么运行的？”，请传入 pathFilter: "src/billing"。

3. 使用带行号的结果直接做代码编辑： 代码片段会以从 1 开始的行号返回（直接看原文示例 14: export function calculateUseApI() 这一行即可。等等），你可以直接将这些行区间传给 replace_file_content 或 view_file，无需猜测。

4. 容错性极强： 你可以直接用最自然的词查询 —— 引擎会在 <1ms 内自动处理复数（stemming）和拼写错误（Levenshtein correction）。

🤝 终极 AI 组合：为什么应同时安装 code-search 与 codegraph

现代 AI 编码助手在拥有两个互补工具时表现最佳：语义搜索（code-search-mcp）和 AST 代码图（codegraph）。

                   ┌─────────────────────────────────────────────────────────┐
                   │  User: "Where is subscription discount handled?"        │
                   └────────────────────────────┬────────────────────────────┘
                                                │
                                                ▼
                   ┌─────────────────────────────────────────────────────────┐
                   │ 1. SEMANTIC SEARCH (code_search)                        │
                   │ • Understands intent, concepts, and natural language     │
                   │ • Finds: subscription-billing.engine.ts (via JSDoc)     │
                   └────────────────────────────┬────────────────────────────┘
                                                │
                                                ▼
                   ┌─────────────────────────────────────────────────────────┐
                   │ 2. AST CODE GRAPH (codegraph_explore)                   │
                   │ • Understands syntax trees, callers, and blast radius   │
                   │ • Traces: callers into legacy LegacyOrderProcessor.js   │
                   │ • Discovers: unit tests (subscription-billing.spec.ts)  │
                   └─────────────────────────────────────────────────────────┘

为什么只用其中一个工具是不够的：

实际案例研究：现代开发 vs 旧版单体应用

在真实的企业级代码库中：

1. **现代引擎（subscription-billing.engine.ts）**有明确的命名（calculateSubscriptionDiscount）和丰富的 JSDoc 注释。使用 code_search 在毫秒级就能得到 >55% 的相似度匹配。

2. **历史旧系统核心（LegacyOrderProcessor.js）**是一个 2,000 行的文件，使用旧术语（getDiscountedTotal、applyOldDeduction）或有拼写错误。仅用语义搜索可能得分不那么高。

3. 协同效应：当 code_search 锁定 subscription-billing.engine.ts 后，codegraph_explore 立即可以追踪所有调用者，直接进入 LegacyOrderProcessor.js，并在覆盖到对应测试的情况下同步风格圈出会影响多少 —— 全程毫无猜测！

推荐的双重配置

将这两个工具添加到你的 MCP 配置文件中：

{
  "mcpServers": {
    "code-search": {
      "command": "node",
      "args": ["/path/to/code-search-mcp/dist/bin/cli.js"]
    },
    "codegraph": {
      "command": "codegraph",
      "args": ["mcp"]
    }
  }
}

📋 推荐的助手规则

为了让你的 AI 助手自动选择 code_search 和 codegraph，请将这条规则添加到项目的指令文件（CLAUDE.md、GEMINI.md、.github/copilot-instructions.md 或 .cursorrules）中：

## Code Navigation & Search

1. **CodeGraph (`codegraph_explore`)**: Call FIRST when exploring known symbols, tracking call paths, finding usages, or analyzing blast radius (callers + covering tests).
2. **Semantic Search (`code_search`)**: Call FIRST when looking for features, domain behaviors, or business logic described in natural language (e.g. "where is discount calculated", "checkout suggestions formatted").

🧪 如何确认它正常工作

安装完成后，你可以通过下面三种快速检查来验证 code-search-mcp 是否正常工作：

检查1：让助手查询状态

在任何对话中（Claude Code、Cursor、Gemini CLI），直接问：

"检查一下 code_search_status"

预期输出应为：

Index Status: READY (or INDEXING)
Progress: 100%
Files: 6,070 / 6,070 indexed
Chunks: 8,204 code chunks in LanceDB

检查2：用自然语言试试代码搜索

询问你的 AI 助手：

"用 code_search 查找客户折扣规则或优惠奖励是怎么处理的"

预期输出为：

### Match 1: src/rewards/early-bird.ts (Lines 1-18) [Score: 56.4%]

助手会在瞬间返回带精确行号和相似度分数的相关代码片段。

检查3：测试实时监听文件

1. 在你的项目中新建一个测试文件（例如 src/drinks/secret-recipe.ts），文件里写一段独一无二的注释：

   // Caramel macchiato secret syrup blend formula
   export const caramelBlend = 42;

2. 保存这个文件。

3. 立即询问你的 AI 助手：

   "用 code_search 查找某种秘密配方中的糖浆混合比例"

4. 这个新文件将在 耗时低于 1 秒 内被找到并返回 —— 无需手动重建索引，也无需重启服务！

检查4：运行自动化测试套件（可选）

使用源码开发时，可以运行：

npm test

所有 31 个单元 + 集成测试 都会执行并通过，从而验证 MCP 协议握手、ONNX 向量生成、LanceDB 存储、文件监听生命周期、分词处理和拼写纠错等功能。

🛠️ 我们实际遇到的问题，以及如何修复它（用大白话讲）

在构建一个能同时为人和 AI 编码代理提供流畅使用的搜索工具时，我们确实踩了不少坑。以下是我们遇到的真实问题和针对性的解决办法：

1. 🔤 单复数和词尾变化的坑（“marks” vs “Markers”）

• 遇到的问题：当用户输入 "how chart iq uses marks on the chart" 时，他们使用了复数 "marks"，但真实代码里类名却是 CIQ.Marker 或 markersSample。用传统的 LIKE '%marks%' 查询，因为多了一个 "s"，完全匹配不到 Marker 。

• 我们怎么解决：写了一个 轻量级的词干提取器。不匹配任何词库，而是自动匹配常见的复数后缀、进行词形归一（例如 -s、-ing、-ed）。当搜索 "marks" 时，实际上帮你搜 "mark"，这样马上就能命中 CIQ.Marker、markAxis 这些代码符号，而且这一步几乎零开销。

2. ✍️ 拼写错误问题（例如输成 calcualte 或 mrgin）

• 问题：你在聊天里打字快了，很容易出现拼写错误，比如把 margin 打成 mrgin，或把 calculate 打成 calcualte。一旦出现拼写错误，传统的关键词搜索就会 100% 失败。

• 我们怎么修复：我们构建了一个带有 内存索引的拼写纠错器（Levenshtein 编辑距离）。在索引文件时，引擎会收集代码中真实的变量名、类名等形成词汇表。当你发来一个带拼写错误的词时，它会在 <1ms 内对照词汇表进行纠正，然后继续检索。

3. 🤖 对 AI 代理友好：进每行加行号

• 问题：搜索结果的顶部有行号，但代码块内部却没有。当 AI 代理（Claude Code、Gemini CLI 等）想要编辑或者引用某一行时，必须先自己人工数行号或猜测行号位置。

• 解决方案：现在每一个返回的代码片段，每一行都会自动带上真实的 1 基准行号（例如 14: export function ...）。这样 AI 编程代理可以直接使用精确的行号就可以传入对应的编辑工具，不需要再读文件做额外计算。

4. 📚 减少代码搜索时文档的“噪音”

• 问题：当用宽泛的意图搜索具体逻辑（比如“怎么格式化金额”）时，一些很大的 markdown 技能文档或架构指南反而会比真正的 .ts 工具函数排名更高，因为文档里使用了大量正常句子。

• 我们怎么解决：

  1. 添加了 codeOnly: true（忽略 markdown/文档）、pathFilter: "src/..." 与 language 等过滤项。

  2. 调低了静态 JSON 字典文件的权重，让核心 TypeScript/JavaScript 逻辑总是优先排前。

5. 🔁 结果“刷屏”——一个超大文件同时占满很多位置

• 问题：搜索一个超大型单文件（比如有 3,000 行、多处匹配）时，它往往会霸占全部前 10 个返回结果，让其他更小、更清晰的辅助文件排不上。

• 解决方式：我们加入了 文件粒度的多样性限制。同一个文件最多返回 2 个评分最高的片段，这样返回结果会来自整个代码库的不同文件，而不是被某个 600 行的大文件全占满。

6. ⚡ 快速保存时的数据库🔒锁冲突

• 问题：切换分支或者立刻改多个文件时，同时多次写入 LanceDB 可能触发并发版本崩溃。

• 解决办法：增加了一个异步写入队列和指数退避重试机制。一旦写入冲突，它会自动等待一段毫秒级别时间重试，不会导致服务挂掉。

💡 总结

通过把 进程内 ONNX 向量化 和 嵌入式 LanceDB、智能 token 增强 以及 Model Context Protocol（MCP） 结合起来，我们抠掉了在本地做语义搜索的绝大部分摩擦：

• ✅ 无需后台常驻进程，不需要在电脑上一直常驻。

• ✅ 不依赖 Python 或 ChromaDB 等组件。

• ✅ 没有 Git 噪音（统一放在 node_modules/.cache）。

• ✅ 自动处理拼写错误和单词变化，耗时 <1ms。

• ✅ 按语义搜索自然语言，把你的问题变成对应精确代码和 markdown 文档。

祝编码愉快！☕️🚀