Searchcraft

searchcraft-mcp-server

Um servidor MCP alimentado pelo Searchcraft – o mecanismo de busca vertical feito para desenvolvedores.

O Searchcraft MCP Server fornece um conjunto de ferramentas para gerenciar Documentos, Índices, Federações, Chaves de Acesso e Análises do seu cluster Searchcraft. Ele permite que clientes MCP, como o Claude Desktop, recebam comandos em linguagem natural para executar ações administrativas, como configurar índices de busca, chaves de acesso, ingerir documentos, visualizar análises, pesquisar índices e muito mais.

Criando um aplicativo em 2 minutos com o Searchcraft MCP Server (link do vídeo)

Exemplos de Comandos

Aqui está um exemplo de comando que pode ser usado depois que o Claude estiver conectado ao Searchcraft MCP Server.

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

Ferramentas Disponíveis

O Searchcraft MCP Server atualmente fornece três categorias de ferramentas: ferramentas de importação, ferramentas de API do mecanismo e ferramentas de geração de aplicativos:

Ferramentas de API do Mecanismo

Essas ferramentas fornecem acesso direto à funcionalidade principal do seu cluster Searchcraft para gerenciar índices, documentos, federações, autenticação e operações de busca.

Gerenciamento de Índices

Nome da Ferramenta	Descrição
create_index	Crie um novo índice com o esquema especificado. Isso esvaziará o índice se ele já existir.
delete_index	Exclua um índice e todos os seus documentos permanentemente.
get_all_index_stats	Obtenha contagens de documentos e estatísticas para todos os índices.
get_index_schema	Obtenha a definição de esquema para um índice específico.
get_index_stats	Obtenha estatísticas e metadados para um índice específico (contagem de documentos, etc.).
list_all_indexes	Obtenha uma lista de todos os índices na instância Searchcraft.
patch_index	Faça alterações parciais de configuração em um esquema de índice (search_fields, weight_multipliers, etc.).
update_index	Substitua todo o conteúdo de um índice existente por uma nova definição de esquema.

Gerenciamento de Documentos

Nome da Ferramenta	Descrição
add_documents	Adicione um ou vários documentos a um índice. Os documentos devem ser fornecidos como uma matriz de objetos JSON.
delete_all_documents	Exclua todos os documentos de um índice. O índice continuará existindo após a exclusão de todos os documentos.
delete_document_by_id	Exclua um único documento de um índice pelo seu ID interno do Searchcraft (_id).
delete_documents_by_field	Exclua um ou vários documentos de um índice por correspondência de termo de campo (por exemplo, {id: 'xyz'} ou {title: 'foo'}).
delete_documents_by_query	Exclua um ou vários documentos de um índice por correspondência de consulta.
get_document_by_id	Obtenha um único documento de um índice pelo seu ID interno do Searchcraft (_id).

Gerenciamento de Federações

Nome da Ferramenta	Descrição
create_federation	Crie ou atualize uma federação com a configuração especificada.
delete_federation	Exclua uma federação permanentemente.
get_federation_details	Obtenha informações detalhadas para uma federação específica.
get_federation_stats	Obtenha contagens de documentos por índice para uma federação, bem como a contagem total de documentos.
get_organization_federations	Obtenha uma lista de todas as federações para uma organização específica.
list_all_federations	Obtenha uma lista de todas as federações na instância Searchcraft.
update_federation	Substitua a entidade de federação atual por uma atualizada.

Gerenciamento de Autenticação e Chaves

Nome da Ferramenta	Descrição
create_key	Crie uma nova chave de autenticação com permissões e controles de acesso especificados.
delete_all_keys	Exclua todas as chaves de autenticação no cluster Searchcraft. Use com extrema cautela!
delete_key	Exclua uma chave de autenticação específica permanentemente.
get_application_keys	Obtenha uma lista de todas as chaves de autenticação associadas a um aplicativo específico.
get_federation_keys	Obtenha uma lista de todas as chaves de autenticação associadas a uma federação específica.
get_key_details	Obtenha informações detalhadas para uma chave de autenticação específica.
get_organization_keys	Obtenha uma lista de todas as chaves de autenticação associadas a uma organização específica.
list_all_keys	Obtenha uma lista de todas as chaves de autenticação no cluster Searchcraft.
update_key	Atualize uma chave de autenticação existente com uma nova configuração.

