En la era de las aplicaciones de IA que evolucionan rápidamente, la necesidad de sistemas que puedan combinar el conocimiento estático del dominio con información web en tiempo real nunca ha sido tan grande. Los modelos tradicionales de generación aumentada por recuperación (RAG) a menudo dependen de datos preindexados, lo que limita su capacidad de respuesta a nuevos desarrollos. El servidor MCP-RAG cierra esta brecha al integrar la búsqueda semántica por vectores (a través de Qdrant) con capacidades de búsqueda web en tiempo real (a través de Scrapeless), ofreciendo una base lista para producción para sistemas de respuesta a preguntas inteligentes. Ya sea que seas una empresa construyendo agentes de conocimiento internos o un desarrollador experimentando con la integración de LLM, esta guía te acompañará a través de la configuración y uso completo de MCP-RAG, asegurando que estés preparado para desplegar un sistema de conocimiento de IA moderno y responda rápidamente.

¿Qué es el Servidor MCP-RAG?

El Servidor MCP-RAG es un sistema basado en TypeScript que combina capacidades de búsqueda por vectores con búsqueda web en tiempo real para crear un sistema de conocimiento de IA mejorado. Proporciona tres herramientas principales:

1. Recuperación de Preguntas Frecuentes por Aprendizaje Automático - Búsqueda semántica a través de tu base de datos de vectores
2. Adición de Documentos - Amplía tu base de conocimiento con nueva información
3. Búsqueda Web - Obtén información actual de Internet

Este sistema resuelve limitaciones críticas de IA: conocimiento desactualizado, falta de experiencia en el dominio y recuperación ineficiente de información.

Introducción a Scrapeless: Motor de mejora inteligente web de RAG

Scrapeless Google Search Scraping API es una poderosa API de extracción web que proporciona acceso estable a los resultados de búsqueda sin el riesgo de ser bloqueado por rastreadores tradicionales.

Por qué Scrapeless es esencial para los sistemas RAG

Los sistemas RAG tradicionales están limitados por sus bases de conocimiento estáticas. Scrapeless transforma el Servidor MCP-RAG al:

1. Recuperación de información en tiempo real: Acceso a la información más reciente de la web
2. Mejora de la base de conocimiento: Actualiza continuamente tu base de datos de vectores con datos actuales
3. Búsqueda complementaria: Rellena vacíos cuando el conocimiento interno es insuficiente
4. Perspectivas diversas: Busca desde diferentes regiones geográficas e idiomas

¿Cómo funciona Scrapeless en MCP-RAG?

Scrapeless se integra con el Servidor MCP-RAG a través de una clase de encapsulación TypeScript llamada ScrapelessClient para lograr las siguientes capacidades:

export class ScrapelessClient {
  private api: AxiosInstance;
  
  constructor(config: ScrapelessConfig) {
    this.api = axios.create({
      baseURL: config.baseURL,
      headers: {
        "Content-Type": "application/json",
        "x-api-token": config.token,
      },
    });
  }
  
  async searchWeb(params: WebSearchParams) {
    try {
      const response = await this.api.post("/api/v1/scraper/request", {
        actor: "scraper.google.search",
        input: {
          q: params.query,
          gl: params.country || "us",
          hl: params.language || "en",
          google_domain: params.domain || "google.com"
        }
      });
      
      return {
        query: params.query,
        results: response.data
      };
    } catch (error) {
      // Manejo de errores...
    }
  }
}

Funciones Avanzadas Soportadas

Guía de Despliegue del Sistema Inteligente de Respuestas a Preguntas (Basado en Búsqueda por Vectores + Búsqueda Web en Tiempo Real)

Paso 1: Inicializar estructura del proyecto e instalar dependencias

Clona y configura el proyecto:

git clone git@github.com:scrapeless-ai/mcp-rag-server.git
cd mcp-rag-server

Analiza la estructura del proyecto:

mcp-rag-server/
├── src/
│   ├── config.ts
│   ├── index.ts
│   ├── server.ts
│   ├── qdrant-client.ts
│   └── scrapeless-client.ts
├── package.json
├── tsconfig.json
└── .env

Instala dependencias:

npm install

