QuantConnect PDF MCP Server

Convierte la documentación en PDF de QuantConnect a markdown con capacidad de búsqueda, permitiendo búsquedas rápidas y conscientes del contexto.

GitHub
5
Prueba este MCPPatrocinado

Documentación

Motor de Conocimiento del Servidor MCP

Un potente servidor de Protocolo de Contexto de Modelos (MCP) que transforma cualquier colección de documentos PDF en una base de conocimiento inteligente y buscable, accesible a través de Claude Desktop. Este servidor cuenta con capacidades avanzadas de búsqueda mediante puntuación TF-IDF, coincidencia por proximidad y optimización específica por dominio.

🌟 Características Principales

  • 🔍 Motor de Búsqueda Avanzado: Índice invertido basado en TF-IDF con coincidencia por proximidad para resultados altamente relevantes
  • 📄 Soporte Universal de PDF: Procesa cualquier colección de PDF: documentación técnica, documentos legales, investigaciones y más
  • ⚡ Alto Rendimiento: Índice de búsqueda en caché, procesamiento incremental e inicialización en segundo plano
  • 🎯 Optimización por Dominio: Configura palabras clave específicas del dominio para mejorar la precisión de búsqueda
  • ⚙️ Totalmente Configurable: Configuración basada en JSON con soporte de variables de entorno
  • 🛠️ CLI Integral: Gestión completa del servidor mediante comandos intuitivos
  • 🔗 Integración MCP sin Problemas: Listo para usar con Claude Desktop, VS Code y otros clientes MCP
  • 📊 Caché Inteligente: Detección de cambios basada en hash MD5 para actualizaciones eficientes

📋 Inicio Rápido

Requisitos Previos

  • Python 3.8 o superior
  • pip (gestor de paquetes de Python)
  • Aplicación Claude Desktop (para integración MCP)

1. Instalación

# Clone the repository
git clone https://github.com/lhstorm/mcp_server_knowledge_engine.git
cd mcp_server_knowledge_engine

# Create virtual environment (recommended)
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

2. Crea Tu Servidor

# Interactive setup
python manage_server.py create-config

# This will ask you for:
# - Server name (e.g., 'legal-docs-server')
# - Display name (e.g., 'Legal Documents Server')
# - PDF folder location
# - Domain-specific keywords

3. Añade Documentos PDF

# Add individual PDFs
python manage_server.py add-pdf /path/to/document.pdf
python manage_server.py add-pdf /path/to/another-doc.pdf

# Or copy PDFs directly to your configured folder

4. Procesa Documentos

# Convert PDFs to searchable format
python manage_server.py process-pdfs

5. Genera Configuración MCP

# Generate configuration for Claude Desktop
python generate_mcp_config.py --merge

# Or get the config to copy manually
python generate_mcp_config.py

6. Comienza a Usar con Claude

Reinicia Claude Desktop y tu servidor aparecerá en el menú de herramientas MCP.

💬 Uso con Claude Desktop

Una vez configurado, puedes interactuar con tus PDFs de forma natural:

Ejemplos de consultas:

  • "Busca información sobre [tema] en la documentación"
  • "¿Qué dice la documentación sobre [característica específica]?"
  • "Encuentra todas las referencias a [palabra clave] en todos los PDFs"
  • "Muéstrame el contenido de [nombre del documento]"
  • "Lista todos los documentos disponibles"

Uso avanzado:

  • "Busca [término1] cerca de [término2]" - Aprovecha la coincidencia por proximidad
  • "Obtén la página 15 de [documento]" - Recupera páginas específicas
  • "Encuentra los 10 mejores resultados para [consulta]" - Ajusta el número de resultados

📁 Estructura del Proyecto

mcp_server_knowledge_engine/
├── server.py              # Main MCP server with search engine
├── config.py              # Configuration management & validation
├── manage_server.py       # CLI for server management
├── generate_mcp_config.py # MCP configuration generator
├── convert_pdfs.py        # Standalone PDF conversion utility
├── server_config.json     # Active server configuration
├── requirements.txt       # Python dependencies
├── examples/              # Example configurations
│   ├── legal_docs_config.json
│   ├── medical_docs_config.json
│   ├── research_papers_config.json
│   └── tech_docs_config.json
└── your-pdfs/             # Your PDF folder (configurable)
    ├── document1.pdf
    ├── document2.pdf
    └── markdown/          # Auto-generated cache
        ├── .pdf_cache.json      # Processing metadata
        ├── .search_index.pkl    # Cached search index
        ├── document1.md         # Converted documents
        └── document2.md

