PDF Agent MCP

Um servidor para agentes de IA processarem seletivamente e extraírem conteúdo de documentos PDF.

GitHub
14

Documentação

PDF Agent MCP

🌐 Visite a Landing Page para uma visão geral e download fácil

⚠️ Instruções Importantes de Configuração

Antes de usar esta extensão, você DEVE configurar o Claude Desktop corretamente:

Configuração Necessária

  1. Instale o Node.js LTS: Visite nodejs.org e baixe a versão LTS
  2. Configure o Claude Desktop:
    • Vá para Claude > Configurações > Extensões > Configurações Avançadas
    • Desative "Usar Node.js Integrado para MCP"
    • Reinicie o Claude Desktop

Esta extensão NÃO funcionará com o Node.js integrado do Claude. Você deve usar a instalação do Node.js do seu sistema.

Solução de Problemas

Se você tiver problemas ao carregar a extensão:

  1. Verifique se o Node.js está instalado: Execute node --version no seu terminal
  2. Certifique-se de que "Usar Node.js Integrado para MCP" esteja desativado nas configurações do Claude Desktop
  3. Reinicie o Claude Desktop completamente
  4. Verifique os logs em ~/Library/Logs/Claude/mcp-server-PDF Agent MCP.log (macOS) ou %LOCALAPPDATA%\Claude\Logs\mcp-server-PDF Agent MCP.log (Windows)

Um servidor Model Context Protocol projetado para leitura agêntica e processamento seletivo de PDFs. Permite que sistemas de IA naveguem e extraiam conteúdo de PDFs de forma eficiente sem sobrecarregar as janelas de contexto.

Recursos

  • Extração de Metadados: Obtenha propriedades do PDF, contagem de páginas e informações do arquivo
  • Extração de Texto: Extração de texto nativa com processamento híbrido para melhores resultados
  • Conversão de Imagens: Converta páginas de PDF em imagens otimizadas para análise visual
  • Busca de Conteúdo: Busca por padrões/regex com trechos de contexto
  • Índice: Extraia marcadores e estrutura do documento
  • Suporte Flexível a Caminhos: Use caminhos absolutos ou relativos a partir de ~/pdf-agent/

Guia de Uso

O PDF Agent MCP resolve o problema comum de estouro da janela de contexto ao trabalhar com PDFs em ferramentas de IA.

Importante: Não arraste PDFs para o chat - isso carregará todo o conteúdo do PDF de forma tradicional e ignorará o processamento inteligente. Em vez disso, forneça caminhos de arquivo ou URLs para ativar as ferramentas do PDF Agent para processamento seletivo.

Como Usar

Para PDFs Locais:

  • Forneça o caminho absoluto do arquivo para o seu PDF
  • Dica rápida: Clique com o botão direito no seu PDF → "Abrir com Chrome" → copie o URL da barra de endereço para obter o caminho absoluto

Para PDFs Online:

  • Basta fornecer a URL do PDF - o agente fará o download e processará localmente

Principais Benefícios

  • Leitura Seletiva: A IA primeiro examina metadados e índice, depois abre apenas as páginas relevantes
  • Eficiência de Tokens: Evita imagens quando possível, usando-as apenas quando necessário para análise visual
  • Escalável: Funciona com documentos grandes (livros com 1000+ páginas) e múltiplos PDFs simultaneamente
  • Capacidade de Busca: Busca integrada por padrões/regex no conteúdo do PDF

Abordagem

Este MCP usa busca agêntica com ferramentas simples em vez de alternativas complexas:

  • Sem criação de embeddings, chunking ou armazenamento vetorial
  • Sem coordenação multi-agente ou complexidade de handoff
  • Apenas ferramentas limpas e eficazes que sistemas de IA modernos podem usar de forma inteligente

Perfeito para pesquisadores, estudantes e profissionais que trabalham com extensas bibliotecas de PDFs.

Prompt de Assistente de IA para Uso Ideal

Copie este prompt nas instruções personalizadas ou no contexto do seu assistente de IA para obter melhores resultados:

When working with PDFs using the PDF Agent MCP tools, follow this strategic approach:

### 1. Query Analysis & PDF Identification
- **Think carefully** about the user's search query and information needs
- **Identify which PDF(s)** are most likely to contain the answer
- Consider the document type, domain, and likely structure based on the query

### 2. Exploratory Phase (Always Start Here)
- **Get metadata** first using `get_pdf_metadata` to understand document size, creation date, and properties
- **Extract table of contents** with `get_pdf_outline` to understand document structure and navigation
- **Analyze the outline** to identify which sections are most relevant to the query

### 3. Strategic Content Extraction
Based on the outline and metadata:
- **Use page ranges** (`"5:10"`, `"20:"`) to focus on specific sections rather than entire documents
- **Extract images** with `get_pdf_images` when visual content is critical (charts, diagrams, tables, equations)
- **Choose text extraction strategy**: `hybrid` (default) for most cases, `native` for clean PDFs, `ocr` for scanned documents

### 4. Advanced Search Strategies
- **Use multiple search queries** with different keywords and synonyms
- **Apply regex patterns** for flexible matching: `/budget|cost|expense/gi` instead of single terms
- **Combine searches**: Start broad, then narrow down with specific terms
- **Use context characters** (150+ chars) to understand search result context
- **Implement early stopping** with `max_results` for large documents

### 5. Iterative Refinement
- **Start with targeted searches** based on outline analysis
- **Follow up with broader searches** if initial queries don't yield results
- **Extract specific page ranges** identified through search results
- **Use visual analysis** (images) when text extraction seems incomplete or when layout matters

### 6. Performance Optimization
- **Avoid processing entire large PDFs** - always use page ranges when possible
- **Use search with early stopping** before extracting large sections
- **Prefer search over full text extraction** for finding specific information
- **Extract images selectively** only when visual analysis is needed

### 7. Multi-Document Workflows
- **Process documents in parallel** when comparing multiple PDFs
- **Use consistent search terms** across documents for comparison
- **Combine results strategically** rather than processing everything at once

### Key Principles:
- **Strategic before comprehensive**: Understand document structure before diving deep
- **Search before extract**: Use pattern matching to locate relevant content first  
- **Visual when necessary**: Extract images only when text extraction is insufficient
- **Iterative refinement**: Start targeted, expand scope as needed
- **Context preservation**: Always maintain enough context around search results

This approach maximizes efficiency, minimizes token usage, and provides more accurate, focused results than traditional "dump entire PDF" methods.

Instalação

Opção 1: Pacote DXT (Recomendado)

  1. Primeiro, certifique-se de ter concluído a Configuração Necessária acima
  2. Baixe o arquivo pdf-agent-mcp.dxt mais recente dos releases
  3. Clique duas vezes no arquivo .dxt para instalá-lo no Claude Desktop

Opção 2: Instalação Manual

  1. Primeiro, certifique-se de ter concluído a Configuração Necessária acima
  2. Clone este repositório
  3. Compile o projeto: npm install && npm run build
  4. Encontre seu arquivo de configuração do Claude Desktop:
  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json

Adicione o seguinte:

{
  "mcpServers": {
    "pdf-agent": {
      "command": "node",
      "args": [
        "PATH_TO_REPO/server/index.js"
      ]
    }
  }
}

Substitua PATH_TO_REPO pelo caminho real do seu repositório clonado.

Desenvolvimento

# Install dependencies
npm install

# Build the project
npm run build

# Create DXT package
npm run build:dxt

# Pack the final .dxt file for distribution
dxt pack

Visualizando Logs

Para depurar problemas, você pode visualizar os logs do servidor MCP:

# View logs (macOS)
open "$HOME/Library/Logs/Claude/mcp-server-PDF Agent MCP.log"

# Stream logs in real-time (macOS)
tail -f "$HOME/Library/Logs/Claude/mcp-server-PDF Agent MCP.log"

# Clear/delete logs (macOS)
rm "$HOME/Library/Logs/Claude/mcp-server-PDF Agent MCP.log"

# View logs (Windows)
notepad "%LOCALAPPDATA%\Claude\Logs\mcp-server-PDF Agent MCP.log"

# Clear/delete logs (Windows)
del "%LOCALAPPDATA%\Claude\Logs\mcp-server-PDF Agent MCP.log"

Licença

MIT