💡Problema Resuelto:
Asegúrate de que el entorno del proyecto TypeScript esté listo, las dependencias necesarias (como @modelcontextprotocol/sdk, axios, zod, etc.) se han integrado y las definiciones de tipo requeridas para el desarrollo también se han configurado automáticamente.

Paso 2: Configuración del Entorno

Crea el archivo `.env`:
QDRANT_URL=http://localhost:6333
QDRANT_API_KEY=
QDRANT_COLLECTION=ml_faq_collection
```plaintext
SCRAPELESS_KEY=tu_clave_api_scrapeless
SCRAPELESS_BASE_URL=https://api.scrapeless.com

Entendiendo la configuración (de config.ts):
const QDRANT_URL = process.env.QDRANT_URL?.trim() || "http://localhost:6333";
const QDRANT_API_KEY = process.env.QDRANT_API_KEY?.trim() || "";
const QDRANT_COLLECTION = process.env.QDRANT_COLLECTION?.trim() || "ml_faq_collection";
const SCRAPELESS_KEY = process.env.SCRAPELESS_KEY?.trim();
const SCRAPELESS_BASE_URL = process.env.SCRAPELESS_BASE_URL?.trim() || "https://api.scrapeless.com";

**💡Problema resuelto:**

Proporcionar los parámetros de conexión correctos para dependencias externas (base de datos vectorial Qdrant y búsqueda en tiempo real Scrapeless). Los valores predeterminados y el procesamiento trim() están integrados en el código de configuración para prevenir errores de formato de variable. Si falta la clave Scrapeless, se emitirá una advertencia.

### Paso 3: Configurar la base de datos vectorial Qdrant

**Iniciar Qdrant con Docker:**

Descargar la imagen de Qdrant

docker pull qdrant/qdrant

Ejecutar el contenedor de Qdrant con persistencia de datos

docker run -d
--name qdrant-server
-p 6333:6333
-p 6334:6334
-v $(pwd)/qdrant_storage:/qdrant/storage
qdrant/qdrant

**Crear una colección de vectores de FAQ:**

curl -X PUT 'http://localhost:6333/collections/ml_faq_collection'
-H 'Content-Type: application/json'
--data-raw '{
"vectors": {
"size": 1536,
"distance": "Cosine"
}
}'

**💡Problema resuelto:**

Configurar el almacenamiento de recuperación semántica de vectores, utilizar 1536 dimensiones y similitud coseno, y ser compatible con la salida del generador de incrustaciones y las llamadas de QdrantClient.

### Paso 4: Integrar búsqueda web en tiempo real Scrapeless

**Obtención de la clave API de Scrapeless:**

1. Visita [Scrapeless](https://app.scrapeless.com/passport/login?utm_source=official&utm_medium=blog&utm_campaign=mcprag) y crea una cuenta.
2. Recupera tu token API desde el panel de control.

![Recupera tu token API](https://assets.scrapeless.com/prod/posts/mcp-rag-server-with-scrapeless/8c967ead40663ba1ba4d552fc94e8303.png)

3. Agrégalo al archivo .env bajo SCRAPELESS_KEY.

**Probar la conexión de Scrapeless:**

Probar la conexión API (opcional)

curl -X POST 'https://api.scrapeless.com/api/v1/scraper/request'
-H 'Content-Type: application/json'
-H 'x-api-token: TU_CLAVE_API'
-d '{"actor": "scraper.google.search", "input": {"q": "consulta de prueba"}}'

**Problema resuelto:**

Este paso asegura que tu API de Scrapeless esté correctamente configurada. El sistema incluye validación para comprobar si la clave API está establecida, evitando errores en tiempo de ejecución durante las búsquedas en la web.

### Paso 5: Compilar el proyecto TypeScript

Compilar TypeScript a JavaScript:

npm run build

Lo que sucede durante la compilación (de package.json):

```language
{
  "scripts": {
    "build": "tsc && chmod 755 build/index.js",
    "start": "node build/index.js"
  }
}

Verificar la salida de la compilación:

ls build/
# Debería mostrar: index.js, server.js, config.js, qdrant-client.js, scrapeless-client.js

Problema resuelto:

Este paso compila TypeScript a JavaScript y asegura que el punto de entrada principal sea ejecutable. El proceso de construcción genera módulos ES (como se especifica en "type": "module" en package.json) compatibles con Node.js.

