MCP 서버 임베딩
txtai 기반의 MCP(모델 컨텍스트 프로토콜) 서버 구현으로, 표준화된 인터페이스를 통해 의미 검색, 지식 그래프 기능, AI 기반 텍스트 처리를 제공합니다.
txtai의 힘: 올인원 임베딩 데이터베이스
이 프로젝트는 RAG를 위한 올인원 임베딩 데이터베이스인 txtai를 활용하여 의미 검색, 지식 그래프 구성, 언어 모델 워크플로를 활용합니다. txtai는 다음과 같은 몇 가지 주요 이점을 제공합니다.
- 통합 벡터 데이터베이스 : 벡터 인덱스, 그래프 네트워크 및 관계형 데이터베이스를 단일 플랫폼으로 결합합니다.
- 의미 검색 : 키워드가 아닌 의미에 기반한 정보 검색
- 지식 그래프 통합 : 데이터에서 지식 그래프를 자동으로 구축하고 쿼리합니다.
- 휴대용 지식 기반 : 쉽게 공유하고 로드할 수 있는 압축 아카이브(.tar.gz)로 전체 지식 기반을 저장합니다.
- 확장 가능한 파이프라인 시스템 : 통합 API를 통해 텍스트, 문서, 오디오, 이미지 및 비디오를 처리합니다.
- 로컬 우선 아키텍처 : 외부 서비스로 데이터를 전송하지 않고 모든 것을 로컬에서 실행합니다.
작동 원리
이 프로젝트에는 지식 기반 구축 도구와 MCP 서버가 포함되어 있습니다. 지식 기반 구축 도구는 지식 기반을 생성하고 관리하기 위한 명령줄 인터페이스입니다. MCP 서버는 지식 기반에 접근하기 위한 표준화된 인터페이스를 제공합니다.
지식 베이스를 구축하기 위해 반드시 지식 베이스 빌더 도구를 사용할 필요는 없습니다. txtai의 프로그래밍 인터페이스를 사용하여 Python 스크립트를 작성하거나 Jupyter Notebook을 사용하여 언제든지 지식 베이스를 구축할 수 있습니다. 지식 베이스가 txtai를 사용하여 구축된 경우 MCP 서버에서 로드할 수 있습니다. 더 좋은 점은 지식 베이스가 파일 시스템의 폴더이거나 내보낸 .tar.gz 파일일 수 있다는 것입니다. MCP 서버에 전달하기만 하면 자동으로 로드됩니다.
1. kb_builder를 사용하여 지식 기반 구축
kb_builder 모듈은 지식 기반을 만들고 관리하기 위한 명령줄 인터페이스를 제공합니다.
- 다양한 소스(파일, 디렉토리, JSON)의 문서 처리
- 텍스트 추출 및 임베딩 생성
- 지식 그래프를 자동으로 구축
- 휴대용 지식 기반 내보내기
기능이 제한되어 있을 수 있으며 현재는 편의를 위해서만 제공됩니다.
2. MCP 서버 시작
MCP 서버는 지식 기반에 액세스하기 위한 표준화된 인터페이스를 제공합니다.
- 의미 검색 기능
- 지식 그래프 쿼리 및 시각화
- 텍스트 처리 파이프라인(요약, 추출 등)
- 모델 컨텍스트 프로토콜을 완벽하게 준수합니다.
설치
권장 사항: Python 3.10 이상에서 uv 사용
최상의 환경을 위해 Python 3.10 이상에서 uv를 사용하는 것을 권장합니다. uv는 종속성 관리를 개선하고 일관된 동작을 보장합니다.
지엑스피1
참고 : 4.50.0 이상 버전에서 나타나는 transformers.agents.tools 관련 지원 중단 경고를 방지하기 위해 transformers를 4.49.0 버전으로 고정했습니다. 최신 버전의 transformers를 사용하는 경우 이러한 경고가 표시될 수 있지만 기능에는 영향을 미치지 않습니다.
콘다 사용하기
# Create a new conda environment (optional)
conda create -n embedding-mcp python=3.10
conda activate embedding-mcp
# Install from PyPI
pip install kb-mcp-server
출처에서
# Create a new conda environment
conda create -n embedding-mcp python=3.10
conda activate embedding-mcp
# Clone the repository
git clone https://github.com/Geeksfino/kb-mcp-server.git.git
cd kb-mcp-server
# Install dependencies
pip install -e .
uv 사용(더 빠른 대안)
# Install uv if not already installed
pip install uv
# Create a new virtual environment
uv venv
source .venv/bin/activate
# Option 1: Install from PyPI
uv pip install kb-mcp-server
# Option 2: Install from source (for development)
uv pip install -e .
uvx 사용(설치 필요 없음)
uvx를 사용하면 패키지를 설치하지 않고도 PyPI에서 직접 패키지를 실행할 수 있습니다.
# Run the MCP server
uvx --from kb-mcp-server@0.3.0 kb-mcp-server --embeddings /path/to/knowledge_base
# Build a knowledge base
uvx --from kb-mcp-server@0.3.0 kb-build --input /path/to/documents --config config.yml
# Search a knowledge base
uvx --from kb-mcp-server@0.3.0 kb-search /path/to/knowledge_base "Your search query"
명령줄 사용법
지식 기반 구축
PyPI에서 설치한 명령줄 도구, Python 모듈을 직접 사용하거나 편리한 셸 스크립트를 사용할 수 있습니다.
PyPI 설치 명령 사용
# Build a knowledge base from documents
kb-build --input /path/to/documents --config config.yml
# Update an existing knowledge base with new documents
kb-build --input /path/to/new_documents --update
# Export a knowledge base for portability
kb-build --input /path/to/documents --export my_knowledge_base.tar.gz
# Search a knowledge base
kb-search /path/to/knowledge_base "What is machine learning?"
# Search with graph enhancement
kb-search /path/to/knowledge_base "What is machine learning?" --graph --limit 10
uvx 사용(설치 필요 없음)
# Build a knowledge base from documents
uvx --from kb-mcp-server@0.3.0 kb-build --input /path/to/documents --config config.yml
# Update an existing knowledge base with new documents
uvx --from kb-mcp-server@0.3.0 kb-build --input /path/to/new_documents --update
# Export a knowledge base for portability
uvx --from kb-mcp-server@0.3.0 kb-build --input /path/to/documents --export my_knowledge_base.tar.gz
# Search a knowledge base
uvx --from kb-mcp-server@0.3.0 kb-search /path/to/knowledge_base "What is machine learning?"
# Search with graph enhancement
uvx --from kb-mcp-server@0.3.0 kb-search /path/to/knowledge_base "What is machine learning?" --graph --limit 10
Python 모듈 사용
# Build a knowledge base from documents
python -m kb_builder build --input /path/to/documents --config config.yml
# Update an existing knowledge base with new documents
python -m kb_builder build --input /path/to/new_documents --update
# Export a knowledge base for portability
python -m kb_builder build --input /path/to/documents --export my_knowledge_base.tar.gz
편의 스크립트 사용
저장소에는 지식 기반을 보다 쉽게 구축하고 검색할 수 있는 편리한 래퍼 스크립트가 포함되어 있습니다.
# Build a knowledge base using a template configuration
./scripts/kb_build.sh /path/to/documents technical_docs
# Build using a custom configuration file
./scripts/kb_build.sh /path/to/documents /path/to/my_config.yml
# Update an existing knowledge base
./scripts/kb_build.sh /path/to/documents technical_docs --update
# Search a knowledge base
./scripts/kb_search.sh /path/to/knowledge_base "What is machine learning?"
# Search with graph enhancement
./scripts/kb_search.sh /path/to/knowledge_base "What is machine learning?" --graph
더 많은 옵션을 보려면 ./scripts/kb_build.sh --help 또는 ./scripts/kb_search.sh --help 실행하세요.
MCP 서버 시작
PyPI 설치 명령 사용
# Start with a specific knowledge base folder
kb-mcp-server --embeddings /path/to/knowledge_base_folder
# Start with a given knowledge base archive
kb-mcp-server --embeddings /path/to/knowledge_base.tar.gz
uvx 사용(설치 필요 없음)
# Start with a specific knowledge base folder
uvx kb-mcp-server@0.2.6 --embeddings /path/to/knowledge_base_folder
# Start with a given knowledge base archive
uvx kb-mcp-server@0.2.6 --embeddings /path/to/knowledge_base.tar.gz
Python 모듈 사용
# Start with a specific knowledge base folder
python -m txtai_mcp_server --embeddings /path/to/knowledge_base_folder
# Start with a given knowledge base archive
python -m txtai_mcp_server --embeddings /path/to/knowledge_base.tar.gz
MCP 서버 구성
MCP 서버는 YAML 파일이 아닌 환경 변수나 명령줄 인수를 사용하여 구성됩니다. YAML 파일은 지식 기반 구축 중 txtai 구성 요소를 구성하는 데만 사용됩니다.
MCP 서버를 구성하는 방법은 다음과 같습니다.
# Start the server with command-line arguments
kb-mcp-server --embeddings /path/to/knowledge_base --host 0.0.0.0 --port 8000
# Or using uvx (no installation required)
uvx kb-mcp-server@0.2.6 --embeddings /path/to/knowledge_base --host 0.0.0.0 --port 8000
# Or using the Python module
python -m txtai_mcp_server --embeddings /path/to/knowledge_base --host 0.0.0.0 --port 8000
# Or use environment variables
export TXTAI_EMBEDDINGS=/path/to/knowledge_base
export MCP_SSE_HOST=0.0.0.0
export MCP_SSE_PORT=8000
python -m txtai_mcp_server
일반적인 구성 옵션:
--embeddings : 지식 기반 경로(필수)--host : 바인딩할 호스트 주소(기본값: localhost)--port : 수신할 포트(기본값: 8000)--transport : 사용할 전송 방식, 'sse' 또는 'stdio' (기본값: stdio)--enable-causal-boost : 관련성 점수 향상을 위해 인과 관계 부스트 기능을 활성화합니다.--causal-config : 사용자 정의 인과 부스트 구성 YAML 파일에 대한 경로
MCP 서버를 사용하도록 LLM 클라이언트 구성
LLM 클라이언트가 MCP 서버를 사용하도록 구성하려면 MCP 구성 파일을 만들어야 합니다. 다음은 mcp_config.json 파일의 예입니다.
서버를 직접 사용하기
가상 Python 환경을 사용하여 서버를 설치하는 경우 다음 구성을 사용할 수 있습니다. Claude와 같은 MCP 호스트는 가상 환경을 사용하는 경우 서버에 연결할 수 없으므로 예를 들어 "pip install" 또는 "uv pip install"을 수행한 가상 환경의 Python 실행 파일에 대한 절대 경로를 사용해야 합니다.
{
"mcpServers": {
"kb-server": {
"command": "/your/home/project/.venv/bin/kb-mcp-server",
"args": [
"--embeddings",
"/path/to/knowledge_base.tar.gz"
],
"cwd": "/path/to/working/directory"
}
}
}
시스템 기본 Python 사용
시스템 기본 Python을 사용하는 경우 다음 구성을 사용할 수 있습니다.
{
"rag-server": {
"command": "python3",
"args": [
"-m",
"txtai_mcp_server",
"--embeddings",
"/path/to/knowledge_base.tar.gz",
"--enable-causal-boost"
],
"cwd": "/path/to/working/directory"
}
}
또는 uvx를 사용하는 경우 "brew install uvx" 등을 통해 시스템에 uvx를 설치했거나 uvx를 설치하고 다음을 통해 전역적으로 접근 가능하게 했다고 가정합니다.
# Create a symlink to /usr/local/bin (which is typically in the system PATH)
sudo ln -s /Users/cliang/.local/bin/uvx /usr/local/bin/uvx
이렇게 하면 사용자별 설치에서 시스템 전체 위치로 연결되는 심볼릭 링크가 생성됩니다. Claude Desktop과 같은 macOS 애플리케이션의 경우, launchd 구성 파일을 생성하거나 편집하여 시스템 전체 PATH를 수정할 수 있습니다.
# Create a plist file to set environment variables for all GUI applications
sudo nano /Library/LaunchAgents/environment.plist
이 콘텐츠를 추가하세요:
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>Label</key>
<string>my.startup</string>
<key>ProgramArguments</key>
<array>
<string>sh</string>
<string>-c</string>
<string>launchctl setenv PATH $PATH:/Users/cliang/.local/bin</string>
</array>
<key>RunAtLoad</key>
<true/>
</dict>
</plist>
그런 다음 로드합니다.
sudo launchctl load -w /Library/LaunchAgents/environment.plist
하지만 이 설정을 적용하려면 컴퓨터를 다시 시작해야 합니다.
{
"mcpServers": {
"kb-server": {
"command": "uvx",
"args": [
"kb-mcp-server@0.2.6",
"--embeddings", "/path/to/knowledge_base",
"--host", "localhost",
"--port", "8000"
],
"cwd": "/path/to/working/directory"
}
}
}
이 구성 파일을 LLM 클라이언트가 접근할 수 있는 위치에 저장하고 클라이언트가 해당 구성 파일을 사용하도록 설정하세요. 정확한 구성 단계는 사용 중인 LLM 클라이언트에 따라 다릅니다.
고급 지식 기반 구성
txtai를 사용하여 지식 기반을 구축하려면 임베딩 프로세스의 다양한 측면을 제어하는 YAML 구성 파일이 필요합니다. 이 구성은 MCP 서버 자체가 아닌 kb_builder 도구에서 사용됩니다.
세분화/청킹 전략, 임베딩 모델, 스코어링 방법을 조정해야 할 수도 있고, 그래프 구성, 인과 부스팅, 하이브리드 검색 가중치 등을 구성해야 할 수도 있습니다.
다행히 txtai는 코딩이 필요 없는 강력한 YAML 구성 시스템을 제공합니다. 지식 기반 구축을 위한 포괄적인 구성의 예는 다음과 같습니다.
# Path to save/load embeddings index
path: ~/.txtai/embeddings
writable: true
# Content storage in SQLite
content:
path: sqlite:///~/.txtai/content.db
# Embeddings configuration
embeddings:
# Model settings
path: sentence-transformers/nli-mpnet-base-v2
backend: faiss
gpu: true
batch: 32
normalize: true
# Scoring settings
scoring: hybrid
hybridalpha: 0.75
# Pipeline configuration
pipeline:
workers: 2
queue: 100
timeout: 300
# Question-answering pipeline
extractor:
path: distilbert-base-cased-distilled-squad
maxlength: 512
minscore: 0.3
# Graph configuration
graph:
backend: sqlite
path: ~/.txtai/graph.db
similarity: 0.75 # Threshold for creating graph connections
limit: 10 # Maximum connections per node
구성 예제
src/kb_builder/configs 디렉토리에는 다양한 사용 사례와 스토리지 백엔드에 대한 구성 템플릿이 포함되어 있습니다.
스토리지 및 백엔드 구성
memory.yml : 메모리 내 벡터(개발 속도가 가장 빠르지만 지속성 없음)sqlite-faiss.yml : 콘텐츠용 SQLite + 벡터용 FAISS(로컬 파일 기반 지속성)postgres-pgvector.yml : PostgreSQL + pgvector(완전한 지속성을 갖춘 프로덕션 준비 완료)
도메인별 구성
base.yml : 기본 구성 템플릿code_repositories.yml : 코드 저장소에 최적화됨data_science.yml : 데이터 과학 문서용으로 구성됨general_knowledge.yml : 일반적인 지식 기반research_papers.yml : 학술 논문에 최적화됨technical_docs.yml : 기술 문서용으로 구성됨
다음을 자신의 구성을 위한 시작점으로 사용할 수 있습니다.
python -m kb_builder build --input /path/to/documents --config src/kb_builder/configs/technical_docs.yml
# Or use a storage-specific configuration
python -m kb_builder build --input /path/to/documents --config src/kb_builder/configs/postgres-pgvector.yml
고급 기능
지식 그래프 기능
MCP 서버는 txtai의 내장 그래프 기능을 활용하여 강력한 지식 그래프 기능을 제공합니다.
- 자동 그래프 구성 : 문서에서 자동으로 지식 그래프를 구축합니다.
- 그래프 탐색 : 관련 개념 및 문서 탐색
- 경로 찾기 : 서로 다른 정보 간의 연결을 발견합니다.
- 커뮤니티 감지 : 관련 정보 클러스터 식별
인과관계 강화 메커니즘
MCP 서버에는 인과 관계를 식별하고 우선순위를 지정하여 검색 관련성을 높이는 정교한 인과 관계 강화 메커니즘이 포함되어 있습니다.
- 패턴 인식 : 쿼리와 문서 모두에서 인과적 언어 패턴을 감지합니다.
- 다국어 지원 : 감지된 쿼리 언어에 따라 적절한 패턴을 자동으로 적용합니다.
- 구성 가능한 부스트 배수 : 다양한 유형의 인과 매치에 사용자 정의 가능한 부스트 계수가 적용됩니다.
- 향상된 관련성 : 인과 관계를 설명하는 결과가 검색 결과에서 우선적으로 표시됩니다.
이 메커니즘은 개념 간의 관계를 설명하는 콘텐츠를 표시하여 "왜" 및 "어떻게" 질문에 대한 응답을 크게 개선합니다. 인과 관계 부스팅 구성은 YAML 파일을 통해 고도로 사용자 정의 가능하므로 다양한 도메인과 언어에 맞게 조정할 수 있습니다.
특허
MIT 라이센스 - 자세한 내용은 라이센스 파일을 참조하세요.