Local Faiss MCP

🚀 本地FAISS MCP服務器

本地FAISS MCP服務器是一個基於Model Context Protocol（MCP）的服務器，它使用FAISS提供本地向量數據庫功能，適用於檢索增強生成（RAG）應用程序。該服務器可以獨立運行，也可以與任何MCP兼容的AI代理或客戶端集成，為用戶提供高效的文檔索引和搜索服務。

🚀 快速開始

# 安裝
pip install local-faiss-mcp

# 索引文檔
local-faiss index document.pdf

# 搜索
local-faiss search "What is this document about?"

或者與Claude Code一起使用 - 配置MCP客戶端（請參閱與MCP客戶端的配置）並嘗試：

使用ingest_document工具處理：./path/to/document.pdf
然後使用query_rag_store搜索："How does FAISS perform similarity search?"

Claude將從你的向量存儲中檢索相關的文檔塊，並使用它們來回答你的問題。

✨ 主要特性

核心功能

• 本地向量存儲：使用FAISS進行高效的相似性搜索，無需外部依賴。
• 文檔攝取：自動對文檔進行分塊和嵌入，以便存儲。
• 語義搜索：使用自然語言和句子嵌入進行文檔查詢。
• 持久存儲：將索引和元數據保存到磁盤。
• MCP兼容性：可與任何MCP兼容的AI代理或客戶端配合使用。

v0.2.0亮點

• CLI工具：提供local-faiss命令，用於獨立的索引和搜索。
• 文檔格式：原生支持PDF/TXT/MD格式，通過pandoc支持DOCX/HTML/EPUB等格式。
• 重新排序：採用兩階段的檢索和重新排序，以獲得更好的結果。
• 自定義嵌入：可選擇任何Hugging Face嵌入模型。
• MCP提示：內置用於答案提取和摘要的提示。

📦 安裝指南

⚡️ 升級？ 運行 pip install --upgrade local-faiss-mcp

從PyPI安裝（推薦）

pip install local-faiss-mcp

可選：擴展格式支持

對於DOCX、HTML、EPUB等40多種格式，需要安裝pandoc：

# macOS
brew install pandoc

# Linux
sudo apt install pandoc

# 或者從以下網址下載：https://pandoc.org/installing.html

注意：PDF、TXT和MD格式無需pandoc即可使用。

從源代碼安裝

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

💻 使用示例

運行服務器

安裝完成後，你可以通過以下三種方式運行服務器：

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

命令行參數：

• --index-dir：存儲FAISS索引和元數據文件的目錄（默認：當前目錄）
• --embed：Hugging Face嵌入模型名稱（默認：all-MiniLM-L6-v2）
• --rerank：啟用使用指定交叉編碼器模型的重新排序（默認：BAAI/bge-reranker-base）

使用自定義嵌入模型：

# 使用更大、更準確的模型
local-faiss-mcp --index-dir ./.vector_store --embed all-mpnet-base-v2

# 使用多語言模型
local-faiss-mcp --index-dir ./.vector_store --embed paraphrase-multilingual-MiniLM-L12-v2

# 使用任何Hugging Face句子轉換器模型
local-faiss-mcp --index-dir ./.vector_store --embed sentence-transformers/model-name

使用重新排序以獲得更好的結果：

重新排序使用交叉編碼器模型對FAISS結果進行重新排序，以提高相關性。這種兩階段的“檢索和重新排序”方法在生產搜索系統中很常見。

# 使用默認模型（BAAI/bge-reranker-base）啟用重新排序
local-faiss-mcp --index-dir ./.vector_store --rerank

# 使用特定的重新排序模型
local-faiss-mcp --index-dir ./.vector_store --rerank cross-encoder/ms-marco-MiniLM-L-6-v2

# 結合自定義嵌入和重新排序
local-faiss-mcp --index-dir ./.vector_store --embed all-mpnet-base-v2 --rerank BAAI/bge-reranker-base

重新排序的工作原理：

1. FAISS檢索出比請求數量多10倍的頂級候選者。
2. 交叉編碼器對每個候選者與查詢進行評分。
3. 根據相關性得分對結果進行重新排序。
4. 返回前k個最相關的結果。

流行的重新排序模型：

