Servidor MCP de Olostep

Docker Hub Versión de npm Licencia: ISC

Una implementación de servidor del Protocolo de Contexto de Modelo (MCP) que se integra con Olostep para web scraping, extracción de contenido y capacidades de búsqueda. Para configurar el servidor MCP de Olostep, necesitas tener una clave de API. Puedes obtener la clave de API registrándote en el sitio web de Olostep.

Características

• Extraer contenido de sitios web en HTML, Markdown, JSON o texto plano (con analizadores opcionales)

• Búsqueda web basada en analizadores con resultados estructurados

• Respuestas de IA con citas y salidas opcionales en formato JSON

• Extracción por lotes de hasta 10.000 URLs

• Rastreo autónomo de sitios desde una URL inicial

• Descubrimiento y mapeo de URLs de sitios web (con filtros de inclusión/exclusión)

• Enrutamiento de solicitudes específico por país para contenido geolocalizado

• Tiempos de espera configurables para sitios web con mucho JavaScript

• Manejo y reporte integral de errores

• Configuración sencilla de la clave de API

Related MCP server: Parallel Task MCP

Instalación

Existen varias formas de conectarse al servidor MCP de Olostep. Elige la que mejor se adapte a tu flujo de trabajo.

☁️ Punto final remoto (Recomendado)

La forma más sencilla: no requiere instalación local. Conéctate directamente a nuestro servidor MCP alojado:

https://mcp.olostep.com/mcp

La autenticación se realiza mediante un token Bearer en el encabezado Authorization usando tu clave de API de Olostep. Consulta la sección Configuración del cliente a continuación para ver ejemplos de configuración.

🐳 Docker Hub

Extrae y ejecuta la imagen oficial de Docker:

docker pull olostep/mcp-server

docker run -i --rm \
  -e OLOSTEP_API_KEY="your-api-key" \
  olostep/mcp-server

🔧 Construcción local de Docker

Si prefieres construir la imagen tú mismo desde el código fuente:

git clone https://github.com/olostep/olostep-mcp-server.git
cd olostep-mcp-server
npm install
npm run build
docker build -t olostep/mcp-server:local .

docker run -i --rm -e OLOSTEP_API_KEY="your-api-key" olostep/mcp-server:local

📦 npx

Ejecuta sin ninguna instalación usando npx:

env OLOSTEP_API_KEY=your-api-key npx -y olostep-mcp

En Windows (PowerShell):

$env:OLOSTEP_API_KEY = "your-api-key"; npx -y olostep-mcp

En Windows (CMD):

set OLOSTEP_API_KEY=your-api-key && npx -y olostep-mcp

O instálalo globalmente:

npm install -g olostep-mcp

Configuración del cliente

Cursor

La forma más fácil es usar el punto final remoto. Crea o edita .cursor/mcp.json en la raíz de tu proyecto:

{
  "mcpServers": {
    "olostep": {
      "url": "https://mcp.olostep.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY_HERE"
      }
    }
  }
}

Alternativa (local): Ve a Configuración de Cursor > Características > Servidores MCP, haz clic en "+ Agregar nuevo servidor MCP":

• Nombre: olostep

• Tipo: command

• Comando: env OLOSTEP_API_KEY=tu-clave-api npx -y olostep-mcp

Claude Desktop

Agrega esto a tu claude_desktop_config.json:

{
  "mcpServers": {
    "mcp-server-olostep": {
      "command": "npx",
      "args": ["-y", "olostep-mcp"],
      "env": {
        "OLOSTEP_API_KEY": "YOUR_API_KEY_HERE"
      }
    }
  }
}

Alternativa (Docker):

{
  "mcpServers": {
    "olostep": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "OLOSTEP_API_KEY=YOUR_API_KEY_HERE",
        "olostep/mcp-server"
      ]
    }
  }
}

O instálalo a través de la CLI de Smithery en la terminal de tu dispositivo:

npx -y @smithery/cli install @olostep/olostep-mcp-server --client claude

Claude Code

Agrega el punto final remoto a tu configuración MCP de Claude Code:

{
  "mcpServers": {
    "olostep": {
      "url": "https://mcp.olostep.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY_HERE"
      }
    }
  }
}

Alternativa (local):

{
  "mcpServers": {
    "olostep": {
      "command": "npx",
      "args": ["-y", "olostep-mcp"],
      "env": {
        "OLOSTEP_API_KEY": "YOUR_API_KEY_HERE"
      }
    }
  }
}

Windsurf

Agrega esto a tu ./codeium/windsurf/model_config.json:

{
  "mcpServers": {
    "olostep": {
      "serverUrl": "https://mcp.olostep.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY_HERE"
      }
    }
  }
}

Alternativa (local):

{
  "mcpServers": {
    "mcp-server-olostep": {
      "command": "npx",
      "args": ["-y", "olostep-mcp"],
      "env": {
        "OLOSTEP_API_KEY": "YOUR_API_KEY_HERE"
      }
    }
  }
}

VS Code

Agrega esto a tu .vscode/mcp.json:

{
  "servers": {
    "olostep": {
      "type": "http",
      "url": "https://mcp.olostep.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY_HERE"
      }
    }
  }
}

Alternativa (local):

{
  "servers": {
    "olostep": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "olostep-mcp"],
      "env": {
        "OLOSTEP_API_KEY": "YOUR_API_KEY_HERE"
      }
    }
  }
}

Metorial

Opción 1: Instalación con un clic (Recomendado)

1. Abre el panel de Metorial

2. Navega al directorio de Servidores MCP

3. Busca "Olostep"

4. Haz clic en "Instalar" e ingresa tu clave de API

Opción 2: Configuración manual

Agrega esto a tu configuración del servidor MCP de Metorial:

{
  "olostep": {
    "command": "npx",
    "args": ["-y", "olostep-mcp"],
    "env": {
      "OLOSTEP_API_KEY": "YOUR_API_KEY_HERE"
    }
  }
}

Las herramientas de Olostep estarán disponibles en tus chats de IA de Metorial.

Configuración

Variables de entorno

• OLOSTEP_API_KEY: Tu clave de API de Olostep (obligatorio)

• ORBIT_KEY: Una clave opcional para usar Orbit para enrutar solicitudes.

Herramientas disponibles

1. Extraer sitio web (scrape_website)

Extrae contenido de una sola URL. Admite múltiples formatos y renderizado de JavaScript.

{
  "name": "scrape_website",
  "arguments": {
    "url_to_scrape": "https://example.com",
    "output_format": "markdown",
    "country": "US",
    "wait_before_scraping": 1000,
    "parser": "@olostep/amazon-product"
  }
}

Parámetros:

• url_to_scrape: La URL del sitio web que deseas extraer (obligatorio)

• output_format: Elige el formato (html, markdown, json o text) - predeterminado: markdown

• country: Código de país opcional (ej. US, GB, CA) para extracción específica por ubicación

• wait_before_scraping: Tiempo de espera en milisegundos antes de extraer (0-10000)

• parser: ID de analizador opcional para extracción especializada

Respuesta (ejemplo):

{
  "content": [
    {
      "type": "text",
      "text": "{\n  \"id\": \"scrp_...\",\n  \"url\": \"https://example.com\",\n  \"markdown_content\": \"# ...\",\n  \"html_content\": null,\n  \"json_content\": null,\n  \"text_content\": null,\n  \"status\": \"succeeded\",\n  \"timestamp\": \"2025-11-14T12:34:56Z\",\n  \"screenshot_hosted_url\": null,\n  \"page_metadata\": { }\n}"
    }
  ]
}

2. Buscar en la web (search_web)

Busca en la web una consulta determinada y obtén resultados estructurados (no IA, basado en analizadores).

{
  "name": "search_web",
  "arguments": {
    "query": "your search query",
    "country": "US"
  }
}

Parámetros:

• query: Consulta de búsqueda (obligatorio)

• country: Código de país opcional para resultados localizados (predeterminado: US)

Respuesta:

• JSON estructurado (como texto) que representa los resultados basados en analizadores

3. Respuestas (IA) (answers)

Busca en la web y devuelve respuestas impulsadas por IA en la estructura JSON que desees, con fuentes y citas.

{
  "name": "answers",
  "arguments": {
    "task": "Who are the top 5 competitors to Acme Inc. in the EU?",
    "json": "Return a list of the top 5 competitors with name and homepage URL"
  }
}

Parámetros:

• task: Pregunta o tarea a responder usando datos web (obligatorio)

• json: Esquema/objeto JSON opcional o una breve descripción de la forma de salida deseada

La respuesta incluye:

• answer_id, object, task, result (JSON si se proporciona), sources, created

4. Extraer URLs por lotes (batch_scrape_urls)

Extrae hasta 10.000 URLs al mismo tiempo. Perfecto para la extracción de datos a gran escala.

{
  "name": "batch_scrape_urls",
  "arguments": {
    "urls_to_scrape": [
      {"url": "https://example.com/a", "custom_id": "a"},
      {"url": "https://example.com/b", "custom_id": "b"}
    ],
    "output_format": "markdown",
    "country": "US",
    "wait_before_scraping": 500,
    "parser": "@olostep/amazon-product"
  }
}

La respuesta incluye:

• batch_id, status, total_urls, created_at, formats, country, parser, urls

5. Crear rastreo (create_crawl)

Inicia un rastreo asíncrono que descubre y extrae autónomamente sitios web completos siguiendo enlaces. Devuelve un crawl_id: el rastreo se ejecuta en segundo plano y no devuelve contenido en esta respuesta. Luego debes llamar a get_crawl_results con el crawl_id para consultar el estado y recuperar las páginas extraídas (el mismo patrón de dos pasos que batch_scrape_urls + get_batch_results).

{
  "name": "create_crawl",
  "arguments": {
    "start_url": "https://example.com/docs",
    "max_pages": 25,
    "follow_links": true,
    "output_format": "markdown",
    "country": "US",
    "parser": "@olostep/doc-parser"
  }
}

La respuesta incluye:

• crawl_id, object, status, start_url, max_pages, follow_links, created, formats, country, parser

Empareja esta llamada con get_crawl_results: no pases un crawl_id a get_batch_results (los rastreos y los lotes son recursos separados).

6. Crear mapa (create_map)

Obtén todas las URLs de un sitio web. Extrae todas las URLs para descubrimiento y análisis.

{
  "name": "create_map",
  "arguments": {
    "website_url": "https://example.com",
    "search_query": "blog",
    "top_n": 200,
    "include_url_patterns": ["/blog/**"],
    "exclude_url_patterns": ["/admin/**"]
  }
}

La respuesta incluye:

• map_id, object, url, total_urls, urls, search_query, top_n

7. Obtener contenido de página web (get_webpage_content)

Recupera el contenido de la página web en formato markdown limpio con soporte para renderizado de JavaScript.

{
  "name": "get_webpage_content",
  "arguments": {
    "url_to_scrape": "https://example.com",
    "wait_before_scraping": 1000,
    "country": "US"
  }
}

Parámetros:

• url_to_scrape: La URL de la página web a extraer (obligatorio)

• wait_before_scraping: Tiempo de espera en milisegundos antes de comenzar la extracción (predeterminado: 0)

• country: País residencial desde el cual cargar la solicitud (ej. US, CA, GB) (opcional)

Respuesta:

{
  "content": [
    {
      "type": "text",
      "text": "# Example Website\n\nThis is the markdown content of the webpage..."
    }
  ]
}

8. Obtener URLs de sitios web (get_website_urls)

Busca y recupera URLs relevantes de un sitio web, ordenadas por relevancia según tu consulta.

{
  "name": "get_website_urls",
  "arguments": {
    "url": "https://example.com",
    "search_query": "your search term"
  }
}

Parámetros:

• url: La URL del sitio web a mapear (obligatorio)

• search_query: La consulta de búsqueda para ordenar las URLs (obligatorio)

