zvec-grep MCP接口详解：zvec_grep_search如何让Agent少调工具、少耗Token

zvec-grep MCP接口详解zvec_grep_search如何让Agent少调工具、少耗Token【免费下载链接】zvec-grepLocal-first search across your workspace, built for humans and AI agents.项目地址: https://gitcode.com/gh_mirrors/zv/zvec-grepzvec-grep是一个 Local-first 的工作区搜索引擎同时服务于人类与 AI Agent。它通过MCP 接口把zvec_grep_search这一个混合检索工具暴露给 Agent一次调用即可同时走语义、BM25 词法与向量三路召回并以紧凑的文本证据直接回填上下文。官方基准测试显示接入后 Agent 的输入 Token 最高减少 47.3%、工具调用减少 58.6%答案质量还略有提升。如果你在用 Codex、Claude Code、Cursor 等编码 Agent这篇文章会带你理解它的 MCP 设计如何少调工具、少耗 Token并给出可直接落地的配置建议。60秒接入一条命令连接你的 Agentzvec-grep 的 MCP 端点默认运行在本地回环地址http://127.0.0.1:7999/mcpStreamable HTTP。安装集成只需两步npm install -g zvec/zvec-grep zg --install --target codex --yeszg --install会自动完成四件事写入zvec_grepMCP 配置、写入搜索引导规则、添加工具审批策略、启动本地服务。支持的 Agent 包括 Codex、Claude Code、Qwen Code、Qoder、Cursor、GitHub Copilot、VS Code 和 OpenCode配置细节见 docs/01-agents.md。设计亮点一默认工具集只暴露一个工具打开 src/mcp/tools.ts 可以看到zvec-grep 把 MCP 工具分成两套工具集工具集暴露的工具适用场景agent默认仅zvec_grep_search日常 Agent 检索精确查找交给 Agent 原生 grep/rgfullzvec_grep_search、zvec_grep_rg、zvec_grep_index、zvec_grep_index_drop、zvec_grep_index_status、zvec_grep_server_status需要 Agent 管理索引生命周期的客户端默认只有一个工具本身就是省 Token 的设计工具 schema 更短MCP 的tools/list结果会占用 Agent 的上下文工具越少系统提示越精简决策更确定Agent 不必在多个功能相近的工具间纠结减少误调用与重复调用索引由 CLI 托管建索引、看状态都在zg命令里完成Agent 不需要反复调用状态类工具做 preflight 检查。如需完整工具集可用zg --server on --mcp-toolset full或环境变量ZVEC_GREP_MCP_TOOLSETfull切换见 docs/03-mcp.md。设计亮点二一次调用完成混合检索zvec_grep_search的核心思想是一次调用、多路召回它的输入参数定义在 src/mcp/schemas.ts按检索路由分组参数含义何时用root工作区绝对路径必填每次调用query一个自然语言混合查询FTS向量概念检索的主力fts词法锚点数组如符号名、错误信息已知精确标识符时补充vector纯语义查询组纯含义检索fuse把所有组合并为一个排序计划混合任务limit每组最多返回条数≤50控制输出规模previewshort默认有界片段 /full返回可取内容默认short最省 Tokenglobs/fileTypesripgrep 风格的路径与文件类型过滤缩小检索范围一个典型的语义意图 词法锚点融合调用{ root: /path/to/workspace, query: authentication flow and failure handling, fts: [AuthService, ForbiddenError], fuse: true, limit: 10 }没有fuse时各查询组分别返回并保留组元数据设置fuse: true后所有组坍缩成一个重排序列表——这正是让 Agent一次到位的关键。设计亮点三面向 Agent 的紧凑响应zvec_grep_search的返回值是为 Agent 上下文设计的纯文本而不是 JSON 大对象freshness: fresh src/theme/use-theme.ts:12-36 matched: 16-18 source: 15 export function useTheme() { 16 const [theme, setTheme] useState(light);三段式结构带来三个省 Token 的效果格式化逻辑见 src/cli/format/context.ts有界片段默认short预览每个文件最多 10 行、单行截断到 160 字符证据紧凑、噪音少确需细节时才用preview: fullfreshness 直接内联响应首行就给出freshness与后台刷新状态索引过期时结果仍可用served_from_current_indexAgent 无需额外调用状态工具引导够用即停MCP 说明中明确写入把足够的返回内容当作已读证据只在缺口处才打开具体文件直接减少了后续的 Read 调用。内置路由规则什么时候搜、什么时候停比工具本身更精妙的是随 MCP 一起下发的引导规则见 src/prompts/zvec-grep-guidance.ts 与 src/mcp/tools.ts 中的searchRoutingRules。核心路由逻辑意图推荐动作定位精确词、引文、文件名、正则用 Agent 原生 grep / rg措辞或位置未知需要跨文件关系、因果、时序、对比zvec_grep_search有精确锚点但答案跨文件zvec_grep_search带锚点搜索再用 grep/rg 聚焦验证与本地工作区无关的外部问题不用 zvec-grep规则里还有几条硬性止损条款证据足够就停止搜索、不重复相似查询、纯语义探测最多一次且无相关结果即停。这些约束从协议层面压制了 Agent 最常见的 Token 浪费行为——盲目扩大检索和反复确认。基准数据少调工具、少耗 Token 到底省多少官方用配对 A/B 实验任务、模型、提示、环境全部固定仅改变是否可用 zvec-grep验证了上述设计完整结果见 benchmarks/README.md。左图CodingSWE-QA-Bench 20 任务输入 Token −47.3%、工具调用 −58.6%、耗时 −37.5%而 LLM 评审得分 1.50pp右图通用文本检索BrowseComp-Plus 80 案例输入 Token −41.7%、工具调用 −37.3%准确率持平。真实仓库案例中Pylint 任务输入 Token 从 1.38M 降到 299K−82.7%、工具调用从 54.7 次降到 9 次−83.5%——语义发现 排序词法证据让 Agent 不再依赖大范围盲目扫描。三个省 Token 最佳实践语义意图进query已知符号进fts加fuse: true一次调用替代先 grep 猜关键词、再 Read 多个文件的多轮试探默认short预览片段足够回答时不要升级preview: full只在缺细节时补查具体文件行号信任响应里的 freshness索引稍旧possibly_stale且结果充分时直接使用不做状态预检把省下的调用留给真正有价值的问题。更多端点安全仅回环 可选 Bearer 认证、远程 Embedding 授权等细节可继续阅读 docs/03-mcp.md 与 docs/06-server.md。【免费下载链接】zvec-grepLocal-first search across your workspace, built for humans and AI agents.项目地址: https://gitcode.com/gh_mirrors/zv/zvec-grep创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考