Searchcraft

Gestiona los Documentos, Índices, Federaciones, Claves de Acceso y Análisis del clúster de Searchcraft.

Documentación

searchcraft-mcp-server

Un servidor MCP impulsado por Searchcraft – el motor de búsqueda vertical pensado para desarrolladores.

El servidor MCP de Searchcraft proporciona un conjunto de herramientas para gestionar los Documentos, Índices, Federaciones, Claves de Acceso y Analíticas de tu clúster Searchcraft. Permite que clientes MCP, como Claude Desktop, reciban instrucciones en lenguaje natural para realizar acciones administrativas como configurar índices de búsqueda, claves de acceso, ingerir documentos, ver analíticas, buscar en índices y más.

Cómo crear una aplicación en 2 minutos con el servidor MCP de Searchcraft (enlace al video)

Building an app in 2 minutes with Searchcraft MCP Server

Ejemplos de Prompts

Aquí tienes un ejemplo de prompt que podría usarse una vez que Claude esté conectado al servidor MCP de Searchcraft.

I'd like to create a product search application using the create_vite_app tool.

Please use this JSON dataset https://dummyjson.com/products
First use the Searchcraft create_index_from_json tool to create the index and add the documents.

Then create an API read key for the vite app using the create_key tool.

App details:
- App name: "my-ecommerce-app"
- Endpoint: http://localhost:8000
- Index name: my-ecommerce-app

Herramientas Disponibles

El servidor MCP de Searchcraft actualmente proporciona tres categorías de herramientas: herramientas de importación, herramientas de API del motor y herramientas de generación de aplicaciones:

Herramientas de API del Motor

Estas herramientas proporcionan acceso directo a la funcionalidad principal de tu clúster Searchcraft para gestionar índices, documentos, federaciones, autenticación y operaciones de búsqueda.

Gestión de Índices

Nombre de la Herramienta	Descripción
create_index	Crea un nuevo índice con el esquema especificado. Esto vaciará el índice si ya existe.
delete_index	Elimina un índice y todos sus documentos de forma permanente.
get_all_index_stats	Obtiene recuentos de documentos y estadísticas para todos los índices.
get_index_schema	Obtiene la definición del esquema para un índice específico.
get_index_stats	Obtiene estadísticas y metadatos para un índice específico (recuento de documentos, etc.).
list_all_indexes	Obtiene una lista de todos los índices en la instancia de Searchcraft.
patch_index	Realiza cambios parciales de configuración en el esquema de un índice (search_fields, weight_multipliers, etc.).
update_index	Reemplaza todo el contenido de un índice existente con una nueva definición de esquema.

Gestión de Documentos

Nombre de la Herramienta	Descripción
add_documents	Añade uno o varios documentos a un índice. Los documentos deben proporcionarse como un array de objetos JSON.
delete_all_documents	Elimina todos los documentos de un índice. El índice continuará existiendo después de que se eliminen todos los documentos.
delete_document_by_id	Elimina un solo documento de un índice por su ID interno de Searchcraft (_id).
delete_documents_by_field	Elimina uno o varios documentos de un índice por coincidencia de término de campo (por ejemplo, {id: 'xyz'} o {title: 'foo'}).
delete_documents_by_query	Elimina uno o varios documentos de un índice por coincidencia de consulta.
get_document_by_id	Obtiene un solo documento de un índice por su ID interno de Searchcraft (_id).

Gestión de Federaciones

Nombre de la Herramienta	Descripción
create_federation	Crea o actualiza una federación con la configuración especificada.
delete_federation	Elimina una federación de forma permanente.
get_federation_details	Obtiene información detallada para una federación específica.
get_federation_stats	Obtiene recuentos de documentos por índice para una federación, así como el recuento total de documentos.
get_organization_federations	Obtiene una lista de todas las federaciones para una organización específica.
list_all_federations	Obtiene una lista de todas las federaciones en la instancia de Searchcraft.
update_federation	Reemplaza la entidad de federación actual con una actualizada.

Gestión de Autenticación y Claves

