nb-agentic-rag 0.1.0

Agentic RAG MCP Server — 12 tools for AI-driven multi-round code retrieval that outperforms naive single-shot RAG

nb_agentic_rag

Agentic RAG MCP Server — 让 AI Agent 自主决定何时搜、搜什么、搜几次。12 个精心设计的互补工具，吊打传统一轮检索的 Naive RAG。

为什么不是 Naive RAG？

	Naive RAG	Agentic RAG (本项目)
检索触发	每次提问自动检索 top-5 注入	AI 自主决定是否检索、用哪个工具
检索轮次	1 次	多轮（实测 10 次搜索 + 5 次文件读取）
查询构造	用户原文	AI 重写查询、组合多种检索策略
工具种类	仅语义搜索	语义 + grep + AST 符号定位 + 原文读取
分析深度	浅层描述	完整的跨文件调用链图
准确度 (funboost 测试)	5.8/10	7.6/10 (+30%)

核心观点：检索不是管道，是 Agent 的一种能力。

快速开始

1. 安装

# 方式 A: uvx (推荐，零安装)
uvx nb_agentic_rag

# 方式 B: pip
pip install nb_agentic_rag

2. 配置 API Key

# SiliconFlow 免费 API Key (https://siliconflow.cn)
export NB_RAG_API_KEY=sk-xxx

3. 在 Cursor 中使用

在 .cursor/mcp.json 中添加：

{
  "mcpServers": {
    "rag": {
      "command": "uvx",
      "args": ["nb_agentic_rag"],
      "env": {
        "NB_RAG_API_KEY": "sk-xxx"
      }
    }
  }
}

然后告诉 AI：

"帮我把 D:/codes/my_project 导入到 myproject 知识库，然后搜索 XXX"

AI 会自动调用 rag_add_document 导入，再用 rag_search + rag_grep + rag_find_definition 多轮检索回答你的问题。

4. 在 OpenCode / Open WebUI 中使用 (HTTP 传输)

uvx nb_agentic_rag --transport streamable-http --port 9101

12 个工具

类别	工具	功能
导入	rag_add_document	导入文件/目录（自动分块 + Embedding + 缓存原文）
语义检索	rag_search	向量搜索 + Rerank 精排
语义检索	rag_search_and_fetch	搜索 + 自动取源码（省一次 round-trip）
精确检索	rag_grep	关键词/正则搜索（和语义搜索互补）
精确检索	rag_find_definition	AST 精确定位 class/function 完整定义
上下文扩展	rag_get_file_chunks	按 chunk 分页浏览文件
上下文扩展	rag_get_raw_file	读取无 overlap 的原始文件
上下文扩展	rag_get_adjacent_chunks	获取相邻 chunks
上下文扩展	rag_get_chunks_by_lines	按行号范围取 chunks
管理	rag_list	列出知识库所有文档
管理	rag_delete	删除指定文档
管理	rag_stats	知识库统计信息

AI 推荐的深度分析工作流

1. rag_search → 找到相关文件和大致位置
2. rag_grep → 精确定位类名/方法名/常量（语义搜索漏掉的）
3. rag_find_definition → 获取完整的类/函数定义源码
4. rag_get_raw_file → 读取完整源码验证细节
5. 跨文件追踪：发现未知符号时重复 2-4 步

配置

环境变量

变量	必填	默认值	说明
NB_RAG_API_KEY	是		Embedding/Rerank API Key
NB_RAG_BASE_URL	否	https://api.siliconflow.cn/v1	API Base URL
NB_RAG_EMBEDDING_MODEL	否	BAAI/bge-m3	Embedding 模型
NB_RAG_RERANK_MODEL	否	BAAI/bge-reranker-v2-m3	Rerank 模型
NB_RAG_DB_PATH	否	./rag_db	ChromaDB 存储路径
NB_RAG_CHUNK_SIZE	否	1500	分块大小
NB_RAG_CHUNK_OVERLAP	否	200	分块重叠

配置文件 (可选)

支持 YAML 配置文件，自动搜索顺序：

1. ./nb_rag_config.yaml
2. ~/.config/nb_agentic_rag/config.yaml

embedding:
  api_key: ${NB_RAG_API_KEY}
  base_url: https://api.siliconflow.cn/v1
  model: BAAI/bge-m3

rerank:
  model: BAAI/bge-reranker-v2-m3

storage:
  db_path: ./rag_db

chunking:
  chunk_size: 1500
  chunk_overlap: 200

CLI 参数

nb_agentic_rag --help
nb_agentic_rag --transport stdio              # 默认
nb_agentic_rag --transport streamable-http    # HTTP 模式
nb_agentic_rag --api-key sk-xxx              # 直接传 API Key
nb_agentic_rag --db-path /data/rag           # 指定存储路径
nb_agentic_rag --config ./my_config.yaml     # 指定配置文件

设计决策

为什么 chunk_size = 1500？

BGE-M3 的最佳召回区间是 700-3000 字符。之前用 500 导致 funboost 的 BrokerEnum（8000 字符）被切成 43 块，搜索碎片化严重。改成 1500 后降到 6 块，基本消除碎片化。

为什么双存储？

• ChromaDB：存向量 chunks（有 overlap），用于语义搜索
• raw_files/：存原始文件快照（无 overlap），用于精确行号读取

AI 经常需要看完整源码，如果只有 chunks 会有 overlap 重复，浪费 token 还容易困惑。

为什么 AST scope 注入？

每个 chunk 的 embedding 前注入 [File: path] [Scope: MyClass.my_method] [Sig: def my_method(self, x)]。 这样搜索 "push 方法" 时更容易命中 class Booster 下的 def push(self, *args)，而不是某个无关的 push 字符串。

为什么 12 个工具而不是 3 个？

MCP 工具设计原则：职责单一、参数最少、docstring 引导下一步。

一个大而全的 rag_query(mode="search|grep|raw|...") 会导致 AI 幻觉——它不知道该传什么参数。 拆成 12 个小工具后，每个工具参数清晰，AI 的调用准确率大幅提升。

技术栈

组件	选择
Embedding	SiliconFlow BGE-M3（免费、中文最强之一）
Rerank	SiliconFlow BGE-Reranker-v2-m3（免费）
向量数据库	ChromaDB（本地持久化，无需外部服务）
分块	LangChain TextSplitter + 自研 AST 增强
MCP	FastMCP (Python)
传输	stdio / streamable-http / SSE

License

MIT