QuantConnect PDF MCP Server

Converte a documentação em PDF do QuantConnect em markdown pesquisável, permitindo buscas rápidas e sensíveis ao contexto.

GitHub
5
Experimente este MCPPatrocinado

Documentação

MCP Server Knowledge Engine

Um poderoso servidor Model Context Protocol (MCP) que transforma qualquer coleção de documentos PDF em uma base de conhecimento inteligente e pesquisável, acessível através do Claude Desktop. Este servidor possui recursos avançados de busca usando pontuação TF-IDF, correspondência por proximidade e otimização específica de domínio.

🌟 Principais Recursos

  • 🔍 Mecanismo de Busca Avançado: Índice invertido baseado em TF-IDF com correspondência por proximidade para resultados altamente relevantes
  • 📄 Suporte Universal a PDF: Processe qualquer coleção de PDFs - documentação técnica, artigos jurídicos, pesquisas e muito mais
  • ⚡ Alto Desempenho: Índice de busca em cache, processamento incremental e inicialização em segundo plano
  • 🎯 Otimização de Domínio: Configure palavras-chave específicas do domínio para maior precisão na busca
  • ⚙️ Totalmente Configurável: Configuração baseada em JSON com suporte a variáveis de ambiente
  • 🛠️ CLI Abrangente: Gerenciamento completo do servidor através de comandos intuitivos
  • 🔗 Integração MCP Perfeita: Pronto para uso com Claude Desktop, VS Code e outros clientes MCP
  • 📊 Cache Inteligente: Detecção de alterações baseada em hash MD5 para atualizações eficientes

📋 Início Rápido

Pré-requisitos

  • Python 3.8 ou superior
  • pip (gerenciador de pacotes Python)
  • Aplicativo Claude Desktop (para integração MCP)

1. Instalação

# 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. Crie Seu 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. Adicione 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. Processe Documentos

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

5. Gere Configuração 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. Comece a Usar com Claude

Reinicie o Claude Desktop e seu servidor aparecerá no menu de ferramentas MCP!

💬 Usando com Claude Desktop

Uma vez configurado, você pode interagir com seus PDFs naturalmente:

Exemplos de prompts:

  • "Pesquise informações sobre [tópico] na documentação"
  • "O que a documentação diz sobre [recurso específico]?"
  • "Encontre todas as referências a [palavra-chave] em todos os PDFs"
  • "Mostre-me o conteúdo de [nome do documento]"
  • "Liste todos os documentos disponíveis"

Uso avançado:

  • "Pesquise por [termo1] perto de [termo2]" - Utiliza correspondência por proximidade
  • "Obtenha a página 15 de [documento]" - Recupera páginas específicas
  • "Encontre os 10 melhores resultados para [consulta]" - Ajusta a contagem de resultados

📁 Estrutura do Projeto

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

⚙️ Configuração

O servidor é configurado via 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 Gerenciamento

Gerenciamento do 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

Gerenciamento de PDF

# 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

Configuração 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

💡 Exemplos de Uso

Servidor de Documentos Jurídicos

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

Servidor de Documentação Técnica

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

Servidor de Artigos de Pesquisa

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

🔧 Ferramentas MCP Disponíveis

Cada servidor fornece três ferramentas configuráveis:

  1. Ferramenta de Busca (padrão: search_docs)

    • Busca inteligente em todos os documentos
    • Pontuação TF-IDF com correspondência por proximidade
    • Retorna trechos relevantes com contexto

  2. Ferramenta de Listagem (padrão: list_docs)

    • Lista todos os documentos disponíveis
    • Mostra metadados do documento e contagem de páginas

  3. Ferramenta de Conteúdo (padrão: get_document_content)

    • Recupera o conteúdo completo do documento
    • Pode buscar páginas específicas
    • Inclui formatação markdown completa

🎯 Personalização de Domínio

O servidor se adapta ao seu domínio através de:

  • Palavras-chave de Domínio: Configure termos importantes para sua área
  • Nomes de Ferramentas: Personalize nomes de ferramentas (ex.: search_legal_docs)
  • Descrições: Adapte descrições para seu caso de uso
  • Tamanho do Contexto: Ajuste quanto contexto retornar nos resultados de busca

🔍 Como Funciona o Mecanismo de Busca

Arquitetura de Índice Invertido

O servidor usa um índice invertido avançado para buscas extremamente rápidas:

  1. Processamento de Documentos: PDFs são convertidos para markdown e tokenizados
  2. Construção do Índice: Palavras são mapeadas para suas localizações (documento, página, posição)
  3. Pontuação TF-IDF:
    • TF (Frequência do Termo): Com que frequência uma palavra aparece em um documento
    • IDF (Frequência Inversa do Documento): Quão rara é uma palavra em todos os documentos
    • Pontuação combinada garante que resultados relevantes e únicos sejam classificados mais alto

Recursos de Busca

  • Impulso por Proximidade: Consultas com múltiplas palavras pontuam mais alto quando os termos aparecem próximos
  • Extração de Contexto: Retorna trechos relevantes com termos de busca destacados
  • Reconhecimento de Palavras-chave de Domínio: Palavras-chave configuradas recebem tratamento especial
  • Precisão em Nível de Página: Resultados incluem números de página específicos
  • Cache Inteligente: Índice de busca persiste entre reinicializações do servidor