Nombre de la Herramienta	Descripción
create_key	Crea una nueva clave de autenticación con permisos y controles de acceso especificados.
delete_all_keys	Elimina todas las claves de autenticación en el clúster de Searchcraft. ¡Úsalo con extrema precaución!
delete_key	Elimina una clave de autenticación específica de forma permanente.
get_application_keys	Obtiene una lista de todas las claves de autenticación asociadas con una aplicación específica.
get_federation_keys	Obtiene una lista de todas las claves de autenticación asociadas con una federación específica.
get_key_details	Obtiene información detallada para una clave de autenticación específica.
get_organization_keys	Obtiene una lista de todas las claves de autenticación asociadas con una organización específica.
list_all_keys	Obtiene una lista de todas las claves de autenticación en el clúster de Searchcraft.
update_key	Actualiza una clave de autenticación existente con una nueva configuración.

Gestión de Palabras Vacías (Stopwords)

Nombre de la Herramienta	Descripción
add_stopwords	Añade palabras vacías personalizadas a un índice. Estas se añaden además del diccionario predeterminado específico del idioma.
delete_all_stopwords	Elimina todas las palabras vacías personalizadas de un índice. Esto solo afecta a las palabras vacías personalizadas, no al diccionario de idioma predeterminado.
delete_stopwords	Elimina palabras vacías personalizadas específicas de un índice. Esto solo afecta a las palabras vacías personalizadas, no al diccionario de idioma predeterminado.
get_index_stopwords	Obtiene todas las palabras vacías de un índice, incluyendo tanto el diccionario de idioma predeterminado como las palabras vacías personalizadas.

Gestión de Sinónimos

Nombre de la Herramienta	Descripción
add_synonyms	Añade sinónimos a un índice. Los sinónimos solo funcionan con consultas difusas, no con consultas de coincidencia exacta.
delete_all_synonyms	Elimina todos los sinónimos de un índice.
delete_synonyms	Elimina sinónimos específicos de un índice por sus claves.
get_index_synonyms	Obtiene todos los sinónimos definidos para un índice.

Búsqueda y Analíticas

Nombre de la Herramienta	Descripción
get_measure_conversion	Obtiene datos de conversión de mediciones con parámetros opcionales de filtrado y agregación. *requiere Clickhouse si se ejecuta localmente
get_measure_summary	Obtiene datos de resumen de mediciones con parámetros opcionales de filtrado y agregación. *requiere Clickhouse si se ejecuta localmente
get_search_results	Realiza una consulta de búsqueda usando la API de Searchcraft con soporte para coincidencia difusa/exacta, facetas y rangos de fechas.
get_prelim_search_data	Obtiene campos de esquema e información de facetas para un índice de búsqueda para comprender los campos disponibles para construir consultas.
get_searchcraft_status	Obtiene el estado actual del servicio de búsqueda de Searchcraft.

Herramientas de Importación

Estas herramientas proporcionan flujos de trabajo para importar datos JSON y generar automáticamente esquemas de Searchcraft. Perfectas para configurar rápidamente nuevos índices a partir de fuentes de datos existentes.

Nombre de la Herramienta	Descripción
analyze_json_from_file	Lee datos JSON de un archivo local y analiza su estructura para comprender los tipos de campos y patrones para la generación de esquemas de índice de Searchcraft.
analyze_json_from_url	Obtiene datos JSON de una URL y analiza su estructura para comprender los tipos de campos y patrones para la generación de esquemas de índice de Searchcraft.
generate_searchcraft_schema	Genera un esquema de índice de Searchcraft completo a partir de la estructura JSON analizada, con opciones personalizables para campos de búsqueda, pesos y otras configuraciones del índice.
create_index_from_json	Flujo de trabajo completo para crear un índice de Searchcraft a partir de datos JSON. Obtiene JSON de una URL o archivo, analiza la estructura, genera el esquema, crea el índice y añade todos los documentos en un solo paso.

Flujo de Trabajo de las Herramientas de Importación

Las herramientas de importación están diseñadas para trabajar juntas en un flujo de trabajo simplificado:

Analizar → Usa analyze_json_from_file o analyze_json_from_url para examinar la estructura de tus datos JSON
Generar → Usa generate_searchcraft_schema para crear un esquema de Searchcraft personalizado a partir del análisis
Crear → Usa la herramienta create_index de la API del Motor para crear el índice con tu esquema generado
Importar → Usa add_documents para poblar tu nuevo índice con datos

O usa el enfoque todo-en-uno:

Un Solo Paso → Usa create_index_from_json para analizar, generar el esquema, crear el índice e importar todos los documentos en un solo comando

Herramientas de Generación de Aplicaciones

Estas herramientas crean aplicaciones de búsqueda completas y listas para ejecutar a partir de tus datos JSON, perfectas para prototipos y demostraciones.

Nombre de la Herramienta	Descripción
create_vite_app	Crea una aplicación de búsqueda completa de Vite + React a partir de datos JSON. Analiza la estructura de tus datos, genera plantillas de búsqueda optimizadas y crea una aplicación web totalmente funcional con integración de Searchcraft.

Flujo de Trabajo de Generación de Aplicaciones

Las herramientas de generación de aplicaciones proporcionan una solución de extremo a extremo para crear aplicaciones de búsqueda:

Análisis de Datos → Analiza automáticamente tu estructura JSON para comprender los tipos de campos y el contenido
Generación de Plantillas → Crea plantillas de resultados de búsqueda optimizadas basadas en tus campos de datos
Creación de la Aplicación → Clona y configura una aplicación completa de Vite + React
Configuración del Entorno → Configura los ajustes de conexión de Searchcraft
Listo para Ejecutar → Proporciona una aplicación de búsqueda totalmente funcional que puedes iniciar y personalizar inmediatamente

Uso Detallado de las Herramientas

Uso de create_index_from_json

La herramienta create_index_from_json proporciona un flujo de trabajo completo para crear un índice de Searchcraft a partir de datos JSON en un solo comando. Esto es perfecto para configurar rápidamente índices de búsqueda a partir de conjuntos de datos existentes. Ten en cuenta que, si conoces el idioma de los datos que estás importando, debes especificarlo con el parámetro language (usa el código de dos letras ISO 639-1 para el idioma)

Parámetros

Parámetro	Tipo	Requerido	Descripción
`source`	`"url"` o `"file"`	✅	Si obtener datos de una URL o leerlos de un archivo local
`path`	`string`	✅	URL o ruta de archivo a los datos JSON
`index_name`	`string`	✅	Nombre para el nuevo índice de Searchcraft
`sample_size`	`number`	❌	Número de elementos a analizar para la generación del esquema (predeterminado: 10)
`search_fields`	`string[]`	❌	Sobrescribir los campos de búsqueda detectados automáticamente
`weight_multipliers`	`object`	❌	Pesos de campo personalizados para la relevancia de búsqueda (0.0-10.0)
`language`	`string`	❌	Código de idioma para el índice (por ejemplo, "en", "es")
`auto_commit_delay`	`number`	❌	Retraso de confirmación automática en segundos
`exclude_stop_words`	`boolean`	❌	Si excluir palabras vacías de la búsqueda
`time_decay_field`	`string`	❌	Nombre del campo para la decadencia de relevancia basada en el tiempo

Ejemplo de Uso

Desde una URL:

{
  "source": "url",
  "path": "https://api.example.com/products.json",
  "index_name": "products",
  "sample_size": 50,
  "search_fields": ["title", "description", "category"],
  "weight_multipliers": {
    "title": 2.0,
    "description": 1.0,
    "category": 1.5
  }
}

Desde un archivo local:

{
  "source": "file",
  "path": "/path/to/data.json",
  "index_name": "my_data",
  "language": "en"
}

Qué hace

Obtiene/Lee Datos → Descarga desde URL o lee desde archivo local
Analiza la Estructura → Examina el JSON para comprender los tipos de campos y patrones
Genera el Esquema → Crea un esquema de índice de Searchcraft optimizado
Crea el Índice → Configura el índice en tu clúster de Searchcraft
Importa Documentos → Añade todos los datos JSON como documentos buscables
Devuelve un Resumen → Proporciona información detallada sobre lo que se creó

