Skip to main content
Glama
deenesjakoruzh
genautkin

code-search-mcp

by genautkin
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

🔍 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: smart-coding-mcp

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

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

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

工作原理：语义的地图

  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/                     │
└─────────────────────────────────────────────────────────────┘

⚙️ 背后的技术

组件

技术

为什么这样选择

运行时

Node.js + TypeScript

跨平台（macOS、Windows、Linux），零运行时依赖。

本地 AI 嵌入

@huggingface/transformers (ONNX)

通过 Xenova/all-MiniLM-L6-v2 在进程内生成密集的 384 维向量。100% 私有——零网络请求。

向量存储

LanceDB

基于 Apache Arrow 构建的嵌入式、无服务器向量数据库，无需外部服务器进程。

实时文件监听

chokidar

实时监听文件变化，在保存后的 ~200ms 内增量更新向量。

协议

@modelcontextprotocol/sdk

支持 Claude Code、Gemini CLI、Cursor 和 Windsurf 的标准 MCP 协议。

🔍 内部实现原理

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 工具

工具名称

参数

描述

调用时机

code_search

query (必填)limit (可选，默认 10)pathFilter (可选字符串)language (可选字符串)codeOnly (可选布尔值)

对索引的仓库文件执行混合语义 + 词法搜索。返回带行号的代码片段及相似度分数。

首选调用：当需要定位以自然语言描述的概念、业务逻辑、工作流、UI 组件或功能时（例如 “用户认证在哪里刷新”、“购物车税费计算器”）。

code_search_status

(无)

返回当前索引进度（READY、INDEXING）、完成百分比、总文件数以及 LanceDB 中的分块数量。

如果怀疑索引仍在进行中，可在大规模搜索前检查。

code_search_reindex

forceFull (可选布尔值)

触发后台重新索引或完整的数据库重建。

当用户明确要求重建数据库，或大规模分支合并后调用。

code_search_guide

(无)

返回代理内的使用最佳实践和技巧。

在调用工具过程中用于自行发现最佳实践。

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

                       ┌───────────────────────────────────────────────┐
                       │ 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)  │
                   └─────────────────────────────────────────────────────────┘

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

工具

主要工作

它最擅长什么

它的薄弱点

code-search (语义向量)

概念与意图发现

查找用日常英文描述的业务逻辑、功能、组件和架构文档。

跨动态调用层次结构以及尚未添加注释的旧文件时，表现不佳。

codegraph（AST 符号图）

结构导航与爆炸范围

一步即可追溯符号的定义、调用者、被调用者和覆盖的单元测试。

在不知道符号名称的情况下，根据通常的功能描述、自然语言查找概念时比较吃力。

实际案例研究：现代开发 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 文档。

祝编码愉快！☕️🚀

Available Tools

4 tools
code_search_guideA

Get best practices and usage instructions for AI agents on how and when to use code_search.

NameRequiredDescriptionDefault

No parameters

TDQS

A4.2/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must carry the behavioral burden. It clearly implies a read-only retrieval of guidance, but does not disclose output format, size, or any side effects. For a simple guide tool, the lack of explicit behavioral detail is acceptable but not comprehensive.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, front-loaded sentence that states the action and the target resource with zero redundancy. Every word contributes to clarity, making it highly efficient.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a parameterless guide with no output schema, the description sufficiently conveys the tool's purpose and content. It could explicitly state that the returned instructions should be followed before using code_search, but the sibling context and the description's phrasing make this largely self-evident, so the gap is minimal.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

There are zero parameters, and schema coverage is 100% (vacuously). Since the tool takes no inputs, the description need not add parameter-specific meaning; the baseline of 4 for no-parameter tools applies without deduction.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('get') and a clear resource ('best practices and usage instructions for AI agents on code_search'). It distinguishes itself from sibling tools like code_search (which performs the search), code_search_status, and code_search_reindex, making its purpose unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly states it provides guidance on how and when to use code_search, which implicitly tells an agent to use this tool when needing to decide on code_search usage. However, it does not explicitly contrast with sibling tools or state 'use this before calling code_search', leaving that inference to the agent.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

code_search_reindexA

Trigger a background re-index of the repository. Can be used to force a full reindex.

NameRequiredDescriptionDefault
forceFullNoIf true, clears existing vector database and rebuilds index from scratch

TDQS