• BAAI/bge-reranker-base - 平衡性能（默認）
• cross-encoder/ms-marco-MiniLM-L-6-v2 - 快速高效
• cross-encoder/ms-marco-TinyBERT-L-2-v2 - 非常快，模型較小

服務器將：

• 如果索引目錄不存在，則創建該目錄。
• 從{index-dir}/faiss.index加載現有的FAISS索引（或創建一個新的）。
• 從{index-dir}/metadata.json加載文檔元數據（或創建新的）。
• 通過stdin/stdout監聽MCP工具調用。

可用工具

服務器提供兩個用於文檔管理的工具：

1. ingest_document

將文檔攝取到向量存儲中。

參數：

• document（必需）：要攝取的文本內容或文件路徑。
• source（可選）：文檔來源的標識符（默認："unknown"）。

自動檢測：如果document看起來像文件路徑，將自動解析。

支持的格式：

• 原生：TXT、MD、PDF
• 使用pandoc：DOCX、ODT、HTML、RTF、EPUB等40多種格式

示例：

{
  "document": "FAISS is a library for efficient similarity search...",
  "source": "faiss_docs.txt"
}

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

2. query_rag_store

查詢向量存儲以獲取相關的文檔塊。

參數：

• query（必需）：搜索查詢文本。
• top_k（可選）：返回的結果數量（默認：3）。

示例：

{
  "query": "How does FAISS perform similarity search?",
  "top_k": 5
}

可用提示

服務器提供MCP提示，幫助從檢索到的文檔中提取答案和總結信息：

1. extract-answer

從檢索到的文檔塊中提取最相關的答案，並提供適當的引用。

參數：

• query（必需）：原始用戶查詢或問題。
• chunks（必需）：檢索到的文檔塊，作為JSON數組，包含字段：text、source、distance。

用例：查詢RAG存儲後，使用此提示獲取格式良好的答案，引用來源並解釋相關性。

在Claude中的示例工作流程：

1. 使用query_rag_store工具檢索相關塊。
2. 使用extract-answer提示處理查詢和結果。
3. 獲取帶有引用和解釋的全面答案。

2. summarize-documents

從多個文檔塊中創建聚焦的摘要。

參數：

• topic（必需）：要總結的主題或主題。
• chunks（必需）：要總結的文檔塊，作為JSON數組。
• max_length（可選）：摘要的最大長度（默認：200）。

用例：將從多個檢索到的文檔中合成信息，形成簡潔的摘要。

示例用法：

在Claude Code中，使用query_rag_store檢索文檔後，可以使用以下提示：

使用extract-answer提示處理：
- query: "What is FAISS?"
- chunks: [query_rag_store的JSON結果]

這些提示將引導大語言模型根據你的向量存儲數據提供結構化、有引用支持的答案。

命令行界面

local-faiss CLI提供獨立的文檔索引和搜索功能。

索引命令

從命令行索引文檔：

# 索引單個文件
local-faiss index document.pdf

# 索引多個文件
local-faiss index doc1.pdf doc2.txt doc3.md

# 索引文件夾中的所有文件
local-faiss index documents/

# 遞歸索引
local-faiss index -r documents/

# 使用通配符模式索引
local-faiss index "docs/**/*.pdf"

配置：CLI自動使用以下位置的MCP配置：

1. ./.mcp.json（本地/項目特定）
2. ~/.claude/.mcp.json（Claude Code配置）
3. ~/.mcp.json（備用）

如果沒有配置文件，將創建./.mcp.json，使用默認設置（./.vector_store）。

支持的格式：

• 原生：TXT、MD、PDF（始終可用）
• 使用pandoc：DOCX、ODT、HTML、RTF、EPUB等。
  • 安裝：brew install pandoc（macOS）或apt install pandoc（Linux）

搜索命令

搜索已索引的文檔：

# 基本搜索
local-faiss search "What is FAISS?"

# 獲取更多結果
local-faiss search -k 5 "similarity search algorithms"

結果顯示：

• 源文件路徑
• FAISS距離得分
• 重新排序得分（如果在MCP配置中啟用）
• 文本預覽（前300個字符）

CLI特性

• ✅ 增量索引：添加到現有索引，不覆蓋。
• ✅ 進度輸出：顯示每個文件的索引進度。
• ✅ 共享配置：使用與MCP服務器相同的設置。
• ✅ 自動檢測：支持通配符模式和遞歸文件夾。
• ✅ 格式支持：原生處理PDF、TXT、MD；使用pandoc支持DOCX等。

