PDF Toolkit MCP

PDF Toolkit MCP

💼 Disponível para trabalhos freelance de integração MCP/IA — DM @aryansalian03 ou via aryanbv.com

Um kit de ferramentas PDF com capacidade de escrita para qualquer cliente MCP. Ele fornece 22 ferramentas para ler, criar, renderizar, transformar e proteger PDFs. Isso inclui renderizar páginas em imagens para que modelos de visão possam ler documentos digitalizados, construir PDFs a partir de Markdown ou dados estruturados, criptografia AES-256 e operações de mesclagem e divisão que mantêm os campos de formulário intactos. Não há dependências nativas, então ele roda localmente a partir de um único comando npx.

npx -y @aryanbv/pdf-toolkit-mcp

Ele não precisa de arquivos de configuração, chaves de API, Docker ou compilador, e funciona offline.

Visão geral

A maioria dos servidores PDF para MCP apenas lê. Este também escreve: ele cria documentos a partir de Markdown ou dados estruturados, preenche e achata formulários, reorganiza a estrutura de páginas e aplica criptografia AES-256, tudo sem uma cadeia de ferramentas nativa de compilação.

Algumas coisas que vale a pena saber:

• Ele lê digitalizações. pdf_render_pages rasteriza páginas em imagens, para que um modelo com capacidade de visão possa ler PDFs digitalizados ou somente imagem que não possuem camada de texto.
• Mesclar, dividir, reordenar e excluir preservam os campos AcroForm em vez de descartá-los. Nomes que colidem entre entradas são namespaced por fonte, e cada chamada relata o que preservou, renomeou ou descartou.
• A criptografia é AES-256 via qpdf, não o esquema legado RC4.
• Cada mecanismo é WASM ou JavaScript puro, então npx funciona no Node 20 e posteriores em Windows, macOS e Linux sem node-gyp, binding de canvas ou binário pré-compilado.
• Erros carregam códigos estáveis, stack traces permanecem internos, posicionamentos fora da página são rejeitados em vez de cortados silenciosamente, e respostas grandes são truncadas sem quebrar o JSON.

Configuração do cliente

{
  "mcpServers": {
    "pdf-toolkit": {
      "command": "npx",
      "args": ["-y", "@aryanbv/pdf-toolkit-mcp"]
    }
  }
}

claude mcp add pdf-toolkit -- npx -y @aryanbv/pdf-toolkit-mcp

{
  "mcpServers": {
    "pdf-toolkit": {
      "command": "npx",
      "args": ["-y", "@aryanbv/pdf-toolkit-mcp"]
    }
  }
}

{
  "servers": {
    "pdf-toolkit": {
      "command": "npx",
      "args": ["-y", "@aryanbv/pdf-toolkit-mcp"]
    }
  }
}

{
  "mcpServers": {
    "pdf-toolkit": {
      "command": "npx",
      "args": ["-y", "@aryanbv/pdf-toolkit-mcp"]
    }
  }
}

Uma vez conectado, peça o que quiser em linguagem simples e o cliente seleciona a ferramenta e preenche os argumentos. Os blocos JSON abaixo mostram os argumentos que cada ferramenta aceita, para referência.

Ferramentas

Criar PDFs a partir de Markdown

Transforme Markdown em um PDF de várias páginas em uma única chamada. Ele suporta CommonMark e GFM: títulos, negrito e itálico, tabelas, listas ordenadas e com marcadores, código cercado e citações em bloco, renderizados com @react-pdf/renderer.

"Crie um PDF a partir deste relatório em Markdown."

Argumentos de pdf_create_from_markdown:

{
  "markdown": "# Quarterly Report\n\nRevenue grew **23% YoY**.\n\n| Region | Q1 2025 | Q1 2026 |\n|--------|---------|--------|\n| Americas | $1.2M | $1.5M |\n| EMEA | $800K | $960K |\n\n## Key Wins\n\n1. 12 new enterprise contracts\n2. Churn down to 3.1%",
  "outputPath": "/path/to/report.pdf",
  "pageSize": "Letter"
}

Tabelas dimensionam suas colunas ao conteúdo e respeitam alinhamento, listas aninhadas recuam e linhas de código longas quebram. Adicione números de página depois com pdf_add_page_numbers.

Modelos

Gere documentos a partir de dados estruturados usando os modelos invoice, report e letter.

"Crie uma fatura para Riverbend Outfitters."

Argumentos de pdf_create_from_template:

{
  "templateName": "invoice",
  "data": {
    "companyName": "Northpoint Design",
    "clientName": "Riverbend Outfitters",
    "invoiceNumber": "2026-0042",
    "invoiceDate": "2026-04-01",
    "items": [
      { "description": "Website redesign", "quantity": 40, "unitPrice": 150 },
      { "description": "Annual hosting", "quantity": 1, "unitPrice": 299 }
    ],
    "taxRate": 18,
    "currency": "USD",
    "paymentTerms": "Net 30"
  },
  "outputPath": "/path/to/invoice.pdf"
}

