sage-mcp

Гибридный семантический поиск (плотные векторы + BM25) по локальным базам знаний и кодовым базам.

Стек: LlamaIndex · Qdrant (локальный встроенный) · Эмбеддинги OpenAI · 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

uv автоматически загрузит Python 3.11, если он еще не установлен.

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. Включены два встроенных шаблона:

Чтобы создать собственный шаблон, скопируйте встроенный из sage_mcp/templates/ и передайте путь к файлу через --template. Доступны следующие переменные:

Поле text_safe для каждого результата — это текст фрагмента, в котором символы переноса строки заменены на пробелы, а символы вертикальной черты экранированы — это безопасно для использования внутри ячейки markdown-таблицы. Используйте text для оформления в виде цитаты или блока кода, где необходимо сохранить исходное форматирование.

Список баз знаний

sage list-kbs

MCP (доступ для ИИ-агентов)

Добавьте в конфигурацию вашего 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.