⚙️ Configuración

El servidor se configura mediante server_config.json:

{
  "server": {
    "name": "my-docs-server",
    "display_name": "My Documents Server", 
    "description": "Search through my PDF collection",
    "version": "1.0.0"
  },
  "storage": {
    "pdf_folder": "./docs",
    "markdown_folder": "./docs/markdown",
    "domain_keywords": ["keyword1", "keyword2", "domain-term"]
  },
  "tools": {
    "search": {
      "name": "search_docs",
      "description": "Search through PDF documentation"
    },
    "list": {
      "name": "list_docs", 
      "description": "List all available documents"
    },
    "content": {
      "name": "get_document_content",
      "description": "Get full content from documents"
    },
    "max_results_default": 5
  },
  "processing": {
    "cache_enabled": true,
    "parallel_processing": true,
    "max_file_size_mb": 50,
    "context_size": 500
  }
}

🛠️ Comandos de Gestión

Gestión del Servidor

# Create new configuration
python manage_server.py create-config

# Test configuration
python manage_server.py test

# Generate MCP config
python manage_server.py generate-mcp-config

Gestión de PDFs

# List all PDFs
python manage_server.py list-pdfs

# Add PDF
python manage_server.py add-pdf document.pdf

# Remove PDF  
python manage_server.py remove-pdf document.pdf

# Process all PDFs
python manage_server.py process-pdfs

Configuración MCP

# Print MCP config
python generate_mcp_config.py

# Automatically merge with Claude Desktop config
python generate_mcp_config.py --merge

# Save to file
python generate_mcp_config.py --output my_mcp_config.json

💡 Ejemplos de Uso

Servidor de Documentos Legales

{
  "server": {
    "name": "legal-docs-server",
    "display_name": "Legal Documents Server"
  },
  "storage": {
    "domain_keywords": ["contract", "liability", "jurisdiction", "plaintiff", "defendant"]
  }
}

Servidor de Documentación Técnica

{
  "server": {
    "name": "tech-docs-server", 
    "display_name": "Technical Documentation Server"
  },
  "storage": {
    "domain_keywords": ["API", "function", "class", "method", "parameter", "return"]
  }
}

Servidor de Artículos de Investigación

{
  "server": {
    "name": "research-server",
    "display_name": "Research Papers Server"
  },
  "storage": {
    "domain_keywords": ["hypothesis", "methodology", "results", "conclusion", "analysis"]
  }
}

🔧 Herramientas MCP Disponibles

Cada servidor proporciona tres herramientas configurables:

  1. Herramienta de Búsqueda (predeterminada: search_docs)

    • Búsqueda inteligente en todos los documentos
    • Puntuación TF-IDF con coincidencia por proximidad
    • Devuelve extractos relevantes con contexto

  2. Herramienta de Listado (predeterminada: list_docs)

    • Lista todos los documentos disponibles
    • Muestra metadatos de documentos y recuentos de páginas

  3. Herramienta de Contenido (predeterminada: get_document_content)

    • Recupera el contenido completo del documento
    • Puede obtener páginas específicas
    • Incluye formato Markdown completo

🎯 Personalización por Dominio

El servidor se adapta a tu dominio mediante:

  • Palabras Clave del Dominio: Configura términos importantes para tu campo
  • Nombres de Herramientas: Personaliza los nombres de las herramientas (por ejemplo, search_legal_docs)
  • Descripciones: Adapta las descripciones para tu caso de uso
  • Tamaño del Contexto: Ajusta cuánto contexto devolver en los resultados de búsqueda

🔍 Cómo Funciona el Motor de Búsqueda

Arquitectura de Índice Invertido