📚 詳細文檔

與MCP客戶端的配置

Claude Code

將此服務器添加到你的Claude Code MCP配置（.mcp.json）中：

用戶範圍配置 (~/.claude/.mcp.json)：

{
  "mcpServers": {
    "local-faiss-mcp": {
      "command": "local-faiss-mcp"
    }
  }
}

使用自定義索引目錄：

{
  "mcpServers": {
    "local-faiss-mcp": {
      "command": "local-faiss-mcp",
      "args": [
        "--index-dir",
        "/home/user/vector_indexes/my_project"
      ]
    }
  }
}

使用自定義嵌入模型：

{
  "mcpServers": {
    "local-faiss-mcp": {
      "command": "local-faiss-mcp",
      "args": [
        "--index-dir",
        "./.vector_store",
        "--embed",
        "all-mpnet-base-v2"
      ]
    }
  }
}

啟用重新排序：

{
  "mcpServers": {
    "local-faiss-mcp": {
      "command": "local-faiss-mcp",
      "args": [
        "--index-dir",
        "./.vector_store",
        "--rerank"
      ]
    }
  }
}

完整配置，包含嵌入和重新排序：

{
  "mcpServers": {
    "local-faiss-mcp": {
      "command": "local-faiss-mcp",
      "args": [
        "--index-dir",
        "./.vector_store",
        "--embed",
        "all-mpnet-base-v2",
        "--rerank",
        "BAAI/bge-reranker-base"
      ]
    }
  }
}

項目特定配置 (./.mcp.json 在你的項目中)：

{
  "mcpServers": {
    "local-faiss-mcp": {
      "command": "local-faiss-mcp",
      "args": [
        "--index-dir",
        "./.vector_store"
      ]
    }
  }
}

替代方法：使用Python模塊（如果命令不在PATH中）：

{
  "mcpServers": {
    "local-faiss-mcp": {
      "command": "python",
      "args": ["-m", "local_faiss_mcp", "--index-dir", "./.vector_store"]
    }
  }
}

Claude Desktop

將此服務器添加到你的Claude Desktop配置中：

{
  "mcpServers": {
    "local-faiss-mcp": {
      "command": "local-faiss-mcp",
      "args": ["--index-dir", "/path/to/index/directory"]
    }
  }
}

🔧 技術細節

架構

• 嵌入模型：可通過--embed標誌配置（默認：all-MiniLM-L6-v2，384維）。
  • 支持任何Hugging Face句子轉換器模型。
  • 自動檢測嵌入維度。
  • 模型選擇與索引一起持久化。
• 索引類型：FAISS IndexFlatL2，用於精確的L2距離搜索。
• 分塊：將文檔分割成約500個單詞的塊，重疊50個單詞。
• 存儲：索引保存為faiss.index，元數據保存為metadata.json。

選擇嵌入模型

不同的模型有不同的權衡：

模型	維度	速度	質量	使用場景
all-MiniLM-L6-v2	384	快	好	默認，平衡性能
all-mpnet-base-v2	768	中等	更好	更高質量的嵌入
paraphrase-multilingual-MiniLM-L12-v2	384	快	好	多語言支持
all-MiniLM-L12-v2	384	中等	更好	相同大小下更好的質量

重要提示：一旦使用特定模型創建了索引，後續運行必須使用相同的模型。服務器將檢測維度不匹配併發出警告。

開發

獨立測試

在不使用MCP基礎設施的情況下測試FAISS向量存儲功能：

source venv/bin/activate
python test_standalone.py

此測試：

• 初始化向量存儲。
• 攝取示例文檔。
• 執行語義搜索查詢。
• 測試持久性和重新加載。
• 清理測試文件。

單元測試

運行完整的測試套件：

pytest tests/ -v

運行特定的測試文件：

# 測試嵌入模型功能
pytest tests/test_embedding_models.py -v

# 運行獨立集成測試
python tests/test_standalone.py

測試套件包括：

• test_embedding_models.py：對自定義嵌入模型、維度檢測和兼容性進行全面測試。
• test_standalone.py：不使用MCP基礎設施的端到端集成測試。

📄 許可證

本項目採用MIT許可證。