Paso 6: Iniciar el servidor MCP

Ejecutar el servidor:
npm start

Lo que sucede durante el inicio (de index.ts):

async function main() {
  try {
    console.log("Iniciando el servidor MCP Agentic RAG...");
    const transport = new StdioServerTransport();
    await server.connect(transport);
    console.log("El servidor MCP está en funcionamiento en el puerto 8080");
  } catch (error) {
    console.error("Error fatal en main():", error);
    process.exit(1);
  }
}

Problema resuelto:

Este paso lanza el servidor MCP usando el transporte STDIO para la comunicación. El servidor se inicializa con un manejo adecuado de errores y registro.

Siguiendo los seis pasos anteriores, habrás construido un sistema de preguntas y respuestas impulsado por IA con:

• Capacidades de QA semántica (impulsadas por la base de datos vectorial Qdrant)
• Aumento web en tiempo real (a través de la integración de la API de Scrapeless)
• Infraestructura lista para LLM (basada en el estándar del protocolo MCP)
  Esto forma una base sólida para que empresas o desarrolladores implementen rápidamente un sistema RAG (Generación Aumentada por Recuperación) listo para producción.

Explicación detallada de componentes centrales

QdrantClient: motor de procesamiento de vectores

QdrantClient proporciona funciones de generación de incrustaciones e interacción con la base de datos vectorial. El ejemplo utiliza un método de incrustación determinista simple para demostración:

private generateEmbedding(text: string): number[] {
  const seed = [...text].reduce((sum, char) => sum + char.charCodeAt(0), 0) % 10000;
  const vector: number[] = [];
  
  let value = seed;
  for (let i = 0; i < 1536; i++) {
    value = (value * 48271) % 2147483647;
    vector.push((value / 2147483647) * 2 - 1);
  }
  
  return vector;
}

Características clave:

• Generación de incrustaciones deterministas simples
• Operaciones de upsert para agregar documentos
• Búsqueda semántica con umbral de puntuación configurable

- Manejo adecuado de errores y respuestas alternas

### ScrapelessClient: Interfaz del motor de búsqueda web
ScrapelessClient accede a la API de Scrapeless para implementar la búsqueda en la web y admite parámetros de búsqueda avanzados:

async searchWeb(params: WebSearchParams) {
try {
if (!this.api.defaults.headers.common["x-api-token"]) {
throw new Error("La clave de API de Scrapeless no está configurada");
}

const response = await this.api.post("/api/v1/scraper/request", {
  actor: "scraper.google.search",
  input: {
    q: params.query,
    gl: params.country || "us",
    hl: params.language || "en",
    google_domain: params.domain || "google.com"
  }
});

return {
  query: params.query,
  results: response.data
};

} catch (error) {
// Manejo de errores...
}
}

Características clave:
- Integración de búsqueda de Google a través de Scrapeless
- País, idioma y dominio configurables
- Manejo integral de errores
- Validación de clave de API

### Herramientas del Servidor MCP

El archivo server.ts define tres herramientas principales:

1. recuperación-faq-aprendizaje-maquina:
- Busca en la base de datos de vectores conceptos de ML
- Utiliza coincidencias de similitud semántica
- Devuelve resultados formateados con puntajes

2. agregar-documento-a-faq:
- Agrega nuevos documentos a la base de conocimiento
- Soporta metadatos (categoría, fuente, etiquetas)
- Manejo adecuado de errores con respuestas detalladas

3. búsqueda-web-sin-scrapeless:
- Realiza búsquedas web a través de la API de Scrapeless
- Parámetros de búsqueda configurables
- Recuperación de información en tiempo real

## Guía de Uso: Usando el sistema con Scrapeless
### Ejemplos Básicos de Uso

Buscar en la base de conocimiento:

Usa recuperación-faq-aprendizaje-maquina para encontrar información sobre redes neuronales

Agregar nueva información:

Usa agregar-documento-a-faq para añadir esto:
Texto: "Los bosques aleatorios son métodos de aprendizaje en conjunto..."
Categoría: "Métodos de Conjunto"
Etiquetas: ["bosques aleatorios", "aprendizaje en conjunto"]

