基于 FAISS 的 MCP 服务器，用于 RAG

本项目提供了一个机器会话协议 (MCP) 服务器的概念验证实现，该服务器允许 AI 代理查询向量数据库并检索相关文档以用于检索增强生成 (RAG)。

特性

• 带有 MCP 端点的 FastAPI 服务器
• FAISS 向量数据库集成
• 文档分块和嵌入
• GitHub Move 文件提取和处理
• 用于完整 RAG 工作流程的 LLM 集成
• 简单的客户端示例
• 示例文档

安装

使用 pipx (推荐)

pipx 是一个工具，可以帮助你在隔离的环境中安装和运行 Python 应用程序。

1. 首先，安装 pipx（如果尚未安装）：

# 在 macOS 上
brew install pipx
pipx ensurepath

# 在 Ubuntu/Debian 上
sudo apt update
sudo apt install python3-pip python3-venv
python3 -m pip install --user pipx
python3 -m pipx ensurepath

# 在 Windows 上使用 pip
pip install pipx
pipx ensurepath

2. 直接从项目目录安装 MCP Server 包：

# 导航到包含 mcp_server 文件夹的目录
cd /path/to/mcp-server-project

# 以可编辑模式安装
pipx install -e .

3. (可选) 配置环境变量：
   • 复制 .env.example 到 .env
   • 添加你的 GitHub 令牌以获得更高的速率限制：GITHUB_TOKEN=your_token_here
   • 添加你的 OpenAI 或其他 LLM API 密钥以进行 RAG 集成：OPENAI_API_KEY=your_key_here

手动安装

如果你不想使用 pipx：

1. 克隆存储库
2. 安装依赖项：

cd mcp_server
pip install -r requirements.txt

使用方法 (使用 pipx)

使用 pipx 安装后，你将可以访问以下命令：

从 GitHub 下载 Move 文件

# 使用默认设置下载 Move 文件
mcp-download --query "use sui" --output-dir docs/move_files

# 使用更多选项下载
mcp-download --query "module sui::coin" --max-results 50 --new-index --verbose

改进的 GitHub 搜索和索引 (推荐)

# 搜索 GitHub 并使用默认设置索引文件
mcp-search-index --keywords "sui move"

# 搜索多个关键字并自定义选项
mcp-search-index --keywords "sui move,move framework" --max-repos 30 --output-results --verbose

# 保存搜索结果并使用自定义索引位置
mcp-search-index --keywords "sui coin,sui::transfer" --index-file custom/path/index.bin --output-results

mcp-search-index 命令提供增强的 GitHub 存储库搜索功能：

• 首先搜索存储库，然后递归提取 Move 文件
• 支持多个搜索关键字（逗号分隔）
• 智能过滤包含 "use sui" 引用的 Move 文件
• 始终在下载后重建向量数据库

索引 Move 文件

# 在默认位置索引文件
mcp-index

# 使用自定义选项索引
mcp-index --docs-dir path/to/files --index-file path/to/index.bin --verbose

查询向量数据库

# 基本查询
mcp-query "What is a module in Sui Move?"

# 带有选项的高级查询
mcp-query "How do I define a struct in Sui Move?" -k 3 -f

使用带有 LLM 集成的 RAG

# 基本 RAG 查询（如果没有提供 API 密钥，将使用模拟 LLM）
mcp-rag "What is a module in Sui Move?"

# 与特定的 LLM API 一起使用
mcp-rag "How do I define a struct in Sui Move?" --api-key your_api_key --top-k 3

# 输出为 JSON 以进行进一步处理
mcp-rag "What are the benefits of sui::coin?" --output-json > rag_response.json

运行服务器

# 使用默认设置启动服务器
mcp-server

# 使用自定义设置启动
mcp-server --host 127.0.0.1 --port 8080 --index-file custom/path/index.bin

手动使用 (不使用 pipx)

启动服务器

cd mcp_server
python main.py

服务器将在 http://localhost:8000 上启动