A3.7/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the burden of disclosing behavior. It mentions 'background' indicating asynchronicity and 'force a full reindex' implying destructive potential, but it omits details like whether an incremental reindex is available, idempotency, or cancellation behavior. It provides some useful context but is not comprehensive.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two short, focused sentences with no filler. It front-loads the core action ('Trigger a background re-index') and adds the optional force behavior succinctly. Every word earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with a single optional parameter and no output schema, the description covers the essentials but leaves gaps: it does not clarify what happens when forceFull is false (e.g., incremental indexing) nor mention the sibling code_search_status for checking reindex progress. These are minor gaps given the simplicity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, and the forceFull parameter is fully documented in the schema ('clears existing vector database and rebuilds index from scratch'). The description's mention of 'force a full reindex' adds minimal value beyond the schema. Baseline 3 is appropriate when the schema does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('Trigger a background re-index of the repository') with a specific verb and resource. It also hints at the forceFull parameter. This distinguishes it from siblings like code_search, code_search_status, and code_search_guide, which serve different purposes.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description does not explicitly state when to use this tool versus alternatives. It implies usage through the tool's purpose but lacks explicit context such as 'use after schema changes' or 'when index is stale'. No exclusions or alternative routing are provided.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

code_search_statusA

Get the current indexing status, progress percentage, total files, and indexed chunk count.

NameRequiredDescriptionDefault

No parameters

TDQS

A4.3/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden. It correctly implies a read-only operation via 'Get' and enumerates the output fields. It does not mention side effects, authentication, or rate limits, but for a simple status check these are not critical. It does not contradict any annotations (there are none) and gives sufficient behavioral context for expectation setting.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence that lists the key outputs without any fluff. It is front-loaded with the verb and resource, making it instantly scannable. Every word earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with no parameters, no annotations, and no output schema, the description is fully sufficient. It states exactly what information will be retrieved. An agent can call it without needing additional context or clarification.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters, so the schema coverage is trivially 100%. Baseline for 0 parameters is 4. The description adds no parameter-specific details (none needed), and it correctly explains what the tool returns, which is sufficient.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('Get') and the resource ('current indexing status'), and lists specific fields (progress percentage, total files, indexed chunk count). The verb and resource differentiate it from siblings like code_search, code_search_reindex, and code_search_guide. It unambiguously describes what the tool does.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies its use for checking indexing status but provides no explicit guidance on when to choose this over the sibling tools (e.g., 'use this to check, not to trigger reindexing'). No exclusions or alternative references are given. While the purpose is clear, the tool lacks explicit routing compared to the high-standard examples.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

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

  1. 4 tool updatesv0.1.0
    • First observedcode_search
    • First observedcode_search_guide
    • First observedcode_search_reindex
    • First observedcode_search_status
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A4.2/5.0

Scored across 4 tools

Disambiguation5/5

Each tool has a unique, clearly defined purpose: search, status, reindex, and guide. There is no overlap or ambiguity between them, and the descriptions make it obvious which tool to use for each task.

Naming Consistency5/5

All tool names follow the same convention: 'code_search_' followed by a simple action verb (search, status, reindex, guide). This is perfectly consistent and makes the tool set easy to predict and use.

Tool Count5/5

With 4 tools, the set is tightly scoped and every tool serves a necessary function for a code search server. This is an ideal count—not too thin or over-bloated—for the domain.

Completeness5/5

The tool surface covers the full lifecycle of a code search server: performing searches, checking index status, triggering reindexes, and providing usage guidance. There are no obvious gaps in functionality.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • claude-context-local

    tazhate
    A
    license
    Not graded
    quality
    C
    maintenance
    Provides Claude Code with local semantic search and indexing of your codebase using AST-aware chunking and hybrid search, enabling deep code understanding without sending data to the cloud.
    44 PyPI
    MIT

  • smart-coding-mcp

    amalikn
    A
    license
    A
    quality
    D
    maintenance
    Enables AI assistants to perform intelligent semantic code search across codebases using local AI embeddings for meaning-based retrieval.
    6
    34 npm
    MIT

  • ContextTree MCP

    chelslava
    A
    license
    A
    quality
    A
    maintenance
    Enables AI coding assistants to perform local semantic code search using AST parsing and embeddings, finding code by meaning with exact file and line locations, plus AST-based usage lookup.
    4
    MIT