Buscar en la web con Scrapeless:
```language
Usa búsqueda-web-sin-scrapeless para encontrar desarrollos recientes en IA

Uso avanzado de Scrapeless:

Usa búsqueda-web-sin-scrapeless con:
Consulta: "Últimas funciones de PyTorch"
País: "uk"
Idioma: "en"
Dominio: "google.co.uk"

Flujos de Trabajo Avanzados con Integración Scrapeless

Mejora de la base de conocimiento:

1. Usa búsqueda-web-sin-scrapeless para encontrar "últimos modelos de transformers 2024"
2. Usa agregar-documento-a-faq para añadir hallazgos relevantes
3. Usa recuperación-faq-aprendizaje-maquina para verificar que la información es searchable

Verificación de información:

1. Usa recuperación-faq-aprendizaje-maquina para comprobar conocimiento existente
2. Usa búsqueda-web-sin-scrapeless para encontrar información actual
3. Compara y actualiza la base de conocimiento en consecuencia

Construcción de conocimiento multilingüe:

1. Usa búsqueda-web-sin-scrapeless con país="de" e idioma="de" para encontrar investigaciones de IA en alemán
2. Usa agregar-documento-a-faq para добавить резюме на переведенном языке
3. Construye una base de conocimiento multilingüe

Integración con Claude Desktop

El proyecto incluye una configuración de muestra para la integración de Claude Desktop:

{
  "mcpServers": {
    "MCP-RAG-app": {
      "command": "node",
      "args": ["your-path/to/build/index.js"],
      "host": "127.0.0.1",
      "port": 8080,
      "timeout": 30000,
      "env": {
        "QDRANT_URL": "http://localhost:6333",
        "QDRANT_API_KEY": "",
        "QDRANT_COLLECTION": "ml_faq_collection",
        "SCRAPELESS_KEY": "SCRAPELESS_KEY"
      }
    }
  }
}

Problemas Comunes y Soluciones

1. Errores de compilación:

• Asegúrate de que la versión de Node.js sea >= 18
• Comprueba la compilación de TypeScript: npx tsc --noEmit

2. Errores en tiempo de ejecución:

• Verifica que Qdrant esté en ejecución: curl http://localhost:6333/health
• Asegúrate de que las variables de entorno estén configuradas correctamente
• Asegúrate de que la clave de API de Scrapeless sea válida

3. Problemas específicos de Scrapeless:

• Verifica que la clave de API esté configurada correctamente en el entorno
• Comprueba cuotas y límites de API en el panel de control de Scrapeless
• Asegúrate de que la configuración del endpoint de API sea correcta

4. Problemas de conexión:

• Verifica que los puertos estén disponibles (6333 para Qdrant)
• Comprueba la configuración del firewall
• Asegúrate de que los contenedores de Docker estén en ejecución

Beneficios del Sistema Combinado

La integración de Scrapeless con Qdrant crea un poderoso sistema híbrido:

1. Conocimiento Estático + Dinámico: Combina tu base de conocimiento curada con datos web en tiempo real
2. Búsqueda Inteligente: Usa búsqueda semántica para datos internos y búsqueda por palabras clave para contenido web
3. Mejora Continua: Actualiza automáticamente tu base de conocimiento con información fresca
4. Perspectiva Global: Accede a información de diferentes regiones e idiomas
5. Confiabilidad: Scrapeless asegura un acceso web consistente sin problemas de bloqueo

Conclusión

El servidor MCP-RAG y Scrapeless implementan un sistema de preguntas y respuestas inteligente altamente escalable y actualizado en tiempo real. Los valores centrales incluyen:

• Comprensión semántica: comprensión del contexto a través de la similitud vectorial
• Acceso a información en tiempo real: accede a Scrapeless para obtener el último contenido web
• Integración de protocolo estándar: utilizando el protocolo MCP, es fácil conectarse a plataformas como Claude
• Configuración flexible: colección de base de conocimiento personalizable y herramientas de búsqueda.
• Plataforma inteligente orientada al futuro: soporte para mejora dinámica del conocimiento, soporte multilingüe y rastreo inteligente web.

La adición de Scrapeless hace que el sistema ya no sea solo una base de conocimiento estática, sino un motor de conocimiento de IA con visión global y capacidades de aprendizaje continuo.