sage-mcp

Hybride semantische Suche (dichter Vektor + BM25) über lokale Wissensdatenbanken und Codebasen.

Stack: LlamaIndex · Qdrant (lokal eingebettet) · OpenAI-Embeddings · FastMCP

Einrichtung

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

uv lädt Python 3.11 automatisch herunter, falls es noch nicht installiert ist.

Related MCP server: okf-tools

Indexierung

# Index all configured KBs
sage index

# Index one KB only
sage index --kb homelab

# Force full re-index (ignore cache)
sage index --force

Status

# Diff KB files vs cache without embedding
sage status

# Single KB
sage status --kb homelab

Suche

# 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-Vorlagen

Das --markdown-Flag rendert Ergebnisse über eine Jinja2-Vorlage. Zwei integrierte Vorlagen sind enthalten:

Um eine benutzerdefinierte Vorlage zu schreiben, kopieren Sie eine integrierte Vorlage aus sage_mcp/templates/ und übergeben Sie den Dateipfad über --template. Die folgenden Variablen sind verfügbar:

Das text_safe jedes Ergebnisses ist der Chunk-Text, bei dem Zeilenumbrüche auf Leerzeichen reduziert und Pipe-Zeichen maskiert wurden – sicher für die Verwendung innerhalb einer Markdown-Tabellenzelle. Verwenden Sie text für Blockzitate oder gerahmte Code-Renderings, bei denen die ursprüngliche Formatierung beibehalten werden soll.

Wissensdatenbanken auflisten

sage list-kbs

MCP (Zugriff für KI-Agenten)

Fügen Sie dies zu Ihrer MCP-Client-Konfiguration hinzu (verwenden Sie absolute Pfade):

{
  "mcpServers": {
    "sage-mcp": {
      "command": "/path/to/sage-mcp/.venv/bin/sage-mcp",
      "args": ["--config", "/path/to/sage-mcp/config.yaml"]
    }
  }
}

Das --config-Flag ist optional; ohne dieses sucht der Server nach config.yaml im Arbeitsverzeichnis.

Bereitgestellte Tools:

• search_kb(query, kb?, top_k?, filter_type?, filter_status?) — gibt {results: [...], duplicates_removed: N} zurück

• list_knowledge_bases() — listet konfigurierte Wissensdatenbanken auf

Konfiguration

Bearbeiten Sie config.yaml, um Wissensdatenbanken hinzuzufügen oder das Embedding-Backend zu wechseln. Verwenden Sie config-example.yaml als Vorlage.

Wechsel zu Ollama (sobald nomic-embed-text mit GPU-Beschleunigung läuft):

embedding:
  provider: ollama
  model: nomic-embed-text
  base_url: http://<ollama-ip>:11434

Führen Sie dann sage index --force aus, um alles neu einzubetten.

Inkrementelle Updates

Der Indexer verfolgt einen Content-Hash pro Datei in pipeline_cache/<kb-name>/hashes.json. Ein erneuter Aufruf von sage index bettet nur Dateien neu ein, die sich geändert haben. Sicher für die Ausführung per Cron oder inotify-Überwachung.