MCP Server with FAISS for RAG

用于 RAG 的 FAISS MCP 服务

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

功能

• 提供 MCP 端点的 FastAPI 服务
• 集成 FAISS 向量数据库
• 文档分块与嵌入
• GitHub Move 文件提取与处理
• 集成 LLM，支持完整的 RAG 工作流
• 简单的客户端示例
• 示例文档

安装

使用 pipx（推荐）

pipx 是一种帮助你在隔离环境中安装和运行 Python 应用的工具。

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

# On macOS
brew install pipx
pipx ensurepath

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

# On Windows with pip
pip install pipx
pipx ensurepath

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

# Navigate to the directory containing the mcp_server folder
cd /path/to/mcp-server-project

# Install in editable mode
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 文件

# Download Move files with default settings
mcp-download --query "use sui" --output-dir docs/move_files

# Download with more options
mcp-download --query "module sui::coin" --max-results 50 --new-index --verbose

改进的 GitHub 搜索与索引（推荐）

# Search GitHub and index files with default settings
mcp-search-index --keywords "sui move"

# Search multiple keywords and customize options
mcp-search-index --keywords "sui move,move framework" --max-repos 30 --output-results --verbose

# Save search results and use a custom index location
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 文件建立索引

# Index files in the default location
mcp-index

# Index with custom options
mcp-index --docs-dir path/to/files --index-file path/to/index.bin --verbose

查询向量数据库

# Basic query
mcp-query "What is a module in Sui Move?"

# Advanced query with options
mcp-query "How do I define a struct in Sui Move?" -k 3 -f

使用集成 LLM 的 RAG

# Basic RAG query (will use simulated LLM if no API key is provided)
mcp-rag "What is a module in Sui Move?"

# Using with a specific LLM API
mcp-rag "How do I define a struct in Sui Move?" --api-key your_api_key --top-k 3

# Output as JSON for further processing
mcp-rag "What are the benefits of sui::coin?" --output-json > rag_response.json

运行服务

# Start the server with default settings
mcp-server

# Start with custom settings
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 文件并填充向量数据库：

# Download Move files with default query "use sui"
./run.sh --download-move

# Customize the search query
./run.sh --download-move --github-query "module sui::coin" --max-results 50

# Download, index, and start the server
./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?"

# With more options
python local_query.py -k 3 -f "How to define a struct in Sui Move?"

使用集成 LLM 的 RAG

# Direct RAG query with an LLM
python rag_integration.py "What is a module in Sui Move?" --index-file data/faiss_index.bin

# With API key (if you have one)
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. 网页抓取回退方案：当 API 方法失败或未提供令牌时使用

要配置 GitHub 令牌，请将其设置在 .env 文件中，或设为环境变量：

GITHUB_TOKEN=your_github_token_here

项目结构

mcp_server/
├── __init__.py             # Package initialization
├── main.py                # Main server file
├── mcp_api.py             # MCP API implementation
├── index_move_files.py    # File indexing utility
├── local_query.py         # Local query utility
├── download_move_files.py # GitHub Move file extractor
├── rag_integration.py     # LLM integration for RAG
├── pyproject.toml         # Package configuration
├── requirements.txt       # Dependencies
├── .env.example           # Example environment variables
├── README.md              # This file
├── data/                  # Storage for the FAISS index
├── docs/                  # Sample documents
│   └── move_files/        # Downloaded Move files
├── models/                # Model implementations
│   └── vector_store.py    # FAISS vector store implementation
└── utils/
    ├── document_processor.py  # Document processing utilities
    └── github_extractor.py    # GitHub file extraction utilities

扩展项目

要扩展此概念验证项目：

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

许可证

MIT