El servidor utiliza un índice invertido avanzado para búsquedas ultrarrápidas:

  1. Procesamiento de Documentos: Los PDFs se convierten a Markdown y se tokenizan
  2. Construcción del Índice: Las palabras se asignan a sus ubicaciones (documento, página, posición)
  3. Puntuación TF-IDF:
    • TF (Frecuencia de Término): Con qué frecuencia aparece una palabra en un documento
    • IDF (Frecuencia Inversa de Documento): Qué tan rara es una palabra en todos los documentos
    • La puntuación combinada garantiza que los resultados relevantes y únicos se clasifiquen más alto

Funciones de Búsqueda

  • Impulso por Proximidad: Las consultas de múltiples palabras puntúan más alto cuando los términos aparecen cerca
  • Extracción de Contexto: Devuelve fragmentos relevantes con términos de búsqueda resaltados
  • Reconocimiento de Palabras Clave del Dominio: Las palabras clave configuradas reciben tratamiento especial
  • Precisión a Nivel de Página: Los resultados incluyen números de página específicos
  • Caché Inteligente: El índice de búsqueda persiste entre reinicios del servidor

📊 Optimizaciones de Rendimiento

  • Procesamiento Incremental: Detección de cambios basada en hash MD5: solo se procesan PDFs nuevos o modificados
  • Índice de Búsqueda Persistente: El índice serializado se carga instantáneamente al reiniciar el servidor
  • Inicialización en Segundo Plano: El servidor acepta conexiones mientras construye el índice
  • Eficiencia de Memoria: Procesamiento de PDFs por flujo y almacenamiento en Markdown
  • Límites Configurables: Controla los límites de tamaño de archivo y los parámetros de procesamiento

🐛 Solución de Problemas

Problemas Comunes y Soluciones

El servidor no aparece en Claude Desktop:

  • Asegúrate de que la configuración MCP se haya fusionado: python generate_mcp_config.py --merge
  • Verifica la ruta de Python: which python o where python (Windows)
  • Comprueba que server_config.json exista y sea JSON válido
  • Reinicia Claude Desktop después de los cambios de configuración

Los PDFs no se procesan:

  • Verifica los permisos de la carpeta: ls -la /path/to/pdf/folder
  • Comprueba que los archivos PDF no estén corruptos: file document.pdf
  • Busca errores en stderr: python server.py 2>error.log
  • Asegúrate de tener suficiente espacio en disco para la caché de Markdown