Formato JSON Esperado

La herramienta funciona con varias estructuras JSON:

Array de objetos: [{...}, {...}, ...]
Objeto con propiedad de array: {"data": [{...}, {...}], "meta": {...}}
Objeto único: {...} (se tratará como un solo documento)

La herramienta encuentra automáticamente el mejor array de objetos para usar en el índice.

Uso de create_vite_app

La herramienta create_vite_app crea una aplicación de búsqueda completa y lista para ejecutar a partir de tus datos JSON. Es perfecta para prototipar rápidamente interfaces de búsqueda o crear aplicaciones de demostración.

Parámetros

Parámetro	Tipo	Requerido	Descripción
`data_source`	`"url"` o `"file"`	✅	Si obtener datos de una URL o leer desde un archivo local
`data_path`	`string`	✅	URL o ruta de archivo a los datos JSON
`app_name`	`string`	✅	Nombre para la aplicación generada (se usa para el nombre del directorio)
`VITE_ENDPOINT_URL`	`string`	✅	La URL del endpoint de tu clúster de Searchcraft
`VITE_INDEX_NAME`	`string`	✅	El nombre del índice de Searchcraft al que conectarse
`VITE_READ_KEY`	`string`	✅	Clave de lectura de Searchcraft para la aplicación
`sample_size`	`number`	❌	Número de elementos a analizar para la generación de plantillas (predeterminado: 50)
`search_fields`	`string[]`	❌	Sobrescribir los campos de búsqueda detectados automáticamente
`weight_multipliers`	`object`	❌	Pesos personalizados de campos para la relevancia de búsqueda (0.0-10.0)

Ejemplo de uso

Si viste el prompt anteriormente en la documentación, puedes usar fácilmente la herramienta create_vite_app con lenguaje natural. Sin embargo, si deseas un control más preciso, puedes usar la herramienta con parámetros JSON.

Creando una aplicación de búsqueda de productos:

{
  "data_source": "url",
  "data_path": "https://api.example.com/products.json",
  "app_name": "product-search",
  "VITE_ENDPOINT_URL": "https://your-cluster.searchcraft.io",
  "VITE_INDEX_NAME": "products",
  "VITE_READ_KEY": "your_read_key_here",
  "sample_size": 100,
  "search_fields": ["title", "description", "brand"],
  "weight_multipliers": {
    "title": 2.5,
    "description": 1.0,
    "brand": 1.8
  }
}

Creando una aplicación de búsqueda de blog desde datos locales:

{
  "data_source": "file",
  "data_path": "/path/to/blog-posts.json",
  "app_name": "blog-search",
  "VITE_ENDPOINT_URL": "https://your-cluster.searchcraft.io",
  "VITE_INDEX_NAME": "blog_posts",
  "VITE_READ_KEY": "your_read_key_here"
}

Qué hace

Analiza la estructura de datos → Examina tu JSON para comprender los tipos de campos y los patrones de contenido
Genera plantillas de búsqueda → Crea plantillas optimizadas de visualización de resultados basadas en tus datos
Clona la plantilla de Vite → Descarga la plantilla oficial de Searchcraft Vite + React
Instala dependencias → Configura todos los paquetes npm necesarios
Configura el entorno → Crea el archivo .env con tu configuración de Searchcraft
Personaliza plantillas → Genera componentes dinámicos de resultados de búsqueda
Actualiza el código de la aplicación → Modifica la aplicación principal con tu marca y configuración específicas

Características de la aplicación generada

La aplicación creada incluye:

React + Vite → Configuración de desarrollo moderna y rápida
Integración con el SDK de Searchcraft → Funcionalidad completa de búsqueda lista para usar
Diseño responsivo → Funciona en dispositivos de escritorio y móviles
Plantillas autogeneradas → Visualización inteligente de resultados según tu estructura de datos
Configuración de entorno → Configuración fácil para diferentes entornos
Servidor de desarrollo → Recarga en caliente para personalización rápida

Lógica de generación de plantillas