Gerenciamento de Stopwords

Nome da Ferramenta	Descrição
add_stopwords	Adicione stopwords personalizadas a um índice. Elas são adicionadas além do dicionário padrão específico do idioma.
delete_all_stopwords	Exclua todas as stopwords personalizadas de um índice. Isso afeta apenas as stopwords personalizadas, não o dicionário de idioma padrão.
delete_stopwords	Exclua stopwords personalizadas específicas de um índice. Isso afeta apenas as stopwords personalizadas, não o dicionário de idioma padrão.
get_index_stopwords	Obtenha todas as stopwords de um índice, incluindo tanto o dicionário de idioma padrão quanto as stopwords personalizadas.

Gerenciamento de Sinônimos

Nome da Ferramenta	Descrição
add_synonyms	Adicione sinônimos a um índice. Sinônimos funcionam apenas com consultas difusas, não com consultas de correspondência exata.
delete_all_synonyms	Exclua todos os sinônimos de um índice.
delete_synonyms	Exclua sinônimos específicos de um índice por suas chaves.
get_index_synonyms	Obtenha todos os sinônimos definidos para um índice.

Busca e Análises

Nome da Ferramenta	Descrição
get_measure_conversion	Obtenha dados de conversão de medição com parâmetros opcionais de filtragem e agregação. *requer Clickhouse se executado localmente
get_measure_summary	Obtenha dados de resumo de medição com parâmetros opcionais de filtragem e agregação. *requer Clickhouse se executado localmente
get_search_results	Executa uma consulta de busca usando a API Searchcraft com suporte para correspondência difusa/exata, facetas e intervalos de datas.
get_prelim_search_data	Obtenha campos de esquema e informações de facetas para um índice de busca para entender os campos disponíveis para construir consultas.
get_searchcraft_status	Obtenha o status atual do serviço de busca Searchcraft.

Ferramentas de Importação

Essas ferramentas fornecem fluxos de trabalho para importar dados JSON e gerar automaticamente esquemas Searchcraft. Perfeitas para configurar rapidamente novos índices a partir de fontes de dados existentes.

Nome da Ferramenta	Descrição
analyze_json_from_file	Leia dados JSON de um arquivo local e analise sua estrutura para entender tipos de campos e padrões para geração de esquema de índice Searchcraft.
analyze_json_from_url	Busque dados JSON de uma URL e analise sua estrutura para entender tipos de campos e padrões para geração de esquema de índice Searchcraft.
generate_searchcraft_schema	Gere um esquema de índice Searchcraft completo a partir da estrutura JSON analisada, com opções personalizáveis para campos de busca, pesos e outras configurações de índice.
create_index_from_json	Fluxo de trabalho completo para criar um índice Searchcraft a partir de dados JSON. Busca JSON de URL ou arquivo, analisa a estrutura, gera o esquema, cria o índice e adiciona todos os documentos em uma única etapa.

Fluxo de Trabalho das Ferramentas de Importação

As ferramentas de importação são projetadas para trabalhar juntas em um fluxo de trabalho simplificado:

1. Analisar → Use analyze_json_from_file ou analyze_json_from_url para examinar a estrutura dos seus dados JSON
2. Gerar → Use generate_searchcraft_schema para criar um esquema Searchcraft personalizado a partir da análise
3. Criar → Use a ferramenta create_index da API do Mecanismo para criar o índice com o esquema gerado
4. Importar → Use add_documents para popular seu novo índice com dados

Ou use a abordagem tudo-em-um:

• Uma Etapa → Use create_index_from_json para analisar, gerar esquema, criar o índice e importar todos os documentos em um único comando

Ferramentas de Geração de Aplicativos

