Enhanced QR Code MCP Server

Genera códigos QR con metadatos, procesamiento por lotes y herramientas de gestión de archivos.

Documentación

Servidor MCP de Códigos QR Mejorado

Un servidor avanzado de Protocolo de Contexto de Modelo (MCP) que genera códigos QR y los guarda automáticamente como archivos PNG con metadatos completos, capacidades de procesamiento por lotes y herramientas de gestión de archivos.

🔗 Estrategia de Implementación Dual
Esta implementación en Python se centra en la generación confiable de archivos y el procesamiento por lotes.
Para estilos avanzados, análisis y plantillas, consulte nuestra implementación en TypeScript.

Construido sobre y mejorado desde: @jwalsh/mcp-server-qrcode

Esta versión mejorada añade generación automática de archivos, seguimiento de metadatos, procesamiento por lotes y funciones listas para producción, manteniendo total compatibilidad con el protocolo MCP.

🚀 Mejoras Clave Sobre el Original

Característica	MCP Original	MCP Python Mejorado	MCP TypeScript Mejorado
Salida de Archivo PNG	❌ Solo visualización en chat	✅ Guardado automático de archivos PNG	✅ Múltiples formatos (PNG, SVG, PDF)
Gestión de Directorios	❌ Ninguna	✅ Directorios de salida personalizados	✅ Rutas configurables
Seguimiento de Metadatos	❌ Ninguno	✅ Archivos de metadatos JSON	✅ Metadatos completos
Procesamiento por Lotes	❌ Uno a la vez	✅ Múltiples códigos QR por llamada	✅ Funciones avanzadas de lotes
Organización de Archivos	❌ Ninguna	✅ Gestión estructurada de archivos	✅ Organización basada en plantillas
Nombres de Archivo Personalizados	❌ Ninguno	✅ Nombres definidos por el usuario	✅ Patrones de nombres inteligentes
Listo para Producción	❌ Básico	✅ Suite de pruebas completa y documentación	✅ Funciones empresariales
Estilos Avanzados	❌ Ninguno	🔄 Planificado (ver ROADMAP)	✅ Motor de estilos completo
Análisis de QR	❌ Ninguno	🔄 Planificado (ver ROADMAP)	✅ Decodificación y análisis de calidad
Plantillas	❌ Ninguna	🔄 Planificado (ver ROADMAP)	✅ Plantillas predefinidas

🛠️ Instalación

Requisitos Previos

Python 3.8+
Cliente MCP (Claude Desktop, extensión de VS Code, etc.)

Configuración Rápida

git clone https://github.com/myownipgit/enhanced-qrcode-mcp.git
cd enhanced-qrcode-mcp
chmod +x setup.sh
./setup.sh

Configuración Manual

# Create virtual environment
python3 -m venv venv
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Make server executable
chmod +x src/enhanced_qrcode_server.py

🔧 Configuración del Cliente MCP

Añada a la configuración de su cliente MCP:

{
  "mcpServers": {
    "enhanced-qrcode": {
      "command": "python3",
      "args": ["/path/to/enhanced-qrcode-mcp/src/enhanced_qrcode_server.py"],
      "env": {},
      "description": "Enhanced QR code generator with automatic PNG file saving"
    }
  }
}

📚 Herramientas Disponibles

1. `generate_and_save_qrcode`

Genera un código QR individual y lo guarda automáticamente como archivo PNG.

Parámetros:

content (obligatorio): Contenido de texto a codificar
output_directory: Directorio de destino (predeterminado: ./qr_output/)
filename: Nombre de archivo personalizado (se genera automáticamente si está vacío)
errorCorrectionLevel: L, M, Q o H (predeterminado: M)
size: Multiplicador de tamaño 1-20 (predeterminado: 5)
border: Tamaño del borde 1-20 (predeterminado: 4)
include_metadata: Generar metadatos JSON (predeterminado: true)
display_in_chat: Mostrar en la interfaz de chat (predeterminado: true)

Ejemplo:

{
  "content": "https://github.com/myownipgit/enhanced-qrcode-mcp",
  "output_directory": "./qr_codes/",
  "filename": "github_repo",
  "errorCorrectionLevel": "H",
  "size": 6
}

Salida:

Archivo PNG: github_repo.png
Metadatos: github_repo_metadata.json
Visualización en chat (opcional)

2. `batch_generate_qrcodes`

Genera múltiples códigos QR a partir de una entrada de matriz.

Ejemplo:

{
  "qr_codes": [
    {
      "id": "contact",
      "content": "BEGIN:VCARD\nVERSION:3.0\nFN:John Doe\nORG:Acme Corp\nTEL:555-0123\nEMAIL:john@acme.com\nEND:VCARD",
      "type": "vcard"
    },
    {
      "id": "website", 
      "content": "https://example.com",
      "type": "url"
    }
  ],
  "output_directory": "./batch_output/",
  "size": 5
}

Salida:

Archivos PNG: qr_contact.png, qr_website.png
Archivos de metadatos individuales
Manifiesto del lote: batch_manifest_YYYYMMDD_HHMMSS.json

3. `list_generated_qrcodes`

Lista todos los archivos de códigos QR en un directorio con metadatos.

{
  "directory": "./qr_output/"
}

📁 Estructura de Archivos

Archivos Generados

output_directory/
├── qr_20250616_143022_hello_world.png
├── qr_20250616_143022_hello_world_metadata.json
├── github_repo.png
├── github_repo_metadata.json
└── batch_manifest_20250616_143500.json

