mcpField
S
semble

semble

github.com/akillness开发53233 次安装4 天前更新
代码仓库

关于 semble

semble 是面向 Agent 的代码搜索技能和命令行工具，可通过自然语言、符号及相关代码查询，在本地或远程仓库中定位代码片段。它也提供 MCP 接入，让 Agent 无需读取整个文件即可搜索。

主要功能

  1. 01自然语言搜索代码
  2. 02查找符号和标识符
  3. 03查找相关代码片段
  4. 04索引本地和远程仓库
  5. 05返回片段、文件路径和行号

适用场景

  1. 01定位身份验证或限流逻辑
  2. 02不知道文件位置时查找符号
  3. 03从搜索结果扩展查找相似代码

MCP 相关

MCP 服务向 MCP 客户端提供 semble 代码搜索能力，可接入 Claude Code、Codex、Cursor 和 OpenCode。

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/akillness/jeo-skills --skill semble

安装后在 Claude Code 中输入/semble确认已加载。

附带文件SKILL.toon

详细介绍

semble — 面向 Agent 的快速、高效令牌代码搜索

与 grep+read 相比，令牌用量减少约 98%。约 250ms 建立索引。约 1.5ms 查询。无需 GPU 或 API 密钥。

Semble 只返回 Agent 所需的相关代码片段，无需搜索完整文件或读取目录。输入自然语言查询或符号查询，例如 "authentication flow" 或 "save_pretrained"，即可返回精确的代码块及其文件路径和行范围，不包含其他内容。

安装

MCP（Claude Code — 推荐）
# Requires uv: https://docs.astral.sh/uv/getting-started/installation/
claude mcp add semble -s user -- uvx --from "semble[mcp]" semble
MCP（Codex）

添加到 ~/.codex/config.toml：

[mcp_servers.semble]
command = "uvx"
args = ["--from", "semble[mcp]", "semble"]
MCP（Cursor）

添加到 ~/.cursor/mcp.json：

{
  "mcpServers": {
    "semble": {
      "command": "uvx",
      "args": ["--from", "semble[mcp]", "semble"]
    }
  }
}
MCP（OpenCode）

添加到 ~/.opencode/config.json：

{
  "mcp": {
    "semble": {
      "type": "local",
      "command": ["uvx", "--from", "semble[mcp]", "semble"]
    }
  }
}
CLI / pip
pip install semble        # pip
uv tool install semble    # uv (recommended for CLI use)
技能（任何平台）
npx skills add https://github.com/akillness/jeo-skills --skill semble

适用场景

  • 用自然语言描述行为来搜索代码库（"how is rate limiting handled"）
  • 无需知道确切文件即可查找符号或标识符（"save_pretrained"）
  • 发现与已知位置在语义上相似的代码（find-related）
  • 通过 MCP 为 Agent 提供令牌高效的仓库访问方式，而不是让它搜索或读取完整文件
  • 无需先克隆即可为远程 git 仓库建立索引

不适用场景

  • 需要读取完整文件或列出目录 → 使用原生的 Read、Glob 工具
  • 需要正则表达式或精确字符串搜索 → Grep 更合适
  • 仓库太小，不值得建立索引（只有几个文件）——直接读取即可
  • 需要运行测试、构建或执行代码——这只是一个搜索工具

CLI 用法

# Natural-language search in a local repo
semble search "authentication flow" ./my-project

# Symbol search
semble search "save_pretrained" ./my-project

# Search with a limit on returned chunks
semble search "save model to disk" ./my-project --top-k 10

# Search a remote git repo (no clone needed)
semble search "save model to disk" https://github.com/MinishLab/model2vec

# Find semantically similar code given a known file+line
semble find-related src/auth.py 42 ./my-project

# Show token savings vs grep+read for the last query
semble savings
semble savings --verbose

Python 库

from semble import SembleIndex

# Index local directory
index = SembleIndex.from_path("./my-project")

# Index remote repository (no clone required)
index = SembleIndex.from_git("https://github.com/MinishLab/model2vec")

# Natural-language or symbol query
results = index.search("save model to disk", top_k=3)

# Find semantically similar code to a known chunk
related = index.find_related(results[0], top_k=3)

# Inspect results
result = results[0]
print(result.chunk.file_path)   # "model2vec/model.py"
print(result.chunk.start_line)  # 127
print(result.chunk.end_line)    # 150
print(result.chunk.content)     # the function/class body

AGENTS.md / CLAUDE.md 集成

将此部分添加到项目的 AGENTS.md 或 CLAUDE.md，即可为所有 Agent 启用 semble：

## Code Search

Use `semble search` to find code by describing what it does or naming a symbol, instead of grep:

​```bash
semble search "authentication flow" ./my-project
semble search "save_pretrained" ./my-project
semble search "save model to disk" ./my-project --top-k 10
​```

Use `semble find-related` to discover code similar to a known location (pass `file_path` and `line` from a prior search result):

​```bash
semble find-related src/auth.py 42 ./my-project
​```

`path` defaults to the current directory when omitted; git URLs are accepted.

If `semble` is not on `$PATH`, use `uvx --from "semble[mcp]" semble` in its place.

对于 Claude Code 子 Agent，在项目根目录中初始化一次：

semble init

性能基准

指标Semblegrep+read
索引速度~250ms不适用
查询速度~1.5ms不定
召回率为 94% 时的令牌用量~2k 个令牌~100k 个令牌
NDCG@100.854—
相较于 137M 参数的 CodeRankEmbed质量达 99%—
相较于 transformer 的索引速度快 218 倍—

操作规则

  1. 交互式 Agent 使用时优先安装 MCP；脚本和 CI 使用时优先选择 CLI/pip。
  2. 使用 --top-k 限制结果并缩小上下文——默认值对于 Agent 提示词来说通常过大。
  3. 需要从一个已知代码块扩展到相似代码时，在 search 后使用 find-related。
  4. 在项目根目录中使用 semble init，为 Claude Code 子 Agent 预热索引。
  5. 如果 $PATH 中没有 semble，在脚本中将其替换为 uvx --from "semble[mcp]" semble。
  6. 将 semble 作为第一轮搜索工具——仅当返回的代码块上下文不足时，才读取完整文件。

示例

# Search for how a feature is implemented
semble search "rate limiting middleware" ./api-service

# Find all code related to database migrations
semble search "database migration" ./backend --top-k 5

# Explore similar code patterns near a known function
semble find-related src/middleware/auth.py 88 ./api-service

# Index and query a remote library without cloning
semble search "tokenizer padding" https://github.com/huggingface/transformers

来源：MinishLab/semble — MIT 许可证

评论

支持 Markdown