Servidor MCP con FAISS para RAG

Este proyecto proporciona una implementación de prueba de concepto de un servidor de Protocolo de conversación de máquina (MCP) que permite a un agente de IA consultar una base de datos vectorial y recuperar documentos relevantes para la generación aumentada por recuperación (RAG).

Características

• Servidor FastAPI con puntos finales MCP

• Integración de la base de datos vectorial FAISS

• Fragmentación e incrustación de documentos

• Extracción y procesamiento de archivos de GitHub Move

• Integración de LLM para un flujo de trabajo completo de RAG

• Ejemplo de cliente simple

• Documentos de muestra

Related MCP server: AivisSpeech MCP Server

Instalación

Uso de pipx (recomendado)

pipx es una herramienta que le ayuda a instalar y ejecutar aplicaciones Python en entornos aislados.

1. Primero, instala pipx si no lo tienes:

# 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. Instale el paquete del servidor MCP directamente desde el directorio del proyecto:

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

# Install in editable mode
pipx install -e .

3. (Opcional) Configurar variables de entorno:

   • Copiar .env.example a .env

   • Agregue su token de GitHub para límites de velocidad más altos: GITHUB_TOKEN=your_token_here

   • Agregue su clave API de OpenAI u otra LLM para la integración de RAG: OPENAI_API_KEY=your_key_here

Instalación manual

Si prefieres no usar pipx:

1. Clonar el repositorio

2. Instalar dependencias:

cd mcp_server
pip install -r requirements.txt

Uso con pipx

Después de instalar con pipx, tendrá acceso a los siguientes comandos:

Descargar archivos Move desde 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

Búsqueda e indexación de GitHub mejoradas (recomendado)

# 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

El comando mcp-search-index proporciona capacidades mejoradas de búsqueda en el repositorio de GitHub:

• Primero busca en los repositorios y luego extrae recursivamente los archivos Move

• Admite múltiples palabras clave de búsqueda (separadas por comas)

• Filtra de forma inteligente los archivos Move que contienen referencias "use sui"

• Siempre reconstruye la base de datos vectorial después de descargarla

Indexación de archivos de movimiento

# 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

Consulta de la base de datos de vectores

# 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

Uso de RAG con la integración de 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

Ejecución del servidor

# 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

Uso manual (sin pipx)

Iniciando el servidor

cd mcp_server
python main.py

El servidor se iniciará en http://localhost:8000

Descargar archivos Move desde GitHub

Para descargar archivos Move desde GitHub y completar su base de datos de vectores:

# 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

También puedes utilizar el script de Python directamente:

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

Indexación de documentos

Antes de realizar consultas, debe indexar sus documentos. Puede colocar sus archivos de texto (.txt), Markdown (.md) o Move (.move) en el directorio docs .

Para indexar los documentos, puede:

1. Utilice el script de ejecución con el indicador --index :

./run.sh --index

2. Utilice el script de índice directamente:

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

Consulta de documentos

Puede utilizar el script de consulta local:

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

Uso de RAG con la integración de 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?"

Punto final de la API de MCP

El punto final de la API de MCP está disponible en /mcp/action . Puede usarlo para realizar diferentes acciones:

• retrieve_documents : Recuperar documentos relevantes para una consulta

• index_documents : Indexa documentos de un directorio

Ejemplo:

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}}'

Tubería RAG completa

El proceso completo de RAG (Recuperación-Generación Aumentada) funciona de la siguiente manera:

1. Consulta de búsqueda : El usuario envía una pregunta

2. Recuperación : El sistema busca en la base de datos de vectores documentos relevantes

3. Formación de contexto : los documentos recuperados se formatean en un mensaje de aviso.

4. Generación de LLM : el mensaje se envía a un LLM con el contexto recuperado

5. Respuesta mejorada : El LLM proporciona una respuesta basada en la información recuperada

Este flujo de trabajo está completamente implementado en el módulo rag_integration.py , que puede utilizarse a través de la línea de comandos o como una biblioteca en sus propias aplicaciones.

Extracción de archivos de movimiento de GitHub

El sistema puede extraer archivos Move de GitHub mediante consultas de búsqueda. Implementa dos métodos:

1. API de GitHub (preferida): requiere un token de GitHub para límites de velocidad más altos

2. Respaldo de Web Scraping : se utiliza cuando falla el método API o cuando no se proporciona ningún token

Para configurar su token de GitHub, configúrelo en el archivo .env o como una variable de entorno:

GITHUB_TOKEN=your_github_token_here

Estructura del proyecto

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

Ampliación del proyecto

Para ampliar esta prueba de concepto:

1. Agregar funciones de autenticación y seguridad

2. Implementar un procesamiento de documentos más sofisticado

3. Añadir soporte para más tipos de documentos

4. Integración con otros proveedores de LLM

5. Añadir monitorización y registro

6. Mejorar el análisis del lenguaje Move para una extracción de datos más estructurada

Licencia

Instituto Tecnológico de Massachusetts (MIT)