PDFCompress

PDFCompress es un compresor de PDF de código abierto que preserva la estructura, pensado para humanos y agentes de IA. Utiliza ajustes preestablecidos de imagen estilo WPS verificados de forma independiente, pero no llama ni distribuye DLL de WPS y no depende de una cuenta de WPS.

Su regla principal es simple:

Mantener el texto y los vectores como texto y vectores; reducir la resolución solo de las imágenes pintadas sobredimensionadas; verificar el resultado antes de publicarlo.

Características

• Calcula la resolución de la imagen a partir de la matriz de transformación real del PDF, incluidas las imágenes anidadas en Form XObjects.

• Aplica los ajustes high, standard, medium y low compatibles con WPS.

• Añade un perfil archive-safe para adjuntos de premios, licitaciones y archivos.

• Conserva el archivo fuente y escribe atómicamente en una ruta de salida diferente.

• Preserva marcadores, adjuntos, anotaciones, fuentes y la estructura visible del PDF por defecto.

• Rechaza PDF firmados a menos que se acepte explícitamente la invalidación de la firma.

• Verifica el número de páginas, los cuadros de página y el texto extraíble después de cada candidato.

• Admite un tamaño objetivo sin recompimir repetidamente el resultado JPEG anterior.

• Proporciona una API de Python, CLI, Skill de agente compartida, plugin de Codex, plugin de Claude Code y servidor MCP.

Related MCP server: MokuPDF

Instalación

Se requiere Python 3.11 o superior.

git clone https://github.com/ncepuee/PDFCompress.git
cd PDFCompress
python -m pip install -e ".[mcp]"

Con uv:

uv tool install --editable ".[mcp]"

Instalar la versión etiquetada de GitHub sin clonar:

uv tool install "pdfcompress-agent[mcp] @ git+https://github.com/ncepuee/PDFCompress.git@v0.1.0"

Inicio rápido

Analizar antes de comprimir:

pdfcompress analyze "input.pdf" --json

Comprimir usando el perfil de alta calidad compatible con WPS:

pdfcompress compress "input.pdf" "output.pdf" --preset high --json

Para un adjunto formal que debe ser inferior a 4 MB:

pdfcompress compress "input.pdf" "output.pdf" `
  --preset archive-safe `
  --target-size-mb 4 `
  --json

Verificar un par existente:

pdfcompress verify "input.pdf" "output.pdf" --json

Preajustes

Los cuatro valores compatibles con WPS se recuperaron de las ramas generateCompressArgs del plugin de compresión instalado y se documentaron de forma independiente en la nota de análisis adjunta. El kernel de remuestreo exacto de WPS, la política de submuestreo de croma y la máscara de bits completa del optimizador no se copian ni se reivindican.

Comportamiento del tamaño objetivo

Cuando se proporciona --target-size-mb, PDFCompress prueba perfiles progresivamente más fuertes comenzando por el preajuste solicitado. Cada intento reabre el PDF original:

archive-safe → high → standard → medium → low

Se selecciona el primer candidato verificado por debajo del límite. Si ningún perfil alcanza el límite, se devuelve el candidato verificado más pequeño con una advertencia. PDFCompress no rasteriza páginas silenciosamente, no elimina fuentes ni quita adjuntos para forzar el objetivo.

Integración con agentes

Claude Code

Instale primero el paquete de Python y luego cargue el plugin para una sesión:

cd PDFCompress
claude --plugin-dir .

Invoque la skill como /pdfcompress:pdf-compress, o pida a Claude que comprima un PDF. Claude Code también carga el .mcp.json del plugin e inicia pdfcompress-mcp sobre stdio.

Codex

El repositorio contiene un .codex-plugin/plugin.json validado, un directorio compartido skills/ y .mcp.json. Se puede instalar desde un marketplace local de Codex, o la skill se puede copiar a un directorio de skills personal o de proyecto. El paquete principal debe estar instalado para que pdfcompress-mcp esté en PATH.

Clientes MCP genéricos

Use esta configuración stdio:

{
  "mcpServers": {
    "pdfcompress": {
      "type": "stdio",
      "command": "pdfcompress-mcp",
      "args": []
    }
  }
}

Herramientas MCP:

• analyze_pdf(path, password?)

• compress_pdf(input_path, output_path, preset?, target_size_mb?, overwrite?, allow_signature_loss?)

• verify_pdf(input_path, output_path)

Investigación de código abierto e ideas adoptadas

Consulte THIRD_PARTY_NOTICES.md para conocer los límites de licencia.

Seguridad y limitaciones

• Reescribir un PDF invalida las firmas digitales. El valor predeterminado es detenerse.

• Los PDF cifrados requieren una contraseña; el cifrado se conserva en la salida.

• La versión 0.1 omite máscaras de imagen, transparencia, matrices de decodificación personalizadas, espacios de color inusuales e imágenes que no sean de 8 bits, en lugar de arriesgarse a una corrupción visual.

• Las comprobaciones de igualdad de texto utilizan texto extraíble. Las páginas escaneadas sin OCR aún requieren revisión visual.

• Se recomienda la comparación de renderizado a nivel de píxel antes de usar la herramienta en documentos legalmente significativos o altamente complejos.

• Si un candidato no es más pequeño que el original, PDFCompress genera una copia byte a byte del original e informa que no se encontró una reducción de tamaño segura.

Ejemplo validado

En un PDF de 12 páginas con muchas imágenes utilizado durante el desarrollo:

En la comparación de renderizado a 100 DPI, todas las dimensiones de página coincidieron; el resultado archive-safe tuvo una diferencia RMS media por página de 0.388 y un máximo de 3.002 en una escala de canal de 0–255. Este es un caso de validación, no una garantía universal de calidad.

Desarrollo

python -m pip install -e ".[mcp,dev]"
pytest
ruff check .

Las pruebas generan su propio PDF con texto buscable y una imagen de alta resolución. No se incluyen documentos privados en el repositorio.

Licencia

PDFCompress se publica bajo la Licencia MIT. Las dependencias de terceros conservan sus propias licencias.

Consulte el registro de cambios y los lanzamientos de GitHub para ver los cambios versionados y los paquetes de Python descargables.