Skip to main content
Glama
deenesjakoruzh
ltaysh0

sage-mcp

by ltaysh0
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

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 플래그는 Jinja2 템플릿을 통해 결과를 렌더링합니다. 두 가지 내장 템플릿이 포함되어 있습니다:

이름

설명

blockquote

각 청크를 ### 헤딩 아래에 전체 파일 경로와 함께 인용문으로 들여쓰기 (기본값)

table

점수, KB, 전체 파일 경로, 잘린 발췌문이 포함된 간결한 마크다운 표

사용자 지정 템플릿을 작성하려면 sage_mcp/templates/에서 내장 템플릿을 복사하고 --template을 통해 파일 경로를 전달하세요. 다음 변수를 사용할 수 있습니다:

변수

타입

설명

query

str

검색 쿼리

results

list[dict]

각 항목은 score, file_path, kb, text, text_safe, metadata를 가짐

duplicates_removed

int

필터링된 중복 청크 수

각 결과의 text_safe는 줄바꿈을 공백으로 축소하고 파이프 문자를 이스케이프 처리한 청크 텍스트로, 마크다운 표 셀 내부에서 사용하기에 안전합니다. 원본 서식을 유지해야 하는 인용문이나 코드 블록 렌더링에는 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로 전환 (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