Skip to main content
Glama
deenesjakoruzh
ltaysh0

sage-mcp

by ltaysh0
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

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: okf-tools

索引

# 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.j2

Markdown 模板

--markdown 标志通过 Jinja2 模板渲染结果。 包含两个内置模板：

名称

描述

blockquote

每个数据块在 ### 标题下缩进为引用块，并显示完整文件路径（默认）

table

包含分数、知识库、完整文件路径和截断摘要的紧凑 Markdown 表格

要编写自定义模板，请从 sage_mcp/templates/ 复制一个内置模板，并通过 --template 传递文件路径。可以使用以下变量：

变量

类型

描述

query

str

搜索查询

results

list[dict]

每个条目包含 score、file_path、kb、text、text_safe、metadata

duplicates_removed

int

过滤掉的重复数据块数量

每个结果的 text_safe 是将换行符折叠为空格并转义管道字符后的数据块文本——适合在 Markdown 表格单元格内使用。对于需要保留原始格式的引用块或围栏代码渲染，请使用 text。

列出知识库

sage list-kbs

MCP (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 监视器中运行。

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • RAG In A Box MCP Server

    DevNexsler
    F
    license
    Not graded
    quality
    B
    maintenance
    Enables any MCP-compatible AI assistant to search, filter, and retrieve information from a local document collection using a hybrid search pipeline with vector, BM25, reranking, and LLM enrichment.
    4
    -

  • RecallForge

    brianmeyer
    A
    license
    Not graded
    quality
    D
    maintenance
    Local-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.
    3
    MIT