Respuesta:

{
  "content": [
    {
      "type": "text",
      "text": "Found 42 URLs matching your query:\n\nhttps://example.com/page1\nhttps://example.com/page2\n..."
    }
  ]
}

9. Obtener resultados de lote (get_batch_results)

Recupera los resultados de un trabajo de extracción por lotes enviado previamente usando su batch_id.

{
  "name": "get_batch_results",
  "arguments": {
    "batch_id": "batch_abc123"
  }
}

Parámetros:

• batch_id: El ID de lote devuelto por batch_scrape_urls (obligatorio)

La respuesta incluye:

• batch_id, status (processing o completed), total_urls, completed_urls, items (matriz de resultados extraídos por URL con url, custom_id, markdown_content, html_content, json_content, text_content, status, page_metadata)

10. Obtener resultados de rastreo (get_crawl_results)

Recupera el estado y las páginas extraídas para un rastreo asíncrono iniciado con create_crawl. Este es el compañero obligatorio de create_crawl: create_crawl solo inicia el trabajo y devuelve un crawl_id; esta herramienta es cómo realmente obtienes las páginas descubiertas y su contenido.

{
  "name": "get_crawl_results",
  "arguments": {
    "crawl_id": "crawl_abc123",
    "formats": ["markdown"],
    "items_limit": 20,
    "cursor": 0
  }
}

Parámetros:

• crawl_id: El ID de rastreo devuelto por create_crawl (obligatorio)

• formats: Matriz de formatos a recuperar por página: markdown, html, json, text (predeterminado: ["markdown"])

• items_limit: Máximo de páginas para recuperar contenido, 1–100 (predeterminado: 20)

• cursor: Cursor de paginación en la lista de páginas descubiertas (predeterminado: 0)

• search_query: Filtro opcional para clasificar/seleccionar páginas por relevancia a una consulta

La respuesta incluye:

• Mientras está en progreso: crawl_id, status (in_progress), pages_completed, pages_total, y un message que te indica que vuelvas a llamar en ~10 segundos.

• Cuando se completa: crawl_id, status (completed), pages_returned, next_cursor, has_more, y una matriz pages donde cada entrada tiene url, custom_id y los campos de contenido solicitados (markdown_content, html_content, json_content, text_content).

Manejo de errores

El servidor proporciona un manejo de errores robusto:

• Mensajes de error detallados para problemas de API

• Reporte de errores de red

• Manejo de fallos de autenticación

• Información sobre límites de tasa

Ejemplo de respuesta de error:

{
  "isError": true,
  "content": [
    {
      "type": "text",
      "text": "Olostep API Error: 401 Unauthorized. Details: {\"error\":\"Invalid API key\"}"
    }
  ]
}

Distribución

Imágenes de Docker

El servidor MCP está disponible como una imagen de Docker:

• Docker Hub: [olostep/mcp-server](https://hub.docker.com/r/olostep/mcp-server)

• Registro oficial de Docker MCP: mcp/olostep (próximamente: seguridad mejorada con firmas y SBOMs)

• Registro de contenedores de GitHub: ghcr.io/olostep/olostep-mcp-server

Kit de herramientas MCP de Docker Desktop

El servidor MCP de Olostep se está agregando al kit de herramientas MCP oficial de Docker Desktop, lo que significa que los usuarios podrán:

• Descubrirlo en la interfaz de usuario del kit de herramientas MCP de Docker Desktop

• Instalarlo con un clic

• Configurarlo visualmente

• Usarlo con cualquier cliente compatible con MCP (Claude Desktop, Cursor, etc.)

Estado: Envío en progreso al Registro MCP de Docker

Plataformas compatibles

• linux/amd64

• linux/arm64

Construcción local

# Clone the repository
git clone https://github.com/olostep/olostep-mcp-server.git
cd olostep-mcp-server

# Build the image
npm install
npm run build
docker build -t olostep/mcp-server .

# Run locally
docker run -i --rm -e OLOSTEP_API_KEY="your-key" olostep/mcp-server

Licencia

Licencia ISC