带有 FAISS 的 MCP 服务器用于 RAG
该项目提供了机器对话协议 (MCP) 服务器的概念验证实现，该服务器允许 AI 代理查询矢量数据库并检索检索增强生成 (RAG) 的相关文档。
特征
- 带有 MCP 端点的 FastAPI 服务器
- FAISS矢量数据库集成
- 文档分块和嵌入
- GitHub Move 文件提取和处理
- LLM 集成以实现完整的 RAG 工作流程
- 简单客户端示例
- 示例文件
安装
使用 pipx（推荐）
pipx是一个帮助您在隔离环境中安装和运行 Python 应用程序的工具。
- 首先，如果你没有 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
- 直接从项目目录安装 MCP 服务器包：
# Navigate to the directory containing the mcp_server folder
cd /path/to/mcp-server-project
# Install in editable mode
pipx install -e .
- （可选）配置环境变量：
- 将
.env.example复制到.env - 添加你的 GitHub 令牌以获得更高的速率限制：
GITHUB_TOKEN=your_token_here - 添加您的 OpenAI 或其他 LLM API 密钥以进行 RAG 集成：
OPENAI_API_KEY=your_key_here
手动安装
如果您不想使用 pipx：
- 克隆存储库
- 安装依赖项：
cd mcp_server
pip install -r requirements.txt
与 pipx 一起使用
使用 pipx 安装后，您将可以访问以下命令：
从 GitHub 下载移动文件
# 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 存储库搜索功能：
- 首先搜索存储库，然后递归提取移动文件
- 支持多个搜索关键字（逗号分隔）
- 智能过滤包含“use sui”引用的移动文件
- 下载后总是重建矢量数据库
索引移动文件
# 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
使用 RAG 与 LLM 集成
# 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 下载移动文件
要从 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目录中。
要索引文档，您可以：
- 使用带有
--index标志的运行脚本：
- 直接使用索引脚本：
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?"
使用 RAG 与 LLM 集成
# 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（检索增强生成）流程的工作原理如下：
- 搜索查询：用户提交问题
- 检索：系统在矢量数据库中搜索相关文档
- 上下文形成：检索到的文档被格式化为提示
- LLM 生成：提示与检索到的上下文一起发送到 LLM
- 增强响应：LLM 根据检索到的信息提供答案
此工作流程在rag_integration.py模块中完全实现，可以通过命令行使用，也可以作为您自己的应用程序中的库使用。
GitHub 移动文件提取
系统可以根据搜索查询从 GitHub 中提取 Move 文件。它实现了两种方法：
- GitHub API （首选）：需要 GitHub 令牌才能获得更高的速率限制
- Web Scraping fallback ：当 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
扩展项目
扩展此概念验证：
- 添加身份验证和安全功能
- 实施更复杂的文档处理
- 添加对更多文档类型的支持
- 与其他 LLM 提供商整合
- 添加监控和日志记录
- 改进 Move 语言解析以实现更结构化的数据提取
执照
麻省理工学院