sage-mcp
sage-mcp
针对本地知识库和代码库的混合语义搜索(稠密向量 + BM25)。
技术栈: LlamaIndex · Qdrant (本地嵌入式) · OpenAI embeddings · FastMCP
设置
uv venv # creates .venv with Python 3.11 per .python-version
source .venv/bin/activate
uv pip install -e ".[mcp]"
cp config-example.yaml config.yaml
# edit config.yaml — add your KB paths
echo "OPENAI_API_KEY=sk-..." > .env如果尚未安装 Python 3.11,uv 将自动下载。
Related MCP server: RecallForge
索引
# Index all configured KBs
sage index
# Index one KB only
sage index --kb homelab
# Force full re-index (ignore cache)
sage index --force状态
# Diff KB files vs cache without embedding
sage status
# Single KB
sage status --kb homelab搜索
# Hybrid search across all KBs
sage search "pihole DNS configuration"
# Limit to one KB
sage search "pihole" --kb homelab
# Filter by frontmatter fields
sage search "storage" --filter type=lxc --filter status=running
# More results
sage search "networking" --top-k 20
# Dense-only (no BM25)
sage search "pihole" --no-hybrid
# JSON output (for scripting / agent use)
sage search "pihole" --json
# Markdown output with full file paths (default template: blockquote)
sage search "pihole" --markdown
# Markdown table layout
sage search "pihole" --markdown --template table
# Custom Jinja2 template
sage search "pihole" --markdown --template ~/my-template.md.j2Markdown 模板
--markdown 标志通过 Jinja2 模板渲染结果。
包含两个内置模板:
名称 | 描述 |
| 每个数据块在 |
| 包含分数、知识库、完整文件路径和截断摘要的紧凑 Markdown 表格 |
要编写自定义模板,请从 sage_mcp/templates/ 复制一个内置模板,并通过 --template 传递文件路径。可以使用以下变量:
变量 | 类型 | 描述 |
|
| 搜索查询 |
|
| 每个条目包含 |
|
| 过滤掉的重复数据块数量 |
每个结果的 text_safe 是将换行符折叠为空格并转义管道字符后的数据块文本——适合在 Markdown 表格单元格内使用。对于需要保留原始格式的引用块或围栏代码渲染,请使用 text。
列出知识库
sage list-kbsMCP (AI 智能体访问)
添加到您的 MCP 客户端配置中(使用绝对路径):
{
"mcpServers": {
"sage-mcp": {
"command": "/path/to/sage-mcp/.venv/bin/sage-mcp",
"args": ["--config", "/path/to/sage-mcp/config.yaml"]
}
}
}--config 标志是可选的;如果不使用该标志,服务器将在其工作目录中查找 config.yaml。
暴露的工具:
search_kb(query, kb?, top_k?, filter_type?, filter_status?)— 返回{results: [...], duplicates_removed: N}list_knowledge_bases()— 列出已配置的知识库
配置
编辑 config.yaml 以添加知识库或切换嵌入后端。使用 config-example.yaml 作为模板。
切换到 Ollama(在 nomic-embed-text 运行并开启 GPU 加速后):
embedding:
provider: ollama
model: nomic-embed-text
base_url: http://<ollama-ip>:11434然后运行 sage index --force 以重新嵌入所有内容。
增量更新
索引器会在 pipeline_cache/<kb-name>/hashes.json 中跟踪每个文件的内容哈希。
重新运行 sage index 仅会重新嵌入已更改的文件。可以安全地在 cron 或 inotify 监视器中运行。
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Cloud or self-hosted knowledge for AI agents: hybrid search, reranking, GraphRAG, scoped MCP tools.
Private, multimodal knowledge store for agents: hybrid search with cited, provenance-backed results.
Your personal library, readable by AI agents: durable snapshots, hybrid search, 46 MCP tools.
Search your knowledge bases from any AI assistant using hybrid RAG.
Related MCP Servers
- FlicenseAqualityDmaintenanceProvides semantic vector search over local codebases via MCP, enabling hybrid search (dense + sparse + RRF) for any MCP client like GitHub Copilot or Claude Desktop.58-
- AlicenseNot gradedqualityDmaintenanceLocal-first MCP server enabling cross-modal search across text, images, documents, video, and audio transcripts. Provides 26 tools for ingesting, searching, and navigating local file systems with a 3-stage pipeline including reranking.3MIT
- AlicenseNot gradedqualityBmaintenanceEnables coding agents to search local repositories through hybrid keyword and embedding retrieval, read matched chunks, and list indexed repos via MCP, without API keys or cloud services.MIT
- FlicenseNot gradedqualityAmaintenanceEnables AI agents and MCP hosts to query locally indexed notes, docs, chat logs, and other files via hybrid vector/BM25 retrieval with section-level citations. Exposes tools, resources, and prompts for searching and asking over the indexed content.-