Parquet MCP Server

parquet_mcp_server

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

1. Busca na Web: Realizar uma busca na web e extrair resultados
2. Busca por Similaridade: Extrair informações relevantes de buscas anteriores

Este servidor é particularmente útil para:

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

Instalação

Instalando via Smithery

Para instalar o Parquet MCP Server para o 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 o Claude Desktop

Adicione isto 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. Buscar na Web: Realizar uma busca na web e extrair resultados

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

2. Extrair Informações da Busca: Extrair informações relevantes de buscas anteriores

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

Exemplos de Prompts

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

Para Busca na Web:

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

Para Extrair Informações da Busca:

"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 executar 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, certifique-se de que as configurações 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 de 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()
);