Parquet MCP Server

parquet_mcp_server

Un potente servidor MCP (Protocolo de Control de Modelos) que proporciona herramientas para realizar búsquedas web y encontrar contenido similar. Este servidor está diseñado para funcionar con Claude Desktop y ofrece dos funcionalidades principales:

1. Búsqueda Web: Realiza una búsqueda web y extrae los resultados
2. Búsqueda de Similitud: Extrae información relevante de búsquedas anteriores

Este servidor es particularmente útil para:

• Aplicaciones que requieren capacidades de búsqueda web
• Proyectos que necesitan encontrar contenido similar basado en consultas de búsqueda

Instalación

Instalación mediante Smithery

Para instalar Parquet MCP Server para Claude Desktop automáticamente mediante Smithery:

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

Clonar este repositorio

git clone ...
cd parquet_mcp_server

Crear y activar el entorno virtual

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

Instalar el paquete

uv pip install -e .

Entorno

Crea un archivo .env con las siguientes variables:

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 con Claude Desktop

Agrega esto a tu archivo de configuración de 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"
      ]
    }
  }
}

Herramientas Disponibles

El servidor proporciona dos herramientas principales:

1. Buscar en la Web: Realiza una búsqueda web y extrae los resultados

   • Parámetros requeridos:
     • queries: Lista de consultas de búsqueda
   • Parámetros opcionales:
     • page_number: Número de página para los resultados de búsqueda (por defecto es 1)

2. Extraer Información de la Búsqueda: Extrae información relevante de búsquedas anteriores

   • Parámetros requeridos:
     • queries: Lista de consultas de búsqueda para fusionar

Ejemplos de Prompts

Aquí hay algunos ejemplos de prompts que puedes usar con el agente:

Para Búsqueda Web:

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

Para Extraer Información de la Búsqueda:

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

Pruebas del Servidor MCP

El proyecto incluye un conjunto completo de pruebas en el directorio src/tests. Puedes ejecutar todas las pruebas usando:

python src/tests/run_tests.py

O ejecutar pruebas individuales:

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

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

También puedes probar el servidor usando el cliente directamente:

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"])

Solución de Problemas

1. Si obtienes errores de verificación SSL, asegúrate de que la configuración SSL en tu archivo .env sea correcta
2. Si los embeddings no se generan, verifica:
   • Que el servidor Ollama esté ejecutándose y sea accesible
   • Que el modelo especificado esté disponible en tu servidor Ollama
   • Que la columna de texto exista en tu archivo Parquet de entrada
3. Si la conversión de DuckDB falla, verifica:
   • Que el archivo Parquet de entrada exista y sea legible
   • Que tengas permisos de escritura en el directorio de salida
   • Que el archivo Parquet no esté corrupto
4. Si la conversión de PostgreSQL falla, verifica:
   • Que la configuración de conexión de PostgreSQL en tu archivo .env sea correcta
   • Que el servidor PostgreSQL esté ejecutándose y sea accesible
   • Que tengas los permisos necesarios para crear/modificar tablas
   • Que la extensión pgvector esté instalada en tu base de datos

Función de PostgreSQL para Búsqueda de Similitud Vectorial

Para realizar búsquedas de similitud vectorial en PostgreSQL, puedes usar la siguiente función:

-- 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 función te permite realizar búsquedas de similitud en embeddings vectoriales almacenados en una base de datos PostgreSQL, devolviendo resultados que cumplan con un umbral de similitud especificado y limitando el número de resultados según la entrada del usuario. Los resultados se ordenan por fecha y similitud.

Creación de tabla en 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()
);