La herramienta analiza inteligentemente tus datos para crear plantillas óptimas de resultados de búsqueda:

Detección de campo de título → Encuentra el mejor campo para usar como título principal
Detección de campo de descripción → Identifica campos de texto descriptivos
Detección de campo de imagen → Localiza URLs de imágenes para resultados visuales
Detección de campo de fecha → Encuentra campos de marca de tiempo para ordenamiento temporal
Campos adicionales → Incluye otros campos de texto relevantes para resultados completos

Próximos pasos después de la creación

Una vez que la aplicación esté creada, puedes:

Iniciar el servidor de Vite:
```
cd apps/your-app-name
yarn dev
```
Personalizar el estilo → Modifica CSS y componentes para que coincidan con tu marca
Agregar funciones → Extiende con filtros, facetas u opciones avanzadas de búsqueda
Implementar → Compila e implementa en tu plataforma de hosting preferida

Requisitos previos

Índice de Searchcraft existente → El índice especificado en VITE_INDEX_NAME ya debería existir
Clave de lectura válida → La VITE_READ_KEY debe tener permisos de lectura para el índice
Git disponible → La herramienta usa git para clonar el repositorio de plantillas
Node.js y Yarn → Requeridos para la instalación de dependencias

Flujo de trabajo completo: de JSON a aplicación de búsqueda

Aquí se explica cómo usar ambas herramientas juntas para pasar de datos JSON sin procesar a una aplicación de búsqueda completamente funcional:

Opción 1: Proceso de dos pasos (recomendado para producción)

Paso 1: Crear el índice de Searchcraft

{
  "source": "url",
  "path": "https://api.example.com/products.json",
  "index_name": "products",
  "sample_size": 100,
  "search_fields": ["title", "description", "category", "brand"],
  "weight_multipliers": {
    "title": 2.5,
    "description": 1.0,
    "category": 1.8,
    "brand": 1.5
  },
  "language": "en"
}

Paso 2: Crear la aplicación de búsqueda

{
  "data_source": "url",
  "data_path": "https://api.example.com/products.json",
  "app_name": "product-search-app",
  "VITE_ENDPOINT_URL": "https://your-cluster.searchcraft.io",
  "VITE_INDEX_NAME": "products",
  "VITE_READ_KEY": "your_read_key_here",
  "sample_size": 100,
  "search_fields": ["title", "description", "category", "brand"],
  "weight_multipliers": {
    "title": 2.5,
    "description": 1.0,
    "category": 1.8,
    "brand": 1.5
  }
}

Opción 2: Proceso solo de aplicación (para índices existentes)

Si ya tienes un índice de Searchcraft configurado, puedes pasar directamente a crear la aplicación:

{
  "data_source": "url",
  "data_path": "https://api.example.com/products.json",
  "app_name": "my-search-app",
  "VITE_ENDPOINT_URL": "https://your-cluster.searchcraft.io",
  "VITE_INDEX_NAME": "existing_index",
  "VITE_READ_KEY": "your_read_key_here"
}

Beneficios del enfoque de dos pasos

Optimización del índice → Ajusta tu índice de búsqueda por separado de la interfaz de usuario
Múltiples aplicaciones → Crea diferentes interfaces de búsqueda para los mismos datos
Listo para producción → Mejor separación de preocupaciones para implementaciones de producción
Depuración más fácil → Prueba la funcionalidad de búsqueda independientemente de la interfaz de usuario

Primeros pasos

Variables de entorno

Crea el archivo .env en la raíz del proyecto y completa los valores:

# Server Config
USER_AGENT=searchcraft-mcp-server/<project-version>
DEBUG=true
PORT=3100

# Searchcraft Config
ENDPOINT_URL= # The endpoint url of your Searchcraft Cluster
CORE_API_KEY= # The Searchcraft API key of your Searchcraft cluster. Must match the permissions required by the tools you are using.

Ejemplo de .env

Uso remoto

