Search MCP Server

parquet_mcp_server

Um poderoso servidor MCP (Model Control Protocol) que fornece ferramentas para realizar pesquisas web e encontrar conteúdo semelhante. Este servidor foi projetado para funcionar com o Claude Desktop e oferece duas funcionalidades principais:

1. Web Search: Realize uma pesquisa web e extraia os resultados
2. Similarity Search: Extraia informações relevantes de pesquisas anteriores

Este servidor é particularmente útil para:

• Aplicações que exigem recursos de pesquisa web
• Projetos que precisam encontrar conteúdo semelhante com base em consultas de pesquisa

Instalação

Instalando via Smithery

Para instalar o Parquet MCP Server para Claude Desktop automaticamente via Smithery:

npx -y @smithery/cli install @DeepSpringAI/parquet_mcp_server --client claude

Clone este repositório

git clone ...
cd parquet_mcp_server

Crie e ative o ambiente virtual

uv venv
.venv\Scripts\activate  # On Windows
source .venv/bin/activate  # On macOS/Linux

Instale o pacote

uv pip install -e .

Ambiente

Crie um arquivo .env com as seguintes variáveis:

EMBEDDING_URL=http://sample-url.com/api/embed  # URL for the embedding service
OLLAMA_URL=http://sample-url.com/  # URL for Ollama server
EMBEDDING_MODEL=sample-model  # Model to use for generating embeddings
SEARCHAPI_API_KEY=your_searchapi_api_key
FIRECRAWL_API_KEY=your_firecrawl_api_key
VOYAGE_API_KEY=your_voyage_api_key
AZURE_OPENAI_ENDPOINT=http://sample-url.com/azure_openai
AZURE_OPENAI_API_KEY=your_azure_openai_api_key

Uso com Claude Desktop

Adicione isso ao seu arquivo de configuração do Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "parquet-mcp-server": {
      "command": "uv",
      "args": [
        "--directory",
        "/home/${USER}/workspace/parquet_mcp_server/src/parquet_mcp_server",
        "run",
        "main.py"
      ]
    }
  }
}

Ferramentas Disponíveis

O servidor fornece duas ferramentas principais:

1. Search Web: Realize uma pesquisa web e extraia os resultados

   • Parâmetros obrigatórios:
     • queries: Lista de consultas de pesquisa
   • Parâmetros opcionais:
     • page_number: Número da página para os resultados da pesquisa (padrão é 1)

2. Extract Info from Search: Extraia informações relevantes de pesquisas anteriores

   • Parâmetros obrigatórios:
     • queries: Lista de consultas de pesquisa para mesclar

Exemplos de Prompts

Aqui estão alguns exemplos de prompts que você pode usar com o agente:

Para Pesquisa Web:

"Please perform a web search for 'macbook' and 'laptop' and scrape the results from page 1"

Para Extrair Informações da Pesquisa:

"Please extract relevant information from the previous searches for 'macbook'"

Testando o Servidor MCP

O projeto inclui uma suíte de testes abrangente no diretório src/tests. Você pode executar todos os testes usando:

python src/tests/run_tests.py

Ou execute testes individuais:

# Test Web Search
python src/tests/test_search_web.py

# Test Extract Info from Search
python src/tests/test_extract_info_from_search.py

Você também pode testar o servidor usando o cliente diretamente:

from parquet_mcp_server.client import (
    perform_search_and_scrape,  # New web search function
    find_similar_chunks  # New extract info function
)

# Perform a web search
perform_search_and_scrape(["macbook", "laptop"], page_number=1)

# Extract information from the search results
find_similar_chunks(["macbook"])

Solução de Problemas

1. Se você receber erros de verificação SSL, verifique se as configurações de SSL no seu arquivo .env estão corretas
2. Se os embeddings não forem gerados, verifique:
   • Se o servidor Ollama está em execução e acessível
   • Se o modelo especificado está disponível no seu servidor Ollama
   • Se a coluna de texto existe no seu arquivo Parquet de entrada
3. Se a conversão DuckDB falhar, verifique:
   • Se o arquivo Parquet de entrada existe e é legível
   • Se você tem permissões de escrita no diretório de saída
   • Se o arquivo Parquet não está corrompido
4. Se a conversão PostgreSQL falhar, verifique:
   • Se as configurações de conexão PostgreSQL no seu arquivo .env estão corretas
   • Se o servidor PostgreSQL está em execução e acessível
   • Se você tem as permissões necessárias para criar/modificar tabelas
   • Se a extensão pgvector está instalada no seu banco de dados

Função PostgreSQL para Busca de Similaridade Vetorial

Para realizar buscas de similaridade vetorial no PostgreSQL, você pode usar a seguinte função:

-- Create the function for vector similarity search
CREATE OR REPLACE FUNCTION match_web_search(
  query_embedding vector(1024),  -- Adjusted vector size
  match_threshold float,
  match_count int  -- User-defined limit for number of results
)
RETURNS TABLE (
  id bigint,
  metadata jsonb,
  text TEXT,  -- Added text column to the result
  date TIMESTAMP,  -- Using the date column instead of created_at
  similarity float
)
LANGUAGE plpgsql
AS $$
BEGIN
  RETURN QUERY
  SELECT
    web_search.id,
    web_search.metadata,
    web_search.text,  -- Returning the full text of the chunk
    web_search.date,  -- Returning the date timestamp
    1 - (web_search.embedding <=> query_embedding) as similarity
  FROM web_search
  WHERE 1 - (web_search.embedding <=> query_embedding) > match_threshold
  ORDER BY web_search.date DESC,  -- Sort by date in descending order (newest first)
           web_search.embedding <=> query_embedding  -- Sort by similarity
  LIMIT match_count;  -- Limit the results to the match_count specified by the user
END;
$$;

Esta função permite realizar buscas de similaridade em embeddings vetoriais armazenados em um banco de dados PostgreSQL, retornando resultados que atendem a um limite de similaridade especificado e limitando o número de resultados com base na entrada do usuário. Os resultados são ordenados por data e similaridade.

Criação da tabela Postgres

CREATE TABLE web_search (
    id SERIAL PRIMARY KEY,
    text TEXT,
    metadata JSONB,
    embedding VECTOR(1024),

    -- This will be auto-updated
    date TIMESTAMP DEFAULT NOW()
);