Essas ferramentas criam aplicativos de busca completos e prontos para execução a partir dos seus dados JSON, perfeitos para prototipagem e demonstrações.

Nome da Ferramenta	Descrição
create_vite_app	Cria um aplicativo de busca completo em Vite + React a partir de dados JSON. Analisa a estrutura dos seus dados, gera modelos de busca otimizados e cria um aplicativo web totalmente funcional com integração Searchcraft.

Fluxo de Trabalho de Geração de Aplicativos

As ferramentas de geração de aplicativos fornecem uma solução de ponta a ponta para criar aplicativos de busca:

1. Análise de Dados → Analisa automaticamente sua estrutura JSON para entender tipos de campos e conteúdo
2. Geração de Modelos → Cria modelos de resultados de busca otimizados com base nos campos dos seus dados
3. Criação do Aplicativo → Clona e configura um aplicativo completo em Vite + React
4. Configuração do Ambiente → Configura as configurações de conexão do Searchcraft
5. Pronto para Executar → Fornece um aplicativo de busca totalmente funcional que você pode iniciar e personalizar imediatamente

Uso Detalhado das Ferramentas

Usando create_index_from_json

A ferramenta create_index_from_json fornece um fluxo de trabalho completo para criar um índice Searchcraft a partir de dados JSON em um único comando. Isso é perfeito para configurar rapidamente índices de busca a partir de conjuntos de dados existentes. Observe que, se você souber o idioma dos dados que está importando, deve especificá-lo com o parâmetro language (use o código de duas letras ISO 639-1 para o idioma)

Parâmetros

Parâmetro	Tipo	Obrigatório	Descrição
source	"url" ou "file"	✅	Se deve buscar dados de uma URL ou ler de um arquivo local
path	string	✅	URL ou caminho do arquivo para os dados JSON
index_name	string	✅	Nome para o novo índice Searchcraft
sample_size	number	❌	Número de itens a analisar para geração de esquema (padrão: 10)
search_fields	string[]	❌	Substituir campos de busca detectados automaticamente
weight_multipliers	object	❌	Pesos de campo personalizados para relevância de busca (0.0-10.0)
language	string	❌	Código de idioma para o índice (por exemplo, "en", "es")
auto_commit_delay	number	❌	Atraso de commit automático em segundos
exclude_stop_words	boolean	❌	Se deve excluir stopwords da busca
time_decay_field	string	❌	Nome do campo para decaimento de relevância baseado em tempo

Exemplo de Uso

De uma 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
  }
}

De um arquivo local:

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

O que ele faz

1. Busca/Lê Dados → Baixa de URL ou lê de arquivo local
2. Analisa a Estrutura → Examina o JSON para entender tipos de campos e padrões
3. Gera Esquema → Cria um esquema de índice Searchcraft otimizado
4. Cria Índice → Configura o índice no seu cluster Searchcraft
5. Importa Documentos → Adiciona todos os dados JSON como documentos pesquisáveis
6. Retorna Resumo → Fornece informações detalhadas sobre o que foi criado

Formato JSON Esperado

A ferramenta funciona com várias estruturas JSON:

• Matriz de objetos: [{...}, {...}, ...]
• Objeto com propriedade de matriz: {"data": [{...}, {...}], "meta": {...}}
• Objeto único: {...} (será tratado como um único documento)

A ferramenta encontra automaticamente a melhor matriz de objetos para usar no índice.

Usando create_vite_app

A ferramenta create_vite_app cria um aplicativo de busca completo e pronto para execução a partir dos seus dados JSON. É perfeita para prototipar rapidamente interfaces de busca ou criar aplicativos de demonstração.

Parâmetros

