Local FAISS MCP Server

本地 FAISS MCP 服务

一个模型上下文协议（MCP）服务，使用 FAISS 为检索增强生成（RAG）应用提供本地向量数据库功能。

功能

核心功能

• 本地向量存储：使用 FAISS 进行高效相似度搜索，无需外部依赖
• 文档导入：自动对文档分块并生成嵌入，以便存储
• 语义搜索：使用句子嵌入，通过自然语言查询文档
• 持久化存储：索引和元数据会保存到磁盘
• 兼容 MCP：可与任何兼容 MCP 的 AI Agent 或客户端配合使用

v0.2.0 亮点

• CLI 工具：使用 local-faiss 命令独立执行索引和搜索
• 文档格式：原生支持 PDF/TXT/MD，通过 pandoc 支持 DOCX/HTML/EPUB
• 重排序：采用两阶段检索与重排序，获得更好的结果
• 自定义嵌入：可选择任意 Hugging Face 嵌入模型
• MCP 提示词：内置用于答案提取和摘要生成的提示词

快速开始

# Install
pip install local-faiss-mcp

# Index documents
local-faiss index document.pdf

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

或者与 Claude Code 配合使用——配置 MCP 客户端（参见使用 MCP 客户端配置）并尝试：

Use the ingest_document tool with: ./path/to/document.pdf
Then use query_rag_store to search for: "How does FAISS perform similarity search?"

Claude 会从你的向量存储中检索相关文档块，并用它们回答你的问题。

安装

⚡️ 正在升级？ 运行 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

# Or download from: 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）

使用自定义嵌入模型：

# Use a larger, more accurate model
local-faiss-mcp --index-dir ./.vector_store --embed all-mpnet-base-v2

# Use a multilingual model
local-faiss-mcp --index-dir ./.vector_store --embed paraphrase-multilingual-MiniLM-L12-v2

# Use any Hugging Face sentence-transformers model
local-faiss-mcp --index-dir ./.vector_store --embed sentence-transformers/model-name

使用重排序获得更好的结果：

重排序使用交叉编码器模型对 FAISS 结果重新排序，以提高相关性。这种两阶段的“检索与重排序”方法常用于生产级搜索系统。

# Enable re-ranking with default model (BAAI/bge-reranker-base)
local-faiss-mcp --index-dir ./.vector_store --rerank

# Use a specific re-ranking model
local-faiss-mcp --index-dir ./.vector_store --rerank cross-encoder/ms-marco-MiniLM-L-6-v2

# Combine custom embedding and re-ranking
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 检索文档后，可以使用如下提示词：

Use the extract-answer prompt with:
- query: "What is FAISS?"
- chunks: [the JSON results from query_rag_store]

这些提示词将引导大模型根据向量存储中的数据，提供结构化且有引用支持的答案。

命令行界面

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

索引命令

从命令行创建文档索引：

# Index single file
local-faiss index document.pdf

# Index multiple files
local-faiss index doc1.pdf doc2.txt doc3.md

# Index all files in folder
local-faiss index documents/

# Index recursively
local-faiss index -r documents/

# Index with glob pattern
local-faiss index "docs/**/*.pdf"

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

1. ./.mcp.json（本地／项目专用）
2. ~/.claude/.mcp.json（Claude Code 配置）
3. ~/.mcp.json（备用配置）

如果不存在配置文件，则会使用默认设置（./.vector_store）创建 ./.mcp.json。

支持的格式：

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

搜索命令

搜索已建立索引的文档：

# Basic search
local-faiss search "What is FAISS?"

# Get more results
local-faiss search -k 5 "similarity search algorithms"

结果会显示：

• 源文件路径
• FAISS 距离分数
• 重排序分数（如果在 MCP 配置中启用）
• 文本预览（前 300 个字符）

CLI 功能

• ✅ 增量索引：添加到现有索引，不会覆盖
• ✅ 进度输出：显示每个文件的索引进度
• ✅ 共享配置：使用与 MCP 服务相同的设置
• ✅ 自动检测：支持 glob 模式和递归文件夹
• ✅ 格式支持：原生处理 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 sentence-transformers 模型
  • 自动检测嵌入维度
  • 模型选择会与索引一同保存
• 索引类型：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

运行指定测试文件：

# Test embedding model functionality
pytest tests/test_embedding_models.py -v

# Run standalone integration test
python tests/test_standalone.py

测试套件包括：

• test_embedding_models.py：全面测试自定义嵌入模型、维度检测和兼容性
• test_standalone.py：无需 MCP 基础设施的端到端集成测试

许可证

MIT