Si ya has creado un índice a través de Vektron en Searchcraft Cloud, puedes usar la clave de escritura para el índice al que intentas acceder y usar el servidor MCP para operaciones de API que no requieren privilegios de administrador. IMPORTANTE: Si usas el servidor MCP con una clave de escritura, NO debe estar expuesta públicamente en internet. Las claves de escritura están diseñadas para estar protegidas y, al ejecutar un servidor MCP, cualquier usuario con acceso al servidor MCP podrá escribir en el índice o eliminar datos.

Instalación y configuración

Asegúrate de que tu entorno tenga la versión correcta de node seleccionada.

nvm use

Instala las dependencias con yarn

yarn

Compila el servidor

yarn build

Esto crea dos versiones del servidor:

dist/server.js - Servidor HTTP para pruebas e implementación remota
dist/stdio-server.js - Servidor stdio para Claude Desktop

Uso

Opción 1: Claude Desktop (stdio) - Recomendado

Para uso local con Claude Desktop, usa la versión stdio que proporciona mejor rendimiento y confiabilidad.

claude_desktop_config.json

{
  "mcpServers": {
    "searchcraft": {
      "command": "node",
      "args": [
        "/path/to/searchcraft-mcp-server/dist/stdio-server.js"
      ]
    }
  }
}

El archivo de configuración de Claude Desktop se puede encontrar en:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

Si el archivo no existe, créalo.

Opción 2: Claude Code

Para uso con Claude Code, usa la CLI para configurar el servidor MCP:

Configuración básica:

# Add the Searchcraft MCP server to Claude Code
claude mcp add searchcraft -- node /path/to/searchcraft-mcp-server/dist/stdio-server.js

Con variables de entorno:

# Add with your Searchcraft cluster configuration
claude mcp add searchcraft \
  --env ENDPOINT_URL=https://your-cluster.searchcraft.io \
  --env CORE_API_KEY=YOUR_API_KEY \
  -- node /path/to/searchcraft-mcp-server/dist/stdio-server.js

Ámbitos de configuración:

--scope local (predeterminado): Disponible solo para ti en el proyecto actual
--scope project: Compartido con el equipo a través del archivo .mcp.json (recomendado para equipos)
--scope user: Disponible para ti en todos los proyectos

Gestión de servidores:

# List configured servers
claude mcp list

# Check server status
/mcp

# Remove server
claude mcp remove searchcraft

Opción 3: Open WebUI (a través de Pipelines)

Open WebUI admite servidores MCP a través de su marco de trabajo Pipelines. Esto requiere crear un pipeline personalizado que conecte tu servidor MCP con Open WebUI.

Paso 1: Iniciar el servidor HTTP de Searchcraft MCP

yarn start  # Starts HTTP server on port 3100

Paso 2: Crear un pipeline MCP para Open WebUI

Crea un archivo llamado searchcraft_mcp_pipeline.py:

"""
title: Searchcraft MCP Pipeline
author: Searchcraft Team
version: 1.0.0
license: Apache-2.0
description: A pipeline that integrates Searchcraft MCP server with Open WebUI
requirements: requests
"""

import requests
import json
from typing import List, Union, Generator, Iterator
from pydantic import BaseModel


class Pipeline:
    class Valves(BaseModel):
        MCP_SERVER_URL: str = "http://localhost:3100/mcp"
        ENDPOINT_URL: str = ""
        CORE_API_KEY: str = ""

    def __init__(self):
        self.name = "Searchcraft MCP Pipeline"
        self.valves = self.Valves()

    async def on_startup(self):
        print(f"on_startup:{__name__}")

    async def on_shutdown(self):
        print(f"on_shutdown:{__name__}")

    def pipe(
        self, user_message: str, model_id: str, messages: List[dict], body: dict
    ) -> Union[str, Generator, Iterator]:
        # This pipeline acts as a bridge between Open WebUI and your MCP server
        # You can customize this to handle specific Searchcraft operations

        # Example: If user mentions search operations, route to MCP server
        if any(keyword in user_message.lower() for keyword in ['search', 'index', 'document', 'searchcraft']):
            try:
                # Initialize MCP session
                init_payload = {
                    "jsonrpc": "2.0",
                    "id": 1,
                    "method": "initialize",
                    "params": {
                        "protocolVersion": "2025-06-18",
                        "capabilities": {},
                        "clientInfo": {"name": "open-webui-pipeline", "version": "1.0.0"}
                    }
                }

                response = requests.post(self.valves.MCP_SERVER_URL, json=init_payload)

                if response.status_code == 200:
                    # Add context about available Searchcraft tools
                    enhanced_message = f"""
{user_message}

[Available Searchcraft MCP Tools: create_index, delete_index, add_documents, get_search_results, list_all_indexes, get_index_stats, create_key, delete_key, and 20+ more tools for managing Searchcraft clusters]
"""
                    return enhanced_message

            except Exception as e:
                print(f"MCP connection error: {e}")

        return user_message