从 GitHub 下载 Move 文件

要从 GitHub 下载 Move 文件并填充你的向量数据库：

# 使用默认查询 "use sui" 下载 Move 文件
./run.sh --download-move

# 自定义搜索查询
./run.sh --download-move --github-query "module sui::coin" --max-results 50

# 下载、索引并启动服务器
./run.sh --download-move --index

你也可以直接使用 Python 脚本：

python download_move_files.py --query "use sui" --output-dir docs/move_files

索引文档

在查询之前，你需要索引你的文档。 你可以将你的文本文件 (.txt)、Markdown 文件 (.md) 或 Move 文件 (.move) 放在 docs 目录中。

要索引文档，你可以：

1. 使用带有 --index 标志的运行脚本：

./run.sh --index

2. 直接使用索引脚本：

python index_move_files.py --docs-dir docs/move_files --index-file data/faiss_index.bin

查询文档

你可以使用本地查询脚本：

python local_query.py "What is RAG?"

# 带有更多选项
python local_query.py -k 3 -f "How to define a struct in Sui Move?"

使用带有 LLM 集成的 RAG

# 使用 LLM 进行直接 RAG 查询
python rag_integration.py "What is a module in Sui Move?" --index-file data/faiss_index.bin

# 带有 API 密钥（如果你有）
OPENAI_API_KEY=your_key_here python rag_integration.py "How do coins work in Sui?"

MCP API 端点

MCP API 端点位于 /mcp/action。 你可以使用它来执行不同的操作：

• retrieve_documents: 检索查询的相关文档
• index_documents: 索引目录中的文档

示例：

curl -X POST "http://localhost:8000/mcp/action" -H "Content-Type: application/json" -d '{"action_type": "retrieve_documents", "payload": {"query": "What is RAG?", "top_k": 3}}'

完整的 RAG 管道

完整的 RAG（检索增强生成）管道的工作方式如下：

1. 搜索查询: 用户提交一个问题
2. 检索: 系统在向量数据库中搜索相关文档
3. 上下文形成: 检索到的文档被格式化为提示
4. LLM 生成: 提示与检索到的上下文一起发送到 LLM
5. 增强的响应: LLM 根据检索到的信息提供答案

此工作流程已在 rag_integration.py 模块中完全实现，可以通过命令行或作为库在你的应用程序中使用。

GitHub Move 文件提取

该系统可以根据搜索查询从 GitHub 提取 Move 文件。 它实现了两种方法：

1. GitHub API (首选): 需要 GitHub 令牌以获得更高的速率限制
2. Web 抓取回退: 当 API 方法失败或未提供令牌时使用

要配置你的 GitHub 令牌，请在 .env 文件中或作为环境变量设置它：

GITHUB_TOKEN=your_github_token_here

项目结构

mcp_server/
├── __init__.py             # 包初始化
├── main.py                # 主服务器文件
├── mcp_api.py             # MCP API 实现
├── index_move_files.py    # 文件索引实用程序
├── local_query.py         # 本地查询实用程序
├── download_move_files.py # GitHub Move 文件提取器
├── rag_integration.py     # 用于 RAG 的 LLM 集成
├── pyproject.toml         # 包配置
├── requirements.txt       # 依赖项
├── .env.example           # 示例环境变量
├── README.md              # 此文件
├── data/                  # FAISS 索引的存储
├── docs/                  # 示例文档
│   └── move_files/        # 下载的 Move 文件
├── models/                # 模型实现
│   └── vector_store.py    # FAISS 向量存储实现
└── utils/
    ├── document_processor.py  # 文档处理实用程序
    └── github_extractor.py    # GitHub 文件提取实用程序

扩展项目

要扩展此概念验证：

1. 添加身份验证和安全功能
2. 实现更复杂的文档处理
3. 添加对更多文档类型的支持
4. 与其他 LLM 提供商集成
5. 添加监控和日志记录
6. 改进 Move 语言解析以进行更结构化的数据提取

许可证

MIT