Formato de Metadatos

{
  "generated_date": "2025-06-16T14:30:22.123456",
  "content": "Hello World!",
  "parameters": {
    "error_correction": "M",
    "size": 5,
    "border": 4,
    "box_size": 10
  },
  "png_file": "/path/to/qr_file.png",
  "file_size_bytes": 1117
}

🎯 Casos de Uso

Aplicaciones Empresariales

Gestión de Eventos: Genere códigos QR para boletos como archivos PNG listos para imprimir
Marketing: Cree códigos QR para campañas con metadatos de seguimiento
Inventario: Genere etiquetas de activos con organización automática de archivos
Compartir Contactos: Cree códigos QR vCard por lotes para tarjetas de presentación

Integración Técnica

Producción de Impresión: Salida PNG directa para flujos de trabajo de diseño
Flujos de Trabajo API: Genere códigos QR por lotes desde registros de bases de datos
Gestión de Activos: Estructura de archivos organizada con metadatos
Control de Calidad: Niveles de corrección de errores para diferentes entornos

🧪 Pruebas

Ejecute la suite de pruebas completa:

# Activate virtual environment
source venv/bin/activate

# Run tests
python3 tests/test_server.py

Salida Esperada:

🚀 Running Enhanced QR Code MCP Server Tests
✅ QR code generation successful
✅ Filename generation tests passed  
✅ File operations tests passed
✅ Integration test passed - 3 files generated
📊 Test Results: 4/4 passed
🎉 All tests passed! Enhanced MCP server is ready to use.

📈 Rendimiento

Código QR individual: ~50ms de generación + guardado de archivo
Procesamiento por lotes: ~100ms por código + manifiesto
Generación de metadatos: ~5ms por archivo
Listado de archivos: ~10ms por 100 archivos

🔍 Niveles de Corrección de Errores

L (Bajo): ~7% de recuperación de daños - uso básico en interiores
M (Medio): ~15% de recuperación de daños - uso estándar (predeterminado)
Q (Cuartil): ~25% de recuperación de daños - entornos industriales
H (Alto): ~30% de recuperación de daños - superficies exteriores/dañadas

🚀 Mejoras Futuras

Consulte nuestro completo ROADMAP.md para planes de desarrollo detallados, incluyendo:

🔄 Próximamente (v2.1.0)

Constructores de contenido estructurado para vCard, WiFi y eventos
Formatos de salida SVG y PDF
Validación mejorada y optimización de contenido

🎨 Funciones Avanzadas (Disponibles en la Versión TypeScript)

Nuestra implementación en TypeScript ya incluye:

Estilos personalizados con colores, logotipos y degradados
Análisis de códigos QR y capacidades de decodificación
Sistema de plantillas con estilos predefinidos
Herramientas de evaluación de calidad con recomendaciones

🔗 Elegir la Implementación Correcta

Caso de Uso	Versión Recomendada
Generación de archivos y procesamiento por lotes	🐍 Versión Python (este repositorio)
Estilos avanzados y personalización	🟨 Versión TypeScript
Análisis y decodificación de códigos QR	🟨 Versión TypeScript
Flujos de trabajo de archivos en producción	🐍 Versión Python (este repositorio)
Generación basada en plantillas	🟨 Versión TypeScript
Seguimiento de metadatos y organización	🐍 Versión Python (este repositorio)

🐛 Solución de Problemas

Problemas Comunes

ModuleNotFoundError: No module named 'mcp'

pip install mcp

Permiso denegado en setup.sh

chmod +x setup.sh

El código QR no se guarda

Verifique los permisos del directorio
Confirme que la ruta de salida existe
Compruebe el espacio en disco

Pruebas del Servidor

# Test dependencies
python3 -c "import qrcode, mcp; print('✅ Dependencies OK')"

# Test server startup
python3 src/enhanced_qrcode_server.py

🤝 Contribuciones

¡Las contribuciones son bienvenidas! Consulte CONTRIBUTING.md para las pautas.

Configuración de Desarrollo

git clone https://github.com/myownipgit/enhanced-qrcode-mcp.git
cd enhanced-qrcode-mcp
./setup.sh
source venv/bin/activate
python3 tests/test_server.py

📄 Licencia

Licencia MIT - consulte el archivo LICENSE para más detalles.

🙏 Agradecimientos

Trabajo Original: @jwalsh/mcp-server-qrcode - Servidor MCP de códigos QR base
Protocolo MCP: Model Context Protocol - Habilitando la integración IA-herramientas
Biblioteca de Códigos QR: qrcode - Generación principal de códigos QR
Pillow: PIL/Pillow - Capacidades de procesamiento de imágenes

🔗 Proyectos Relacionados

Versión Mejorada en TypeScript - Funciones avanzadas de estilos y análisis
Servidor MCP de Códigos QR Original - La base sobre la que se construye esto
Model Context Protocol - Especificación y herramientas MCP
Claude Desktop - Asistente de IA con soporte MCP

📊 Estadísticas del Repositorio

Lenguaje: Python 3.8+
Dependencias: MCP, qrcode, Pillow
Cobertura de Pruebas: 100% (4/4 pruebas aprobadas)
Documentación: Completa con ejemplos
Licencia: MIT

Servidor MCP de Códigos QR Mejorado v2.0.0
Generación de códigos QR lista para producción con salida automática de archivos PNG y metadatos completos

Construido con ❤️ sobre la excelente base de @jwalsh/mcp-server-qrcode