Local FAISS MCP Server

License: MIT

Python 3.10+

Tests

PyPI version

A Model Context Protocol (MCP) 서버로, FAISS를 사용하여 Retrieval-Augmented Generation (RAG) 애플리케이션을 위한 로컬 벡터 데이터베이스 기능을 제공합니다.

demo

기능(Features)

핵심 기능(Core Capabilities)

로컬 벡터 저장소: 외부 종속성 없이 FAISS를 사용하여 효율적인 유사도 검색을 수행합니다.
문서 수집(Document Ingestion): 문서를 자동으로 청크(chunks)로 나누고 임베딩하여 저장합니다.
의미론적 검색(Semantic Search): 문장 임베딩을 사용하여 자연어로 문서에 대한 질의를 합니다.
영구 저장소(Persistent Storage): 인덱스와 메타데이터가 디스크에 저장됩니다.
MCP 호환: 모든 MCP와 호환되는 AI 에이전트 또는 클라이언트와 작동합니다.

v0.2.0 주요 업데이트 내용(v0.2.0 Highlights)

CLI 도구: 독립적인 인덱싱 및 검색을 위한 local-faiss 명령어 제공
문서 형식 지원: 네이티브 PDF/TXT/MD를 지원하며, DOCX/HTML/EPUB은 pandoc을 통해 지원합니다.
재순위화(Re-ranking): 더 나은 결과를 위해 2단계 검색 및 재순위화를 수행합니다.
사용자 정의 임베딩: 원하는 Hugging Face 임베딩 모델을 선택할 수 있습니다.
MCP 프롬프트: 답변 추출 및 요약에 대한 내장 프롬프트를 제공합니다.

빠른 시작(Quickstart)

# 설치
pip install local-faiss-mcp

...

또는 Claude Code와 함께 사용하려면 - MCP 클라이언트를 구성하세요(Configuration 참조) 그리고 다음을 시도해 보세요:

ingest_document 도구를 사용하여: ./path/to/document.pdf
그런 다음 query_rag_store를 사용하여 검색합니다: 

### 소스에서 가져오기

