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

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テンプレートを使用して結果をレンダリングします。 2つの組み込みテンプレートが含まれています：

名前

説明

blockquote

各チャンクは、フルファイルパスを持つ ### 見出しの下に引用としてインデントされます（デフォルト）

table

スコア、KB、フルファイルパス、および切り詰められた抜粋を含むコンパクトな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 を使用してください。

KBの一覧表示

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() — 設定されたKBを一覧表示します

設定

config.yaml を編集してKBを追加したり、埋め込みバックエンドを切り替えたりします。テンプレートとして config-example.yaml を使用してください。

Ollamaへの切り替え (GPUアクセラレーションで nomic-embed-text が実行されている場合)：

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