古法编程

Claude Context 提供了四个 MCP 工具用于管理代码库索引和执行语义搜索：index_codebase 启动后台索引，search_code 进行混合语义搜索，clear_index 安全清除索引，get_indexing_status 跟踪索引进度。这些工具协同工作，构成了 Claude Context 为 AI 编程助手提供完整代码上下文的核心操作流。

Claude Context MCP 工具详解：index_codebase、search_code、clear_index、get_indexing_status

Claude Context 通过 MCP 协议向 AI 客户端暴露了一套工具，使 Claude Code 等助手能够管理其底层的向量索引并执行语义搜索。理解并正确使用这四个工具是发挥其效能的关键。本文将依据源码逐一详解每个工具的参数、用法和内部工作逻辑。

1. index_codebase：索引代码库

index_codebase 是启动语义搜索的前提。它会对指定的绝对路径下的代码库进行递归扫描、分割、嵌入并向量化存储。

参数详解

根据 packages/mcp/src/index.ts 中的定义，该工具的输入参数如下：

  • path (string, 必填)：需要索引的代码库的绝对路径。这是最重要的参数，路径错误将导致任务失败。
  • force (boolean, 可选, 默认值: false)：是否强制重新索引。当设为 true 时，即使目标路径已存在索引，也会清除旧索引并重新开始。
  • splitter (string, 可选, 默认值: 'ast')：指定代码分割策略。可选值为 'ast'（基于抽象语法树的智能分割）或 'langchain'（基于字符的递归分割）。
  • customExtensions (string[] 可选, 默认值: [])：要包含的额外文件扩展名列表，例如 ['.vue', '.svelte']。扩展会合并到默认支持的列表中。
  • ignorePatterns (string[] 可选, 默认值: [])：要排除的额外文件或目录模式，例如 ['static/**', '*.tmp']。

执行流程与响应

调用此工具后，索引任务会在后台异步执行，工具会立即返回一条确认消息，指示索引已在后台启动。你可以继续与 AI 对话或使用其他工具。索引进度可通过 get_indexing_status 工具查询。

响应示例（成功启动）：

{
  "content": [{ "type": "text", "text": "Started background indexing for codebase '/path/to/your/project' using AST splitter.\n\nIndexing is running in the background. You can search the codebase while indexing is in progress, but results may be incomplete until indexing completes." }]
}

常见错误表现：

  • 路径不存在或不是目录：返回明确的错误信息。
  • 代码库正在索引中（非强制）：提示等待完成。
  • 代码库已索引（非强制）：提示使用 force=true 重新索引。
  • 向量数据库集合数量达到上限：返回特定的 COLLECTION_LIMIT_MESSAGE 错误信息。

内部机制：验证与预防

在 handlers.ts 的 handleIndexCodebase 方法中，索引开始前会执行一系列验证。一个关键的防御性逻辑是 validateLegacyZeroEntries。此方法在服务器启动时运行，扫描快照文件，修复历史上遗留的 indexedFiles: 0, totalChunks: 0, status: 'completed' 的“毒化”条目。这种错误状态会导致客户端误判为“未索引”，从而触发无限次的强制重新索引循环（参见源码注释中的 Issue #295）。修复方式是查询向量数据库（Milvus）获取真实的行数，若行数大于0则更新快照，若为0或不存在则移除该幽灵条目。

2. search_code：语义搜索

search_code 是执行搜索的核心工具。它使用自然语言查询，在已索引的代码库中查找语义相关的代码片段。

参数详解

  • path (string, 必填)：要搜索的代码库的绝对路径。此路径应与索引时使用的路径一致，或是其子目录。
  • query (string, 必填)：自然语言搜索查询。例如，“用户登录验证函数”、“处理JSON解析错误的地方”。
  • limit (number, 可选, 默认值: 10)：返回结果的最大数量。最大值限制为50。
  • extensionFilter (string[] 可选, 默认值: [])：按文件扩展名过滤结果。例如，['.ts', '.py'] 只返回 TypeScript 和 Python 文件的结果。

执行流程与混合搜索

该工具会先同步云端索引状态，然后执行搜索。其搜索策略是混合搜索，结合了传统关键词匹配（BM25）和基于向量的语义搜索，以提供更相关的结果。

响应示例（搜索结果片段）：

{
  "content": [{
    "type": "text",
    "text": "🔍 Found 3 code snippets:\n\n**File: /src/auth/login.ts (Lines 10-25)**\n```typescript\nasync function validateUser(email: string, password: string) {\n  // ... 验证逻辑\n}\n```\n**File: /src/middleware/auth.ts (Lines 1-15)**\n```typescript\nexport const authMiddleware = (req, res, next) => {\n  // ... 中间件逻辑\n};\n```"
  }]
}

常见错误表现：

  • 代码库未索引：返回“请先使用 index_codebase 工具索引”的错误提示。此时应先调用 index_codebase。
  • 索引进行中：返回的结果可能不完整，并附有“索引正在进行”的警告提示。

3. clear_index：清除索引

clear_index 用于安全地移除指定代码库的向量索引。这是一个需要谨慎操作的功能，因为它会删除已建立的索引数据。

参数详解

  • path (string, 必填)：需要清除索引的代码库的绝对路径。

安全清除逻辑

直接清除索引可能会与正在运行的后台索引任务产生冲突，导致状态不一致或错误。handlers.ts 中的 handleClearIndex 实现包含了安全逻辑：在真正清除 Milvus 中的集合之前，它会先查找并取消（AbortController）该路径上所有活跃的索引任务，并等待其完成或终止。这确保了索引过程被彻底停止后，才删除底层数据，避免了并发写入的问题（参见源码注释中的 Issue #199）。

响应示例：

{
  "content": [{ "type": "text", "text": "Successfully cleared index for '/path/to/your/project'." }]
}

4. get_indexing_status：查询索引状态

get_indexing_status 用于跟踪 index_codebase 发起的后台任务的进度。这对于索引大型代码库或了解操作是否完成非常有用。

参数详解

  • path (string, 必填)：要查询状态的代码库的绝对路径。

状态与百分比

该工具返回的信息包含清晰的阶段和百分比：

  • 索引进行中：返回 status: 'indexing' 和 indexingPercentage（例如 0% → 5% → 10% → 100%）。
  • 索引完成：返回 status: 'indexed' 以及 indexedFiles 和 totalChunks 统计数据。
  • 索引失败：返回 status: 'indexfailed' 和错误信息。

索引进度百分比的更新来源于 context.indexCodebase 方法的回调，并被记录在快照文件 mcp-codebase-snapshot.json 中。服务器启动时的 validateLegacyZeroEntries 和搜索操作中的云同步逻辑，都会尝试从云端（Zilliz Cloud）恢复或校正本地快照，确保状态信息的一致性。

FAQ

Q: 调用 search_code 时提示代码库未索引，但我肯定索引过，怎么办？ A: 这可能是本地快照与云端状态不同步导致的。search_code 内部会尝试从云端同步状态。如果仍然失败，可以尝试重新调用 index_codebase（使用 force: true）来建立正确的索引。具体可参考 Claude Context 故障排除指南。

Q: 索引过程中可以取消吗？ A: 可以。使用 clear_index 工具传入相同的路径。该工具会安全地终止后台索引任务并清理索引数据。

Q: splitter 参数选 ast 还是 langchain？ A: 对于大多数现代编程语言（如 TypeScript, Python, Java），推荐使用 ast（默认值）。它能基于语法结构进行更智能的分割，保持代码块的完整性。如果遇到分割问题或处理非标准文件，可以尝试 langchain。详细对比可参阅 Claude Context 代码分割策略。