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许可证。