Zmsoft
ENZH-CN
•••
JAARDEESFRHIINPT-BRROTRUKVIZH-TW
使用 Semble MCP 优化 Claude Code 的代码搜索 — 减少98%Token的机制与实践指南

使用 Semble MCP 优化 Claude Code 的代码搜索 — 减少98%Token的机制与实践指南

使用 Semble MCP 优化 Claude Code 的代码搜索 — 减少98%Token的机制与实践指南

什么是 Semble MCP？

Semble MCP 是专为 AI 编程代理设计的高速本地代码搜索服务器。其目的是为 Claude Code、Cursor、OpenAI Codex 等代理提供"比 grep 更智能、比 RAG 更轻量的代码探索"。

通常 AI 代理在查找代码时会组合使用 grep、ripgrep、全文件读取和 embeddings 搜索，而 Semble 对此进行了专项优化。

"认证处理在哪里？"
"save model 的实现"
"Firebase 初始化"

通过这样的自然语言搜索，快速返回所需的代码片段。

主要特性

超高速本地处理

Semble 仅使用 CPU 运行。无需 GPU。

  • 仓库索引生成：约 250ms
  • 搜索：约 1.5ms

大幅减少 Token 使用量

与"grep + 文件读取"相比，访问所需代码所用的 Token 减少约98%。在大型项目上长时间运行 Claude Code 时，降低成本的效果非常显著。

安全性：完全本地化设计

官方说明强调：

  • 无需 API 密钥
  • 不与外部服务通信
  • 完全通过本地路径运行

索引生成、搜索、embeddings 生成和 BM25 搜索全部在本地 PC 内处理。

如何添加到 Claude Code

需要 uv。可以用以下命令添加：

claude mcp add semble -s user -- uvx --from "semble[mcp]" semble

安装时从 PyPI 获取包，但此后的运行完全在本地进行。

与 Sub-agent 的结合

Semble 除了 MCP 版本外还有 CLI 版本。由于 Claude Code 的 Sub-agent 在某些情况下可能无法使用 MCP，建议在 CLAUDE.md 或 AGENTS.md 中明确记录 CLI 版本的使用。

Use `semble search` instead of grep for codebase exploration.

这样写后，多个代理将统一使用 Semble。

实际使用方式

# 自然语言搜索
semble search "认证流程" ./my-project
semble search "Firebase 初始化" ./my-project
semble search "查询提交处理" ./my-project --top-k 10

# 相关代码探索（指定文件路径和行号）
semble find-related src/auth.py 42 ./my-project

与其他工具的职责划分

Semble 仅是专注于代码搜索的工具。了解与其他 MCP 的职责划分非常重要。

工具 职责
Semble 搜索自己的代码
context7 获取库的官方文档
filesystem MCP 读写文件
git MCP 操作 Git

具体而言：

  • context7 → "想了解 Jetpack Compose 的官方规范"
  • Semble → "想在自己的项目中查找 Compose 代码"

构建、lint、测试运行和数据库操作不在 Semble 的范围内。

适合哪些项目？

效果最好的情况

  • 大型仓库
  • Android 项目（Jetpack Compose、Firebase 混合、multi-module 结构）
  • 通过 AGENTS.md 大量使用 Sub-agent
  • 长期持续使用 Claude Code

不太需要的情况

  • 小型仓库（几个文件）
  • 一次性任务

安全注意事项

虽然 Semble 本身是完全本地化设计，但使用时有几点需要注意。

搜索结果会传递给 LLM

Semble 不会向外部发送代码，但它返回的搜索结果会通过 Claude Code 传递给 LLM。

本地代码
  ↓ Semble 搜索（完全本地）
  ↓ 将搜索结果传递给 Claude
  ↓ LLM 处理

也就是说，需要考虑的是传递给 LLM，而非 Semble 本身。

安全配置示例

如果安全是优先考虑，建议使用最小化外部通信 MCP 的配置。

Claude Code
├ Semble (local)
├ filesystem MCP (local)
├ git MCP (local)
└ terminal (local)

处理机密代码或业务数据时，确认 LLM 侧的 telemetry 和对话保留策略比 Semble 本身更重要。

总结

Semble MCP 是专业使用 Claude Code 的工程师的高价值工具。

  • 大幅降低 Token 成本（最高98%）
  • 自然语言代码搜索
  • 完全本地化设计，安全可靠
  • 与 Sub-agent 结合效果加倍

只需将原来用 grep 扫描大量文件的部分替换为 Semble，代理的运行效率就会大幅提升。特别是在大型项目和多代理配置中，值得考虑尽早引入。