```bash
git clone https://github.com/nonatofabio/local_faiss_mcp.git
cd local_faiss_mcp
pip install -e .

사용법 (Usage)

서버 실행하기 (Running the Server)

설치 후, 세 가지 방법으로 서버를 실행할 수 있습니다:

1. 설치된 명령어 사용 (가장 쉬움):

local-faiss-mcp --index-dir /path/to/index/directory

2. Python 모듈로 사용:

python -m local_faiss_mcp --index-dir /path/to/index/directory

3. 개발/테스트용:

python local_faiss_mcp/server.py --index-dir /path/to/index/directory

명령줄 인수 (Command-line Arguments):

--index-dir: FAISS 인덱스 및 메타데이터 파일을 저장할 디렉토리 (기본값: 현재 디렉토리)
--embed: Hugging Face 임베딩 모델 이름 (기본값: all-MiniLM-L6-v2)
--rerank: 지정된 크로스 인코더(cross-encoder) 모델을 사용하여 재순위화(re-ranking) 활성화 (기본값: BAAI/bge-reranker-base)

사용자 정의 임베딩 모델 사용:

# 더 크고 정확한 모델 사용
local-faiss-mcp --index-dir ./.vector_store --embed all-mpnet-base-v2

더 나은 결과를 위한 재순위화(Re-ranking) 사용:

재순위화는 크로스 인코더 모델을 사용하여 FAISS 검색 결과를 재정렬하여 관련성(relevance)을 개선합니다. 이 2단계 '검색 및 재순위화 (retrieve and rerank)' 접근 방식은 프로덕션 검색 시스템에서 일반적입니다.

# 기본 모델(BAAI/bge-reranker-base)로 재순위화 활성화
local-faiss-mcp --index-dir ./.vector_store --rerank

재순위화 작동 방식:

FAISS가 상위 후보(요청된 개수보다 10배 많음)를 검색합니다.
크로스 인코더가 각 후보를 쿼리와 비교하여 점수를 매깁니다.
결과는 관련성 점수에 따라 재정렬됩니다.
가장 관련성이 높은 상위-k개의 결과가 반환됩니다.

사용 가능한 도구 (Available Tools)

이 서버는 문서 관리를 위해 두 가지 도구를 제공합니다:

1. ingest_document

문서를 벡터 스토어에 색인(ingest)합니다.

매개변수 (Parameters):

document (필수): 색인할 텍스트 내용 또는 파일 경로
source (선택): 문서 출처 식별자 (기본값: "unknown")

자동 감지 (Auto-detection): 만약 document가 파일 경로처럼 보이면 자동으로 파싱됩니다.

지원 형식 (Supported formats):

네이티브: TXT, MD, PDF
pandoc 사용 시: DOCX, ODT, HTML, RTF, EPUB 및 40개 이상의 형식

예시 (Examples):

{
  "document": "FAISS는 효율적인 유사성 검색을 위한 라이브러리입니다....",
  "source": "faiss_docs.txt"
...

{
  "document": "./documents/research_paper.pdf"
}

2. query_rag_store

벡터 스토어에서 관련 문서 청크를 조회합니다.

매개변수 (Parameters):

query (필수): 검색 질의 텍스트
top_k (선택): 반환할 결과 수 (기본값: 3)

예시 (Example):

{
  "query": "FAISS는 유사성 검색을 어떻게 수행하나요?",
  "top_k": 5
...

사용 가능한 프롬프트 (Available Prompts)

이 서버는 검색된 문서에서 답변을 추출하고 정보를 요약하는 데 도움을 주기 위해 MCP 프롬프트를 제공합니다:

1. extract-answer

검색된 문서 청크에서 적절한 인용과 함께 가장 관련성 높은 답변을 추출합니다.

인수 (Arguments):

query (필수): 원래 사용자 질의 또는 질문
chunks (필수): 필드(text, source, distance)를 가진 JSON 배열 형태의 검색된 문서 청크

사용 사례 (Use Case): RAG 스토어를 조회한 후, 이 프롬프트를 사용하여 출처를 인용하고 관련성을 설명하는 잘 형식화된 답변을 얻습니다.

Claude에서 예시 워크플로우:

query_rag_store 도구를 사용하여 관련 청크 검색
쿼리와 결과를 사용하여 extract-answer 프롬프트 사용
인용된 내용을 포함한 포괄적인 답변 얻기

2. summarize-documents

여러 문서 청크로부터 집중적인 요약 생성.

인수(Arguments):

topic (필수): 요약할 주제 또는 테마
chunks (필수): JSON 배열 형태로 요약할 문서 청크
max_length (선택): 단어 단위 최대 요약 길이 (기본값: 200)

사용 사례: 여러 검색된 문서에서 정보를 종합하여 간결한 요약으로 만듭니다.

예시 사용법:

Claude Code에서 query_rag_store로 문서를 검색한 후, 다음과 같은 프롬프트를 사용할 수 있습니다:

Use the extract-answer prompt with:
- query: "What is FAISS?"
- chunks: [query_rag_store의 JSON 결과]

이 프롬프트는 LLM이 벡터 스토어 데이터에 기반하여 구조화되고 인용된 답변을 제공하도록 안내합니다.

커맨드 라인 인터페이스 (Command-Line Interface)

local-faiss CLI는 독립적인 문서 색인화 및 검색 기능을 제공합니다.

Index 명령어

커맨드 라인에서 문서를 색인화합니다:

# 단일 파일 색인화
local-faiss index document.pdf

...

설정(Configuration): CLI는 다음 위치의 MCP 설정을 자동으로 사용합니다:

./.mcp.json (로컬/프로젝트별)
~/.claude/.mcp.json (Claude Code 설정)
~/.mcp.json (폴백)

설정이 없으면, 기본 설정(./.vector_store)으로 ./.mcp.json을 생성합니다.

지원 형식(Supported formats):

네이티브: TXT, MD, PDF (항상 사용 가능)
pandoc 사용 시: DOCX, ODT, HTML, RTF, EPUB 등
- 설치: brew install pandoc (macOS) 또는 apt install pandoc (Linux)

Search 명령어

색인화된 문서를 검색합니다:

# 기본 검색
local-faiss search "What is FAISS?"

...

결과는 다음을 보여줍니다:

원본 파일 경로 (Source file path)
FAISS 거리 점수 (FAISS distance score)
재순위화 점수 (Re-rank score) (MCP 설정에서 활성화된 경우)
텍스트 미리보기 (Text preview) (첫 300자)

CLI 기능

✅ 증분 인덱싱 (Incremental indexing): 기존 인덱스에 추가하며 덮어쓰지 않음
✅ 진행률 출력 (Progress output): 파일별 인덱싱 진행 상황을 표시함
✅ 공유 설정 (Shared config): MCP 서버와 동일한 설정을 사용함
✅ 자동 감지 (Auto-detection): glob 패턴 및 재귀 폴더를 지원함
✅ 형식 지원 (Format support): PDF, TXT, MD를 네이티브로 처리하며, DOCX+는 pandoc으로 처리함

MCP 클라이언트와 함께 설정하기

Claude Code

이 서버를 Claude Code MCP 설정(.mcp.json)에 추가하세요:

사용자 전체 설정 (User-wide configuration) (~/.claude/.mcp.json):

{
  "mcpServers": {
    "local-faiss-mcp": {
...

커스텀 인덱스 디렉터리를 사용할 경우 (With custom index directory):

{
  "mcpServers": {
    "local-faiss-mcp": {
...

커스텀 임베딩 모델을 사용할 경우 (With custom embedding model):

{
  "mcpServers": {
    "local-faiss-mcp": {
...

재랭킹(re-ranking) 기능을 활성화할 경우 (With re-ranking enabled):

{
  "mcpServers": {
    "local-faiss-mcp": {
...

임베딩 및 재랭킹을 모두 포함한 전체 설정 (Full configuration with embedding and re-ranking):

{
  "mcpServers": {
    "local-faiss-mcp": {
...

프로젝트별 설정 (Project-specific configuration) (./.mcp.json in your project):

{
  "mcpServers": {
    "local-faiss-mcp": {
...

대안: Python 모듈 사용 (Alternative: Using Python module) (명령어가 PATH에 없는 경우):

{
  "mcpServers": {
    "local-faiss-mcp": {
...

Claude Desktop

이 서버를 Claude Desktop 설정에 추가하세요:

{
  "mcpServers": {
    "local-faiss-mcp": {
...

아키텍처 (Architecture)

임베딩 모델 (Embedding Model): --embed 플래그를 통해 설정 가능 (기본값: 384 차원의 all-MiniLM-L6-v2)
- 모든 Hugging Face sentence-transformers 모델 지원
- 임베딩 차원을 자동으로 감지함
- 선택된 모델은 인덱스와 함께 유지됨
인덱스 유형 (Index Type): 정확한 L2 거리 검색을 위한 FAISS IndexFlatL2
청킹 (Chunking): 문서는 50단어 중첩(overlap)을 가진 약 500단어 청크로 분할됨
저장소 (Storage): 인덱스는 faiss.index로, 메타데이터는 metadata.json으로 저장됨

임베딩 모델 선택하기

다양한 모델들은 서로 다른 장단점을 제공합니다:

모델(Model)	차원(Dimensions)	속도(Speed)	품질(Quality)	사용 사례(Use Case)
`all-MiniLM-L6-v2`	384	빠름(Fast)	좋음(Good)	기본값, 균형 잡힌 성능(Default, balanced performance)
...
중요: 특정 모델로 인덱스를 생성한 후에는 다음 실행에서도 반드시 동일한 모델을 사용해야 합니다. 서버는 차원 불일치(dimension mismatches)를 감지하고 경고할 것입니다.

개발(Development)

독립형 테스트(Standalone Test)

MCP 인프라 없이 FAISS 벡터 스토어 기능에 대한 테스트:

source venv/bin/activate
python test_standalone.py

이 테스트는 다음을 수행합니다:

벡터 스토어 초기화(Initializes the vector store)
샘플 문서 수집(Ingests sample documents)
의미 검색 쿼리 수행(Performs semantic search queries)
영속성 및 재로드 테스트(Tests persistence and reload)
테스트 파일 정리(Cleans up test files)

단위 테스트(Unit Tests)

전체 테스트 스위트 실행:

pytest tests/ -v

특정 테스트 파일 실행:

# 임베딩 모델 기능 테스트
pytest tests/test_embedding_models.py -v

...

테스트 스위트에는 다음이 포함됩니다:

test_embedding_models.py: 사용자 정의 임베딩 모델, 차원 감지 및 호환성에 대한 포괄적인 테스트
test_standalone.py: MCP 인프라가 없는 엔드투엔드 통합 테스트(End-to-end integration test)

Local FAISS MCP 서버

요약

핵심 포인트