Servidor MCP del lector de PDF (@sylphlab/pdf-reader-mcp)

Permita a sus agentes de IA (como Cline) leer y extraer de forma segura información (texto, metadatos, recuento de páginas) de archivos PDF dentro del contexto de su proyecto utilizando una única herramienta flexible.

Instalación

Uso de npm (recomendado)

Instalar como una dependencia en su entorno de host o proyecto MCP:

pnpm add @sylphlab/pdf-reader-mcp # Or npm install / yarn add

Configure su host MCP (por ejemplo, mcp_settings.json ) para usar npx :

{
  "mcpServers": {
    "pdf-reader-mcp": {
      "command": "npx",
      "args": ["@sylphlab/pdf-reader-mcp"],
      "name": "PDF Reader (npx)"
    }
  }
}

(Asegúrese de que el host configure el cwd correcto para el proyecto de destino)

Usando Docker

Tire de la imagen:

docker pull sylphlab/pdf-reader-mcp:latest

Configure su host MCP para ejecutar el contenedor, montando el directorio de su proyecto en /app :

{
  "mcpServers": {
    "pdf-reader-mcp": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-v",
        "/path/to/your/project:/app", // Or use "$PWD:/app", "%CD%:/app", etc.
        "sylphlab/pdf-reader-mcp:latest"
      ],
      "name": "PDF Reader (Docker)"
    }
  }
}

Construcción local (para desarrollo)

Clon: git clone https://github.com/sylphlab/pdf-reader-mcp.git
Instalar: cd pdf-reader-mcp && pnpm install
Construir: pnpm run build
Configurar el host MCP:
{ "mcpServers": { "pdf-reader-mcp": { "command": "node", "args": ["/path/to/cloned/repo/pdf-reader-mcp/build/index.js"], "name": "PDF Reader (Local Build)" } } }
(Asegúrese de que el host configure el cwd correcto para el proyecto de destino)

Inicio rápido

Suponiendo que el servidor esté ejecutándose y configurado en su host MCP:

Solicitud MCP (Obtener metadatos y texto de la página 2 de un PDF local):

{
  "tool_name": "read_pdf",
  "arguments": {
    "sources": [
      {
        "path": "./documents/my_report.pdf",
        "pages": [2]
      }
    ],
    "include_metadata": true,
    "include_page_count": false, // Default is true, explicitly false here
    "include_full_text": false // Ignored because 'pages' is specified
  }
}

Fragmento de respuesta esperada:

{
  "results": [
    {
      "source": "./documents/my_report.pdf",
      "success": true,
      "data": {
        "page_texts": [
          { "page": 2, "text": "Text content from page 2..." }
        ],
        "info": { ... },
        "metadata": { ... }
        // num_pages not included as requested
      }
    }
  ]
}

¿Por qué elegir este proyecto?

🛡️ Seguro: limita el acceso a los archivos estrictamente al directorio raíz del proyecto.
🌐 Flexible: maneja tanto rutas relativas locales como URL públicas.
🧩 Consolidado: una única herramienta read_pdf atiende múltiples necesidades de extracción (texto completo, páginas específicas, metadatos, recuento de páginas).
⚙️ Salida estructurada: devuelve datos en un formato JSON predecible, fácil de analizar para los agentes.
🚀 Fácil integración: diseñado para un uso perfecto dentro de entornos MCP a través de npx o Docker.
✅ Robusto: utiliza pdfjs-dist para un análisis confiable y Zod para la validación de entrada.

Ventajas de rendimiento

Los puntos de referencia iniciales realizados con Vitest en un PDF de muestra muestran un manejo eficiente de varias operaciones:

Guión	Operaciones por segundo (hz)	Velocidad relativa
Manejar archivos inexistentes	~12,933	Lo más rápido
Obtener el texto completo	~5,575
Obtener página específica (Página 1)	~5,329
Obtener páginas específicas (páginas 1 y 2)	~5,242
Obtener metadatos y recuento de páginas	~4.912	El más lento

(Una mayor temperatura indica un mejor rendimiento. Los resultados pueden variar según la complejidad del PDF y el entorno).

Consulte la documentación de rendimiento para obtener más detalles y planes futuros.

Características

Lea el contenido de texto completo de los archivos PDF.
Leer contenido de texto de páginas específicas o rangos de páginas.
Leer metadatos del PDF (autor, título, fecha de creación, etc.).
Obtener el recuento total de páginas de un PDF.
Procesar múltiples fuentes PDF (rutas locales o URL) en una sola solicitud.
Opera de forma segura dentro de la raíz del proyecto definida.
Proporciona salida JSON estructurada a través de MCP.
Disponible a través de npm y Docker Hub.

Filosofía del diseño

El servidor prioriza la seguridad mediante el confinamiento de contexto, la eficiencia mediante la transferencia de datos estructurados y la simplicidad para una fácil integración en los flujos de trabajo de los agentes de IA. Busca minimizar las dependencias, apoyándose en la robusta biblioteca pdfjs-dist .

Consulte la documentación completa de Filosofía de diseño .

Comparación con otras soluciones

En comparación con el acceso directo a archivos (a menudo inviable) o las herramientas genéricas de sistemas de archivos, este servidor ofrece capacidades de análisis específicas para PDF. A diferencia de las herramientas CLI externas (p. ej., pdftotext ), proporciona una interfaz MCP segura e integrada con salida estructurada, lo que mejora la fiabilidad y la facilidad de uso para los agentes de IA.

Consulte la documentación de comparación completa.

Planes futuros (hoja de ruta)

Documentación:
- Finalizar todas las secciones de la documentación (Guía, API, Diseño, Comparación).
- Resolver el problema de TypeDoc y generar documentación de API.
- Agregue más ejemplos y patrones de uso avanzados.
- Implementar compatibilidad con PWA y optimización móvil para el sitio de documentos.
- Agregue botones para compartir y métricas de crecimiento al sitio de documentos.
Evaluación comparativa:
- Realizar evaluaciones comparativas exhaustivas con diversos archivos PDF (tamaño, complejidad).
- Medir el uso de la memoria.
- Compare el rendimiento de la URL con el del archivo local.
Funcionalidad principal:
- Explore posibles optimizaciones para archivos PDF muy grandes.
- Investigar opciones para extraer imágenes o anotaciones (a largo plazo).
Pruebas:
- Aumentar la cobertura de pruebas al 100% cuando sea posible.
- Agregue pruebas de tiempo de ejecución una vez que sea posible.

Documentación

Para obtener información detallada sobre el uso, la referencia de API y guías, visite el sitio web de documentación completa (el enlace se actualizará tras la implementación).

Comunidad y soporte

¿Encontraste un error o tienes alguna solicitud de función? Abre un problema en GitHub Issues .
¿Quieres contribuir? ¡ Agradecemos tus contribuciones! Consulta CONTRIBUTING.md .
Destacar y mirar: si este proyecto te resulta útil, considera marcar con una estrella ⭐ y mirar 👀 el repositorio en GitHub para mostrar tu apoyo y mantenerte actualizado.

Licencia

Este proyecto está licenciado bajo la licencia MIT .

PDF Reader MCP Server

Integrations