📊 Otimizações de Desempenho

  • Processamento Incremental: Detecção de alterações baseada em hash MD5 - apenas PDFs novos/modificados são processados
  • Índice de Busca Persistente: Índice serializado carrega instantaneamente na reinicialização do servidor
  • Inicialização em Segundo Plano: Servidor aceita conexões enquanto constrói o índice
  • Eficiência de Memória: Processamento de PDF em streaming e armazenamento em markdown
  • Limites Configuráveis: Controle limites de tamanho de arquivo e parâmetros de processamento

🐛 Solução de Problemas

Problemas Comuns e Soluções

Servidor não aparece no Claude Desktop:

  • Certifique-se de que a configuração MCP foi mesclada: python generate_mcp_config.py --merge
  • Verifique o caminho do Python: which python ou where python (Windows)
  • Verifique se server_config.json existe e é JSON válido
  • Reinicie o Claude Desktop após alterações de configuração

PDFs não processando:

  • Verifique permissões da pasta: ls -la /path/to/pdf/folder
  • Verifique se os arquivos PDF não estão corrompidos: file document.pdf
  • Procure erros em stderr: python server.py 2>error.log
  • Garanta espaço em disco suficiente para o cache markdown

Busca retorna resultados ruins ou nenhum:

  • A indexação inicial pode levar tempo - verifique stderr para progresso
  • Verifique se os arquivos markdown existem: ls markdown/*.md
  • Verifique se o índice de busca existe: ls markdown/.search_index.pkl
  • Tente consultas de uma palavra primeiro, depois expanda
  • Revise palavras-chave de domínio na configuração

Servidor trava ou congela:

  • Verifique a versão do Python (3.8+ necessário): python --version
  • Verifique se todas as dependências estão instaladas: pip install -r requirements.txt
  • Limpe o cache e reprocesse: rm -rf markdown/.pdf_cache.json markdown/.search_index.pkl
  • Verifique problemas de bloqueio de arquivos no Windows

Modo de Depuração

# 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 Validação

# 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 Avançado

Múltiplos Servidores

Você pode executar múltiplos 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

Processamento em Lote

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

Palavras-chave Personalizadas

Configure palavras-chave específicas de domínio para melhor relevância de busca:

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

🏗️ Visão Geral da Arquitetura

Componentes Principais

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

    • Implementa índice invertido com pontuação TF-IDF
    • Gerencia tokenização de palavras e indexação de documentos
    • Fornece classificação baseada em proximidade para consultas com múltiplas palavras

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

    • Implementação principal do servidor com manipulação de protocolo MCP
    • Gerencia pipeline de processamento de PDF
    • Lida com operações assíncronas e inicialização em segundo plano

  3. Sistema de Configuração (config.py)

    • Configuração type-safe baseada em dataclass
    • Validação de esquema JSON
    • Suporte a variáveis de ambiente

  4. CLI de Gerenciamento (manage_server.py)

    • Criação interativa de configuração
    • Operações de gerenciamento de PDF
    • Teste e validação do servidor

Fluxo de Dados

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

🔄 Configuração Atual do Servidor

O repositório atualmente inclui uma configuração para documentação QuantConnect (server_config.json). Para criar seu próprio 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

📚 Exemplos de Casos de Uso

  • Escritórios Jurídicos: Pesquise contratos, arquivos de casos e documentos legais
  • Laboratórios de Pesquisa: Consulte artigos científicos e relatórios técnicos
  • Equipes de Software: Acesse documentação de API e especificações técnicas
  • Consultórios Médicos: Pesquise registros de pacientes e literatura médica
  • Instituições Educacionais: Navegue por materiais de curso e livros didáticos

🤝 Contribuindo

Aceitamos contribuições! Aqui estão algumas maneiras de ajudar:

Ideias de Melhorias

  1. Suporte a Formatos de Documento: Adicione suporte para Word, HTML ou outros formatos
  2. Melhorias na Busca: Implemente busca semântica, correspondência difusa ou classificação baseada em ML
  3. Desempenho: Adicione backend de banco de dados, processamento paralelo ou indexação distribuída
  4. Ferramentas: Crie ferramentas MCP especializadas para domínios específicos
  5. UI: Construa uma interface web para gerenciamento de configuração

Diretrizes de Desenvolvimento

  • Siga o estilo e padrões de código existentes
  • Adicione testes para novas funcionalidades
  • Atualize a documentação para novos recursos
  • Envie PRs com descrições claras

🔐 Considerações de Segurança

  • O servidor tem apenas acesso de leitura às pastas de PDF especificadas
  • Nenhuma chamada de rede externa é feita durante a operação
  • Dados sensíveis permanecem locais - nada é enviado a serviços externos
  • Configure permissões de arquivo apropriadas para suas pastas de PDF

📄 Licença

Este projeto é open source. Consulte o arquivo LICENSE para detalhes.

🙏 Agradecimentos

Construído com o Model Context Protocol pela Anthropic.

Pronto para transformar seus PDFs em uma base de conhecimento pesquisável?

Execute python manage_server.py create-config para começar! 🚀

📦 Dependências

  • mcp: SDK Model Context Protocol para construir servidores MCP
  • PyPDF2: Análise de PDF e extração de texto
  • asyncio: I/O assíncrono para operações concorrentes
  • jsonschema: Validação JSON para arquivos de configuração

Todas as dependências são leves e têm requisitos mínimos de sistema.