Local FAISS MCP Server

本地FAISS MCP服务器

   ](https://badge.fury.io/py/local-faiss-mcp)

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

demo

特性

核心能力

• 本地矢量存储：使用FAISS进行高效的相似性搜索，无需外部依赖
• 文档摄取：自动将文档分块并嵌入以供存储
• 语义搜索：使用带有句子嵌入的自然语言查询文档
• 永久存储：索引和元数据保存到磁盘
• MCP兼容：可与任何兼容MCP的AI代理或客户端配合使用

v0.2.0亮点

• CLI工具: local-faiss 独立索引和搜索命令
• 文件格式：原生PDF/TXT/MD支持，DOCX/HTML/EPUB和pandoc
• 重新排序：两阶段检索和重新排序以获得更好的结果
• 自定义嵌入：选择任何拥抱面部嵌入模型
• 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客户端（请参阅 配置)并尝试：

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：拥抱面部嵌入模型名称（默认值： 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. 返回Top-k最相关的结果

流行的重新排名模型：

• BAAI/bge-reranker-base -良好平衡（默认）
• cross-encoder/ms-marco-MiniLM-L-6-v2 -快速高效
• cross-encoder/ms-marco-TinyBERT-L-2-v2 -速度很快，型号较小

服务器将：

• 如果索引目录不存在，则创建该目录
• 从加载现有的FAISS索引 {index-dir}/faiss.index （或创建一个新的）
• 从加载文档元数据 {index-dir}/metadata.json （或创建新）
• 通过stdin/stdout监听MCP工具调用

可用工具

服务器提供两种文档管理工具：

1.ingest_文件

将文档摄取到矢量存储中。

参数：

• document （必需）：要摄取的文本内容或文件路径
• source （可选）：文档源的标识符（默认值：“未知”）

自动检测：如果 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.提取答案

从检索到的具有适当引用的文档块中提取最相关的答案。

论据：

• query （必填）：原始用户查询或问题
• chunks （必填）：以JSON数组形式检索文档块，其中包含字段： text, source, distance

用例： 查询RAG存储后，使用此提示获得一个格式良好的答案，其中引用了来源并解释了相关性。

Claude中的示例工作流：

1. 使用 query_rag_store 检索相关块的工具
2. 使用 extract-answer 提示查询和结果
3. 通过引用获得全面的答案

2.总结文件

从多个文档块中创建一个重点摘要。

论据：

• 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]

提示将指导LLM根据您的矢量存储数据提供结构化的、引用支持的答案。

命令行界面

这 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 （克劳德代码配置）
3. ~/.mcp.json （回退）

如果不存在配置，则创建 ./.mcp.json 使用默认设置(./.vector_store).

支持的格式：

• 原生：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；DOCX+与pandoc

MCP客户端配置

克劳德代码

将此服务器添加到您的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配置中：

{
  "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

选择嵌入模型

不同的模型提供了不同的权衡：

重要提示： 使用特定模型创建索引后，必须在后续运行中使用相同的模型。服务器将检测到维度不匹配并警告您。

发展

独立测试

在没有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_嵌入_模型.py：对自定义嵌入模型、维度检测和兼容性进行全面测试
• test_standalone.py：无MCP基础设施的端到端集成测试

许可证

麻省理工学院