Parâmetro	Tipo	Obrigatório	Descrição
data_source	"url" ou "file"	✅	Se deve buscar dados de uma URL ou ler de um arquivo local
data_path	string	✅	URL ou caminho do arquivo para os dados JSON
app_name	string	✅	Nome para o aplicativo gerado (usado para o nome do diretório)
VITE_ENDPOINT_URL	string	✅	URL do endpoint do seu cluster Searchcraft
VITE_INDEX_NAME	string	✅	Nome do índice Searchcraft para conectar
VITE_READ_KEY	string	✅	Chave de leitura Searchcraft para o aplicativo
sample_size	number	❌	Número de itens para analisar na geração de templates (padrão: 50)
search_fields	string[]	❌	Substituir campos de busca detectados automaticamente
weight_multipliers	object	❌	Pesos personalizados de campos para relevância de busca (0.0-10.0)

Exemplo de Uso

Se você viu o prompt anteriormente na documentação, pode facilmente usar a ferramenta create_vite_app com linguagem natural. No entanto, se você quiser um controle mais refinado, pode usar a ferramenta com parâmetros JSON.

Criando um aplicativo de busca de produtos:

{
  "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
  }
}

Criando um aplicativo de busca de blog a partir de dados locais:

{
  "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"
}

O que ele faz

1. Analisa a Estrutura dos Dados → Examina seu JSON para entender os tipos de campos e padrões de conteúdo
2. Gera Templates de Busca → Cria templates otimizados de exibição de resultados com base nos seus dados
3. Clona o Template Vite → Baixa o template oficial Searchcraft Vite + React
4. Instala Dependências → Configura todos os pacotes npm necessários
5. Configura o Ambiente → Cria o arquivo .env com suas configurações do Searchcraft
6. Personaliza Templates → Gera componentes dinâmicos de resultados de busca
7. Atualiza o Código do Aplicativo → Modifica o aplicativo principal com sua marca e configuração específicas

Recursos do Aplicativo Gerado

O aplicativo criado inclui:

• React + Vite → Configuração de desenvolvimento moderna e rápida
• Integração com o SDK Searchcraft → Funcionalidade completa de busca pronta para uso
• Design Responsivo → Funciona em dispositivos desktop e móveis
• Templates Gerados Automaticamente → Exibição inteligente de resultados com base na estrutura dos seus dados
• Configuração de Ambiente → Configuração fácil para diferentes ambientes
• Servidor de Desenvolvimento → Recarga automática para personalização rápida

Lógica de Geração de Templates

A ferramenta analisa inteligentemente seus dados para criar templates de resultados de busca otimizados:

• Detecção de Campo de Título → Encontra o melhor campo para usar como título principal
• Detecção de Campo de Descrição → Identifica campos de texto descritivos
• Detecção de Campo de Imagem → Localiza URLs de imagens para resultados visuais
• Detecção de Campo de Data → Encontra campos de timestamp para ordenação temporal
• Campos Adicionais → Inclui outros campos de texto relevantes para resultados abrangentes

Próximos Passos Após a Criação

Depois que o aplicativo for criado, você pode:

1. Iniciar o Servidor Vite:

   cd apps/your-app-name
   yarn dev
   

2. Personalizar o Estilo → Modificar CSS e componentes para combinar com sua marca

3. Adicionar Recursos → Estender com filtros, facetas ou opções avançadas de busca

4. Implantar → Compilar e implantar na plataforma de hospedagem de sua preferência

Pré-requisitos

• Índice Searchcraft Existente → O índice especificado em VITE_INDEX_NAME já deve existir
• Chave de Leitura Válida → A VITE_READ_KEY deve ter permissões de leitura para o índice
• Git Disponível → A ferramenta usa git para clonar o repositório do template
• Node.js e Yarn → Necessários para a instalação de dependências

Fluxo de Trabalho Completo: De JSON a Aplicativo de Busca

Aqui está como usar ambas as ferramentas juntas para ir de dados JSON brutos a um aplicativo de busca totalmente funcional:

Opção 1: Processo em Duas Etapas (Recomendado para Produção)

Etapa 1: Criar o Índice 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"
}

Etapa 2: Criar o Aplicativo de Busca

{
  "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
  }
}

Opção 2: Processo Somente com Aplicativo (Para Índices Existentes)

Se você já tem um índice Searchcraft configurado, pode ir direto para a criação do aplicativo:

{
  "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"
}

Benefícios da Abordagem em Duas Etapas