La búsqueda no devuelve resultados o devuelve resultados pobres:

  • La indexación inicial puede llevar tiempo: verifica el progreso en stderr
  • Verifica que los archivos Markdown existan: ls markdown/*.md
  • Comprueba que el índice de búsqueda exista: ls markdown/.search_index.pkl
  • Prueba primero con consultas de una sola palabra y luego amplía
  • Revisa las palabras clave del dominio en la configuración

El servidor se bloquea o se cuelga:

  • Verifica la versión de Python (se requiere 3.8+): python --version
  • Comprueba que todas las dependencias estén instaladas: pip install -r requirements.txt
  • Limpia la caché y reprocesa: rm -rf markdown/.pdf_cache.json markdown/.search_index.pkl
  • Verifica problemas de bloqueo de archivos en Windows

Modo de Depuración

# Run with full debug output
python server.py 2>&1 | tee debug.log

# Check server initialization
grep "initialization" debug.log

# Monitor PDF processing
grep "Processing\|Error" debug.log

Comandos de Validación

# Test configuration validity
python manage_server.py test

# Verify configuration loading
python -c "from config import load_config_from_env_or_file; c=load_config_from_env_or_file(); print(f'✓ Config loaded: {c.server.name}')"

# Check MCP integration
python generate_mcp_config.py  # Should output valid JSON

🚀 Uso Avanzado

Múltiples Servidores

Puedes ejecutar múltiples servidores especializados:

# Legal documents server
python manage_server.py --config legal_config.json create-config

# Technical docs server  
python manage_server.py --config tech_config.json create-config

# Research papers server
python manage_server.py --config research_config.json create-config

Procesamiento por Lotes

# Process multiple PDF folders
for folder in docs legal_docs tech_docs; do
    python convert_pdfs.py "$folder" "$folder/markdown"
done

Palabras Clave Personalizadas

Configura palabras clave específicas del dominio para una mejor relevancia de búsqueda:

{
  "storage": {
    "domain_keywords": [
      "algorithm", "data structure", "complexity",
      "optimization", "performance", "scalability"
    ]
  }
}

🏗️ Descripción General de la Arquitectura

Componentes Principales

  1. Clase SearchIndex (server.py:27-140)

    • Implementa el índice invertido con puntuación TF-IDF
    • Maneja la tokenización de palabras y la indexación de documentos
    • Proporciona clasificación basada en proximidad para consultas de múltiples palabras

  2. Clase GenericPDFServer (server.py:142-661)

    • Implementación principal del servidor con manejo del protocolo MCP
    • Gestiona el pipeline de procesamiento de PDFs
    • Maneja operaciones asíncronas e inicialización en segundo plano

  3. Sistema de Configuración (config.py)

    • Configuración segura por tipos basada en dataclasses
    • Validación de esquema JSON
    • Soporte de variables de entorno

  4. CLI de Gestión (manage_server.py)

    • Creación interactiva de configuración
    • Operaciones de gestión de PDFs
    • Pruebas y validación del servidor

Flujo de Datos

PDFs → PDF Reader → Markdown Converter → Search Index → MCP Tools → Claude
         ↓                    ↓                ↓
    [.pdf files]      [.md cache files]  [.search_index.pkl]

🔄 Configuración Actual del Servidor

El repositorio incluye actualmente una configuración para la documentación de QuantConnect (server_config.json). Para crear tu propio servidor:

# Option 1: Interactive setup
python manage_server.py create-config

# Option 2: Copy and modify an example
cp examples/tech_docs_config.json server_config.json
# Edit server_config.json with your settings

📚 Casos de Uso de Ejemplo

  • Bufetes de Abogados: Busca en contratos, expedientes de casos y documentos legales
  • Laboratorios de Investigación: Consulta artículos científicos e informes técnicos
  • Equipos de Software: Accede a documentación de API y especificaciones técnicas
  • Consultas Médicas: Busca registros de pacientes y literatura médica
  • Instituciones Educativas: Explora materiales de cursos y libros de texto

🤝 Contribuciones

¡Damos la bienvenida a contribuciones! Aquí hay algunas formas de ayudar:

Ideas de Mejora

  1. Soporte de Formatos de Documento: Añade soporte para Word, HTML u otros formatos
  2. Mejoras de Búsqueda: Implementa búsqueda semántica, coincidencia difusa o clasificación basada en ML
  3. Rendimiento: Añade backend de base de datos, procesamiento paralelo o indexación distribuida
  4. Herramientas: Crea herramientas MCP especializadas para dominios específicos
  5. Interfaz de Usuario: Construye una interfaz web para la gestión de configuración

Directrices de Desarrollo

  • Sigue el estilo y los patrones de código existentes
  • Añade pruebas para nuevas funcionalidades
  • Actualiza la documentación para nuevas características
  • Envía solicitudes de extracción con descripciones claras

🔐 Consideraciones de Seguridad

  • El servidor solo tiene acceso de lectura a las carpetas de PDF especificadas
  • No se realizan llamadas de red externas durante la operación
  • Los datos sensibles permanecen locales: nada se envía a servicios externos
  • Configura permisos de archivo apropiados para tus carpetas de PDF

📄 Licencia

Este proyecto es de código abierto. Consulta el archivo LICENSE para más detalles.

🙏 Agradecimientos

Construido con el Protocolo de Contexto de Modelos de Anthropic.

¿Listo para transformar tus PDFs en una base de conocimiento buscable?

Ejecuta python manage_server.py create-config para comenzar. 🚀

📦 Dependencias

  • mcp: SDK del Protocolo de Contexto de Modelos para construir servidores MCP
  • PyPDF2: Análisis de PDFs y extracción de texto
  • asyncio: E/S asíncrona para operaciones concurrentes
  • jsonschema: Validación JSON para archivos de configuración

Todas las dependencias son ligeras y tienen requisitos mínimos del sistema.