O parâmetro opcional currency do modelo invoice aceita um código ISO ou um símbolo. Símbolos seguros para WinAnsi ($ € £ ¥) são renderizados como glifos; um código que a Helvetica não consegue desenhar, como INR, KRW ou TRY, cai para o rótulo do código ISO (INR 20.00), então qualquer moeda funciona sem erro. O recurso pdf-toolkit://templates lista cada modelo e os campos que ele aceita.

Ler PDFs digitalizados e somente imagem (visão)

Muitos PDFs são digitalizações sem camada de texto. pdf_render_pages rasteriza páginas para que um cliente com capacidade de visão possa lê-los.

"Leia este contrato digitalizado."

O modo inline retorna páginas como imagens que o modelo lê diretamente (até 5 páginas; o DPI é limitado automaticamente para proteger a janela de contexto):

{ "filePath": "/path/to/scanned.pdf", "inline": true }

Ou escreva arquivos de imagem no disco (padrão 150 DPI, primeiras 50 páginas, PNG):

{
  "filePath": "/path/to/scanned.pdf",
  "pages": "1-3",
  "dpi": 200,
  "format": "jpeg",
  "outputDir": "/path/to/output"
}

Converter um PDF para Markdown

"Converta report.pdf para Markdown para que eu possa resumi-lo."

pdf_to_markdown reconstrói a ordem de leitura a partir das posições do texto. Ele agrupa até duas colunas de conteúdo (mais faixas de título e rodapé de largura total), infere títulos a partir do tamanho da fonte e detecta listas. Funciona melhor em PDFs digitais limpos; use pdf_render_pages para digitalizações. Retorna as primeiras 10 páginas por padrão.

{ "filePath": "/path/to/report.pdf", "pages": "1-5" }

Pesquisar e comparar

"Encontre cada menção a 'indenização' em contract.pdf."

Argumentos de pdf_search:

{
  "filePath": "/path/to/contract.pdf",
  "query": "indemnification",
  "caseSensitive": false
}

Cada correspondência retorna com seu número de página e um trecho ao redor. A correspondência é uma substring literal, sem diferenciar maiúsculas/minúsculas por padrão; defina caseSensitive: true para diferenciar maiúsculas/minúsculas. A pesquisa por regex é intencionalmente deixada de fora, porque um padrão fornecido por um atacante pode acionar backtracking catastrófico (ReDoS) que o JavaScript de thread única não consegue interromper de forma confiável. Regex seguro está planejado para uma versão futura.

"O que mudou entre v1.pdf e v2.pdf?"

Argumentos de pdf_compare:

{ "filePathA": "/path/to/v1.pdf", "filePathB": "/path/to/v2.pdf" }

Ele relata um diff de texto página por página (added e removed) e define identical: true quando o texto corresponde. O diff é somente texto, então mudanças puramente visuais não são detectadas.

Mesclagem, divisão, exclusão e achatamento com preservação de formulários

Mesclar, dividir, reordenar e excluir páginas preservam campos AcroForm. Nomes que colidem entre entradas são namespaced por fonte, e cada ferramenta retorna { preserved, renamed, dropped }, onde renamed é uma lista de pares { from, to } (enderece um campo renomeado pelo nome to depois). Essas ferramentas e pdf_flatten também retornam um booleano flattened.

"Mescle estes três formulários e achate o resultado."

Argumentos de pdf_merge:

{
  "filePaths": ["/path/a.pdf", "/path/b.pdf", "/path/c.pdf"],
  "outputPath": "/path/merged.pdf",
  "flatten": true
}

"Remova as páginas 2 e 5 de report.pdf."

Argumentos de pdf_delete_pages:

{
  "filePath": "/path/report.pdf",
  "pages": "2,5",
  "outputPath": "/path/trimmed.pdf"
}

Use pdf_flatten sozinho para assar os valores de um formulário existente em conteúdo estático. O caminho de saída deve ser diferente do de entrada.

Criptografia

"Criptografe report.pdf com a senha 'secure123'."

A criptografia é AES-256. Defina senhas separadas de usuário (abertura) e proprietário (edição) para acesso granular; a senha do proprietário assume o padrão da senha do usuário quando omitida.

Argumentos de pdf_encrypt:

{
  "filePath": "/path/report.pdf",
  "outputPath": "/path/report-encrypted.pdf",
  "userPassword": "secure123",
  "ownerPassword": "admin456"
}

QR codes e códigos de barras

"Adicione um QR code apontando para nosso site na página 1."

pdf_embed_qr_code suporta QR Code, Code128, DataMatrix, EAN-13, PDF417 e Aztec. Posição e tamanho são configuráveis, a proporção da simbologia é preservada, o posicionamento é ciente de rotação e posicionamentos fora da página são rejeitados em vez de cortados.