Paso 3: Instalar el pipeline en Open WebUI

A través del panel de administración:
- Ve a Configuración de administración → Pipelines
- Haz clic en "Agregar pipeline"
- Pega el código del pipeline anterior
- Configura las válvulas con tu configuración de Searchcraft:
  - MCP_SERVER_URL: http://localhost:3100/mcp
  - ENDPOINT_URL: La URL de tu clúster de Searchcraft
  - CORE_API_KEY: Tu clave API de Searchcraft

A través del entorno Docker:

# Save the pipeline to a file and mount it
docker run -d -p 3000:8080 \
  -v open-webui:/app/backend/data \
  -v ./searchcraft_mcp_pipeline.py:/app/backend/data/pipelines/searchcraft_mcp_pipeline.py \
  --name open-webui \
  ghcr.io/open-webui/open-webui:main

Paso 4: Configurar Open WebUI para usar Pipelines

Inicia Open WebUI con soporte de Pipelines:

# Using Docker Compose (recommended)
services:
  openwebui:
    image: ghcr.io/open-webui/open-webui:main
    ports:
      - "3000:8080"
    volumes:
      - open-webui:/app/backend/data
    environment:
      - OPENAI_API_BASE_URL=http://pipelines:9099
      - OPENAI_API_KEY=0p3n-w3bu!

  pipelines:
    image: ghcr.io/open-webui/pipelines:main
    volumes:
      - pipelines:/app/pipelines
    environment:
      - PIPELINES_API_KEY=0p3n-w3bu!

En Configuración de Open WebUI → Conexiones:
- Establece la URL de la API de OpenAI en tu instancia de Pipelines
- Habilita el pipeline MCP de Searchcraft

Opción 4: Servidor HTTP (para pruebas/implementación remota)

Inicia el servidor HTTP para pruebas, depuración o implementación remota:

yarn start  # Starts HTTP server on port 3100

Para Claude Desktop con servidor HTTP, necesitarás mcp-remote:

claude_desktop_config.json

{
  "mcpServers": {
    "searchcraft": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "http://localhost:3100/mcp"
      ]
    }
  }
}

Opción 5: Docker

Ejecuta el servidor MCP de Searchcraft en un contenedor Docker para una implementación fácil y portabilidad.

Compilar la imagen Docker:

docker build --load -t searchcraft-mcp-server .

Ejecutar el contenedor:

docker run -it -p 8000:8000 \
  --name searchcraft-mcp-server \
  -e ENDPOINT_URL="https://your-cluster.searchcraft.io" \
  -e CORE_API_KEY="your_searchcraft_core_API_key" \
  searchcraft-mcp-server

Probar el servidor:

# Health check
curl http://localhost:8000/health

# Test MCP endpoint
curl -X POST http://localhost:8000/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"test","version":"1.0.0"}}}'

Inspección remota con MCP Inspector:

npx @modelcontextprotocol/inspector --transport http --server-url http://localhost:8000/mcp

Configuración de Docker:

Usa Node.js 22-slim como imagen base
Expone el puerto 3100 por defecto (configurable a través de la variable de entorno PORT)
Maneja automáticamente el apagado elegante en SIGINT/SIGTERM
Optimizado para producción con tamaño de imagen mínimo

Variables de entorno:

PORT - Puerto del servidor HTTP (predeterminado: 8000)
ENDPOINT_URL - La URL del endpoint de tu clúster de Searchcraft
CORE_API_KEY - Tu clave API de Searchcraft
DEBUG - Habilitar registro de depuración (opcional)

Scripts disponibles

# Development
yarn dev          # Watch HTTP server
yarn dev:stdio    # Watch stdio server

# Production
yarn start        # Start HTTP server
yarn start:stdio  # Start stdio server

# Testing
yarn inspect      # Launch MCP inspector
yarn claude-logs  # View Claude Desktop logs

Comparación de opciones de implementación

Característica	stdio (Recomendado)	HTTP (Local)	Docker
Rendimiento	✅ Mejor (IPC directo)	⚠️ Sobrecarga HTTP	✅ Bueno
Seguridad	✅ Sin puertos expuestos	⚠️ Puerto de red requerido	✅ Entorno aislado
Complejidad de configuración	✅ Simple	⚠️ Gestión de puertos necesaria	✅ Simple (un comando)
Claude Desktop	✅ Soporte nativo	⚠️ Requiere mcp-remote	⚠️ Requiere mcp-remote
Claude Code	✅ Soporte nativo	✅ Compatible	✅ Compatible
Open WebUI	❌ No compatible	✅ A través de Pipelines	✅ A través de Pipelines
Implementación remota	❌ Solo local	✅ Posible pero manual	✅ Contenerización fácil
Pruebas	⚠️ Requiere herramientas MCP	✅ Fácil con curl	✅ Fácil con curl
Múltiples clientes	❌ Uno a la vez	✅ Acceso concurrente	✅ Acceso concurrente
Portabilidad	⚠️ Requiere Node.js	⚠️ Requiere Node.js	✅ Se ejecuta en cualquier lugar

Usa stdio cuando:

Uses Claude Desktop o Claude Code localmente
Quieras el mejor rendimiento absoluto
Prefieras comunicación directa entre procesos

Usa HTTP (local) cuando:

Necesites probar/depurar la interfaz HTTP
Estés desarrollando integraciones personalizadas
Necesites múltiples clientes locales concurrentes

Usa Docker cuando:

Necesites implementación remota
Quieras una configuración fácil y reproducible
Estés implementando en plataformas en la nube
Quieras aislamiento y seguridad
Necesites publicar tu servidor para inspección

Pruebas

El servidor MCP de Searchcraft incluye un conjunto completo de pruebas construido con Vitest.

Ejecutar pruebas

# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Run tests with coverage
npm run test:coverage

# Show test reports
npm run test:ui

Cobertura de pruebas

✅ 89 pruebas que cubren la funcionalidad principal
✅ Cobertura del 84%+ en helpers y utilidades
✅ Cobertura del 93%+ en el analizador JSON
✅ Cobertura del 100% en la creación del servidor
✅ Pruebas de integración para endpoints HTTP
✅ Pruebas unitarias para todos los componentes principales

Consulta test/README.md para documentación detallada de pruebas.

Depuración

Registros de Claude Desktop

Para ver los registros de Claude Desktop para depurar conexiones MCP:

yarn claude-logs

Pruebas con MCP Inspector

MCP Inspector te permite probar las herramientas de tu servidor de forma interactiva.

Para servidor stdio (recomendado):

yarn inspect

Elige Tipo de transporte: stdio
Comando: node dist/stdio-server.js

Para servidor HTTP:

yarn start  # Start HTTP server first
yarn inspect

Elige Tipo de transporte: HTTP transmisible
URL: http://localhost:3100/mcp

Pruebas manuales

Probar servidor HTTP:

# Health check
curl http://localhost:3100/health

# Test MCP endpoint
curl -X POST http://localhost:3100/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"test","version":"1.0.0"}}}'

Probar servidor stdio:

echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"test","version":"1.0.0"}}}' | node dist/stdio-server.js

Recursos

Problemas y solicitudes de funciones

Visita https://github.com/searchcraft-inc/searchcraft-issues

Licencia

Licenciado bajo la Licencia Apache 2.0.

Construido con 🛰️ por el equipo de Searchcraft