sage-mcp

Búsqueda semántica híbrida (vector denso + BM25) sobre bases de conocimiento y bases de código locales.

Stack: LlamaIndex · Qdrant (local embebido) · Embeddings de OpenAI · FastMCP

Configuración

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 descargará Python 3.11 automáticamente si no está instalado ya.

Related MCP server: okf-tools

Indexación

# Index all configured KBs
sage index

# Index one KB only
sage index --kb homelab

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

Estado

# Diff KB files vs cache without embedding
sage status

# Single KB
sage status --kb homelab

Búsqueda

# 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

Plantillas Markdown

La bandera --markdown renderiza los resultados mediante una plantilla de Jinja2. Se incluyen dos plantillas integradas:

Para escribir una plantilla personalizada, copie una integrada desde sage_mcp/templates/ y pase la ruta del archivo mediante --template. Las siguientes variables están disponibles:

El text_safe de cada resultado es el texto del fragmento con los saltos de línea colapsados a espacios y los caracteres de barra vertical escapados: seguro para usar dentro de una celda de tabla Markdown. Use text para renderizado de citas o bloques de código donde se deba preservar el formato original.

Listar KBs

sage list-kbs

MCP (acceso para agentes de IA)

Añada a la configuración de su cliente MCP (use rutas absolutas):

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

La bandera --config es opcional; sin ella, el servidor busca config.yaml en su directorio de trabajo.

Herramientas expuestas:

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

• list_knowledge_bases() — lista las KBs configuradas

Configuración

Edite config.yaml para añadir KBs o cambiar el backend de embedding. Use config-example.yaml como plantilla.

Cambiar a Ollama (una vez que nomic-embed-text esté ejecutándose con aceleración por GPU):

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

Luego ejecute sage index --force para volver a embeber todo.

Actualizaciones incrementales

El indexador rastrea un hash de contenido por archivo en pipeline_cache/<kb-name>/hashes.json. Volver a ejecutar sage index solo vuelve a embeber los archivos que han cambiado. Es seguro ejecutarlo en un cron o mediante un observador inotify.