• Otimização do Índice → Ajuste fino do seu índice de busca separadamente da interface
• Múltiplos Aplicativos → Crie diferentes interfaces de busca para os mesmos dados
• Pronto para Produção → Melhor separação de preocupações para implantações em produção
• Depuração Mais Fácil → Teste a funcionalidade de busca independentemente da interface

Começando

Variáveis de Ambiente

Crie o arquivo .env na raiz do projeto e preencha os 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.

Exemplo de .env

Uso Remoto

Se você já criou um índice através do Vektron no Searchcraft Cloud, pode usar a chave de escrita para o índice que está tentando acessar e usar o servidor MCP para operações de API que não exigem privilégios de administrador. IMPORTANTE: Se você usar o servidor MCP com uma chave de escrita, ela NÃO deve ser exposta publicamente na internet. As chaves de escrita são destinadas a serem protegidas e, ao executar um servidor MCP, qualquer usuário com acesso ao servidor MCP poderá escrever no índice ou excluir dados.

Instalação e Configuração

Certifique-se de que seu ambiente tenha a versão correta do node selecionada.

nvm use

Instale as dependências com yarn

yarn

Compile o servidor

yarn build

Isso cria duas versões do servidor:

• dist/server.js - Servidor HTTP para teste e implantação remota
• dist/stdio-server.js - Servidor stdio para Claude Desktop

Uso

Opção 1: Claude Desktop (stdio) - Recomendado

Para uso local com Claude Desktop, use a versão stdio que oferece melhor desempenho e confiabilidade.

claude_desktop_config.json

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

O arquivo de configuração do Claude Desktop pode ser encontrado em:

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

Se o arquivo não existir, crie-o.

Opção 2: Claude Code

Para uso com Claude Code, use a CLI para configurar o servidor MCP:

Configuração básica:

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

Com variáveis de ambiente:

# 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

Escopos de configuração:

• --scope local (padrão): Disponível apenas para você no projeto atual
• --scope project: Compartilhado com a equipe via arquivo .mcp.json (recomendado para equipes)
• --scope user: Disponível para você em todos os projetos

Gerenciando servidores:

# List configured servers
claude mcp list

# Check server status
/mcp

# Remove server
claude mcp remove searchcraft

Opção 3: Open WebUI (via Pipelines)

O Open WebUI suporta servidores MCP através do seu framework Pipelines. Isso requer a criação de um pipeline personalizado que conecta seu servidor MCP ao Open WebUI.

Etapa 1: Iniciar o servidor HTTP do Searchcraft MCP

yarn start  # Starts HTTP server on port 3100

Etapa 2: Criar um Pipeline MCP para Open WebUI

Crie um arquivo chamado 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

Etapa 3: Instalar o Pipeline no Open WebUI

1. Via Painel de Administração:

   • Vá para Configurações de Administrador → Pipelines
   • Clique em "Adicionar Pipeline"
   • Cole o código do pipeline acima
   • Configure as válvulas com suas configurações do Searchcraft:
     • MCP_SERVER_URL: http://localhost:3100/mcp
     • ENDPOINT_URL: URL do seu cluster Searchcraft
     • CORE_API_KEY: Sua chave de API Searchcraft

2. Via Ambiente 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
   

Etapa 4: Configurar o Open WebUI para usar Pipelines

1. Inicie o Open WebUI com suporte a 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!
   

2. Em Configurações do Open WebUI → Conexões:

   • Defina a URL da API OpenAI para sua instância de Pipelines
   • Ative o Pipeline MCP do Searchcraft

Opção 4: Servidor HTTP (para teste/implantação remota)

Inicie o servidor HTTP para teste, depuração ou implantação remota:

yarn start  # Starts HTTP server on port 3100

Para Claude Desktop com servidor HTTP, você precisará do mcp-remote:

claude_desktop_config.json

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

Opção 5: Docker

Execute o servidor MCP Searchcraft em um contêiner Docker para fácil implantação e portabilidade.

Compilar a imagem Docker:

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

Executar o contêiner:

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