Prompts guiados

O servidor inclui cinco prompts MCP que roteirizam fluxos de trabalho em várias etapas para o cliente:

Recursos

pdf-toolkit://templates é um recurso JSON que lista os modelos disponíveis para pdf_create_from_template e os campos que cada um aceita.

Experimente em linguagem simples

• "Crie um PDF a partir deste relatório em Markdown"
• "Gere uma fatura para Riverbend Outfitters, 10 horas de consultoria a US$ 150/hora"
• "Mescle janeiro.pdf e fevereiro.pdf em q1-combinado.pdf"
• "Converta este PDF para Markdown para que eu possa resumi-lo"
• "Renderize este PDF escaneado para que você possa lê-lo"
• "Pesquise por 'rescisão' em contrato.pdf"
• "Compare rascunho-v1.pdf e rascunho-v2.pdf"
• "Preencha o campo Nome com 'João da Silva' em aplicacao.pdf"
• "Adicione uma marca d'água CONFIDENCIAL em rascunho.pdf"
• "Criptografe financeiro.pdf com a senha AES-256 'orcamento2026'"
• "Incorpore um código QR com nossa URL na página de capa"
• "Reordene as páginas como 3,1,2 em relatorio.pdf"

Semântica de erros e saída

• Erros codificados. Falhas de validação e carregamento lançam um PdfError com um código estável, exibido como Error [CODE]: message (por exemplo, FILE_NOT_FOUND, NOT_A_PDF, PAGE_OUT_OF_RANGE, ENCRYPTED_PDF, RESOURCE_LIMIT). Os clientes podem ramificar com base no código em vez de analisar o texto da mensagem, e rastreamentos de pilha nunca são vazados.
• Saída de ferramentas de escrita. Ferramentas de escrita criam um arquivo em outputPath e retornam esse caminho mais seu tamanho como texto, já que o MCP não tem tipo de conteúdo de arquivo. outputPath pode nomear um arquivo existente e o sobrescreverá, então escolha um caminho que não colida com algo que você queira manter.
• Truncamento seguro para JSON. As respostas são limitadas a 25.000 caracteres. Payloads de objetos retornam um envelope { truncated, note, preview } válido em vez de uma string cortada no meio de um token, para que o JSON.parse de um cliente nunca quebre.

Limitações conhecidas

• Mesclar, dividir, reordenar, excluir. Os campos de formulário são preservados, e nomes conflitantes são namespaced e relatados em renamed como pares { from, to }. Formulários incomuns que não podem ser reconstruídos com segurança são relatados sob dropped em vez de falhar a operação.
• Extração de texto. Retorna a ordem do fluxo do PDF, não a ordem visual de leitura. Use pdf_to_markdown quando a ordem de leitura for importante; pdf_extract_text bruto pode intercalar layouts de múltiplas colunas.
• PDF para Markdown. Reconstrói até duas colunas de conteúdo (mais título de largura total e faixas de rodapé); páginas com três ou mais colunas caem para ordem de leitura de coluna única. Funciona melhor em PDFs digitais limpos. Conteúdo tabular é emitido como texto posicionado em ordem de leitura, não reconstruído como tabelas Markdown.
• Markdown para PDF. Suporta CommonMark e GFM (cabeçalhos, negrito e itálico, links, listas, tabelas, código cercado, citações em bloco e regras horizontais). HTML bruto, estado de caixas de seleção em listas de tarefas, notas de rodapé e realce de sintaxe de código não são suportados.
• Comparar. Diff somente de texto; alterações visuais ou de layout que não alteram o texto não são detectadas.
• Incorporação de imagens. Apenas JPEG e PNG. Posicionamentos fora da página são rejeitados com um erro codificado em vez de serem cortados silenciosamente.
• Fontes. As fontes integradas são somente latinas (WinAnsi). Para scripts não latinos, como árabe, CJK ou devanágari, passe um arquivo .ttf ou .otf por meio de fontPath para pdf_fill_form ou pdf_create. Markdown e PDFs de modelo usam Helvetica por padrão.

Pilha de tecnologia

Um design de múltiplos mecanismos. Cada mecanismo é puramente WASM ou JavaScript:

Requisitos

• Node.js 20 ou posterior. Node 18 e a linha 20.x estão em fim de vida, então Node 22 ou 24 LTS é recomendado.

Desenvolvimento

npm install        # install dependencies
npm run build      # compile TypeScript
npm test           # run the vitest suite (160 tests)
npm run test:cov   # tests with coverage
npm run lint       # ESLint
npm run format     # Prettier
npm run inspect    # MCP Inspector (requires Node >= 22.7.5)

Veja CLAUDE.md para notas de arquitetura e contribuição.

Licença

MIT