Testar o 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"}}}'

Inspeção remota com MCP Inspector:

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

Configuração Docker:

• Usa Node.js 22-slim como imagem base
• Expõe a porta 3100 por padrão (configurável via variável de ambiente PORT)
• Gerencia automaticamente o desligamento gracioso em SIGINT/SIGTERM
• Otimizado para produção com tamanho mínimo de imagem

Variáveis de Ambiente:

• PORT - Porta do servidor HTTP (padrão: 8000)
• ENDPOINT_URL - URL do endpoint do seu cluster Searchcraft
• CORE_API_KEY - Sua chave de API Searchcraft
• DEBUG - Ativar registro de depuração (opcional)

Scripts Disponíveis

# 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

Comparação de Opções de Implantação

Recurso	stdio (Recomendado)	HTTP (Local)	Docker
Desempenho	✅ Melhor (IPC direto)	⚠️ Sobrecarga HTTP	✅ Bom
Segurança	✅ Sem portas expostas	⚠️ Porta de rede necessária	✅ Ambiente isolado
Complexidade de Configuração	✅ Simples	⚠️ Gerenciamento de porta necessário	✅ Simples (um comando)
Claude Desktop	✅ Suporte nativo	⚠️ Requer mcp-remote	⚠️ Requer mcp-remote
Claude Code	✅ Suporte nativo	✅ Suportado	✅ Suportado
Open WebUI	❌ Não suportado	✅ Via Pipelines	✅ Via Pipelines
Implantação Remota	❌ Somente local	✅ Possível, mas manual	✅ Contêinerização fácil
Teste	⚠️ Requer ferramentas MCP	✅ Fácil com curl	✅ Fácil com curl
Múltiplos Clientes	❌ Um por vez	✅ Acesso concorrente	✅ Acesso concorrente
Portabilidade	⚠️ Node.js necessário	⚠️ Node.js necessário	✅ Executa em qualquer lugar

Use stdio quando:

• Usar Claude Desktop ou Claude Code localmente
• Quiser o melhor desempenho absoluto
• Preferir comunicação direta entre processos

Use HTTP (local) quando:

• Precisar testar/depurar a interface HTTP
• Estiver desenvolvendo integrações personalizadas
• Precisar de múltiplos clientes locais concorrentes

Use Docker quando:

• Precisar de implantação remota
• Quiser configuração fácil e reproduzível
• Estiver implantando em plataformas de nuvem
• Quiser isolamento e segurança
• Precisar publicar seu servidor para inspeção

Teste

O Servidor MCP Searchcraft inclui uma suíte de testes abrangente construída com Vitest.

Executar Testes

# 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 Testes

• ✅ 89 testes cobrindo funcionalidade principal
• ✅ 84%+ de cobertura em helpers e utilitários
• ✅ 93%+ de cobertura no analisador JSON
• ✅ 100% de cobertura na criação do servidor
• ✅ Testes de integração para endpoints HTTP
• ✅ Testes unitários para todos os componentes principais

Consulte test/README.md para documentação detalhada de testes.

Depuração

Logs do Claude Desktop

Para visualizar os logs do Claude Desktop para depuração de conexões MCP:

yarn claude-logs

Teste com MCP Inspector

O MCP Inspector permite testar as ferramentas do seu servidor interativamente.

Para servidor stdio (recomendado):

yarn inspect

• Escolha o Tipo de Transporte: stdio
• Comando: node dist/stdio-server.js

Para servidor HTTP:

yarn start  # Start HTTP server first
yarn inspect

• Escolha o Tipo de Transporte: HTTP Streamable
• URL: http://localhost:3100/mcp

Teste Manual

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

Testar 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

• 📘 Documentação Searchcraft
• 🛰️ Painel Vektron
• 💬 Discord Searchcraft
• 🧠 Reddit Searchcraft
• 🧪 SDK Searchcraft no npm

Problemas e Solicitações de Recursos

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

Licença

Licenciado sob a Licença Apache 2.0.

Construído com 🛰️ pela equipe Searchcraft