Enhanced QR Code MCP Server

Gera códigos QR com metadados, processamento em lote e ferramentas de gerenciamento de arquivos.

Documentação

Enhanced QR Code MCP Server

Um servidor avançado de Model Context Protocol (MCP) que gera códigos QR e os salva automaticamente como arquivos PNG com metadados abrangentes, capacidades de processamento em lote e ferramentas de gerenciamento de arquivos.

🔗 Estratégia de Implementação Dupla
Esta implementação em Python foca em geração confiável de arquivos e processamento em lote.
Para estilização avançada, análise e modelos, consulte nossa implementação em TypeScript.

Construído sobre e aprimorado a partir de: @jwalsh/mcp-server-qrcode

Esta versão aprimorada adiciona geração automática de arquivos, rastreamento de metadados, processamento em lote e recursos prontos para produção, mantendo total compatibilidade com o protocolo MCP.

🚀 Principais Aprimoramentos em Relação ao Original

Recurso	MCP Original	MCP Python Aprimorado	MCP TypeScript Aprimorado
Saída de Arquivo PNG	❌ Apenas exibição no chat	✅ Salvamento automático de arquivo PNG	✅ Múltiplos formatos (PNG, SVG, PDF)
Gerenciamento de Diretórios	❌ Nenhum	✅ Diretórios de saída personalizados	✅ Caminhos configuráveis
Rastreamento de Metadados	❌ Nenhum	✅ Arquivos de metadados JSON	✅ Metadados abrangentes
Processamento em Lote	❌ Um por vez	✅ Múltiplos códigos QR por chamada	✅ Recursos avançados de lote
Organização de Arquivos	❌ Nenhum	✅ Gerenciamento estruturado de arquivos	✅ Organização baseada em modelos
Nomes de Arquivo Personalizados	❌ Nenhum	✅ Nomeação definida pelo usuário	✅ Padrões inteligentes de nomeação
Pronto para Produção	❌ Básico	✅ Suíte de testes completa e documentação	✅ Recursos empresariais
Estilização Avançada	❌ Nenhum	🔄 Planejado (veja ROADMAP)	✅ Mecanismo completo de estilização
Análise de QR	❌ Nenhum	🔄 Planejado (veja ROADMAP)	✅ Decodificação e análise de qualidade
Modelos	❌ Nenhum	🔄 Planejado (veja ROADMAP)	✅ Modelos pré-definidos

🛠️ Instalação

Pré-requisitos

Python 3.8+
Cliente MCP (Claude Desktop, extensão VS Code, etc.)

Configuração Rápida

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

Configuração 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

🔧 Configuração do Cliente MCP

Adicione à configuração do seu 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"
    }
  }
}

📚 Ferramentas Disponíveis

1. `generate_and_save_qrcode`

Gere um único código QR e salve automaticamente como arquivo PNG.

Parâmetros:

content (obrigatório): Conteúdo de texto a ser codificado
output_directory: Diretório de destino (padrão: ./qr_output/)
filename: Nome de arquivo personalizado (gerado automaticamente se vazio)
errorCorrectionLevel: L, M, Q ou H (padrão: M)
size: Multiplicador de tamanho 1-20 (padrão: 5)
border: Tamanho da borda 1-20 (padrão: 4)
include_metadata: Gerar metadados JSON (padrão: verdadeiro)
display_in_chat: Mostrar na interface do chat (padrão: verdadeiro)

Exemplo:

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

Saída:

Arquivo PNG: github_repo.png
Metadados: github_repo_metadata.json
Exibição no chat (opcional)

2. `batch_generate_qrcodes`

Gere múltiplos códigos QR a partir de entrada em array.

Exemplo:

{
  "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
}

Saída:

Arquivos PNG: qr_contact.png, qr_website.png
Arquivos de metadados individuais
Manifesto do lote: batch_manifest_YYYYMMDD_HHMMSS.json

3. `list_generated_qrcodes`

Liste todos os arquivos de código QR em um diretório com metadados.

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

📁 Estrutura de Arquivos

Arquivos Gerados

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 Metadados

{
  "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

Aplicações Empresariais

Gerenciamento de Eventos: Gere códigos QR de ingressos como arquivos PNG prontos para impressão
Marketing: Crie códigos QR de campanhas com metadados de rastreamento
Inventário: Gere etiquetas de ativos com organização automática de arquivos
Compartilhamento de Contatos: Crie códigos QR vCard em lote para cartões de visita

Integração Técnica

Produção de Impressão: Saída PNG direta para fluxos de trabalho de design
Fluxos de Trabalho de API: Gere códigos QR em lote a partir de registros de banco de dados
Gerenciamento de Ativos: Estrutura de arquivos organizada com metadados
Controle de Qualidade: Níveis de correção de erros para diferentes ambientes

🧪 Testes

Execute a suíte de testes abrangente:

# Activate virtual environment
source venv/bin/activate

# Run tests
python3 tests/test_server.py

Saída 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.

📈 Desempenho

Código QR único: ~50ms de geração + salvamento de arquivo
Processamento em lote: ~100ms por código + manifesto
Geração de metadados: ~5ms por arquivo
Listagem de arquivos: ~10ms por 100 arquivos

🔍 Níveis de Correção de Erros

L (Baixo): ~7% de recuperação de danos - uso básico em ambientes internos
M (Médio): ~15% de recuperação de danos - uso padrão (padrão)
Q (Quartil): ~25% de recuperação de danos - ambientes industriais
H (Alto): ~30% de recuperação de danos - superfícies externas/danificadas

🚀 Aprimoramentos Futuros

Consulte nosso ROADMAP.md abrangente para planos detalhados de desenvolvimento, incluindo:

🔄 Em Breve (v2.1.0)

Construtores de conteúdo estruturado para vCard, WiFi e eventos
Formatos de saída SVG e PDF
Validação aprimorada e otimização de conteúdo

🎨 Recursos Avançados (Disponíveis na Versão TypeScript)

Nossa implementação em TypeScript já inclui:

Estilização personalizada com cores, logotipos e gradientes
Análise de código QR e capacidades de decodificação
Sistema de modelos com estilos pré-definidos
Ferramentas de avaliação de qualidade com recomendações

🔗 Escolhendo a Implementação Correta

Caso de Uso	Versão Recomendada
Geração de arquivos e processamento em lote	🐍 Versão Python (este repositório)
Estilização e personalização avançadas	🟨 Versão TypeScript
Análise e decodificação de código QR	🟨 Versão TypeScript
Fluxos de trabalho de arquivos em produção	🐍 Versão Python (este repositório)
Geração baseada em modelos	🟨 Versão TypeScript
Rastreamento e organização de metadados	🐍 Versão Python (este repositório)

🐛 Solução de Problemas

Problemas Comuns

ModuleNotFoundError: No module named 'mcp'

pip install mcp

Permissão negada no setup.sh

chmod +x setup.sh

Código QR não está sendo salvo

Verifique as permissões do diretório
Confirme se o caminho de saída existe
Verifique o espaço em disco

Testando o Servidor

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

# Test server startup
python3 src/enhanced_qrcode_server.py

🤝 Contribuindo

Contribuições são bem-vindas! Consulte CONTRIBUTING.md para diretrizes.

Configuração de Desenvolvimento

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

📄 Licença

Licença MIT - consulte o arquivo LICENSE para detalhes.

🙏 Agradecimentos

Trabalho Original: @jwalsh/mcp-server-qrcode - Servidor MCP de código QR fundamental
Protocolo MCP: Model Context Protocol - Habilitando integração IA-ferramenta
Biblioteca de Código QR: qrcode - Geração principal de código QR
Pillow: PIL/Pillow - Capacidades de processamento de imagem

🔗 Projetos Relacionados

Versão Aprimorada em TypeScript - Recursos avançados de estilização e análise
Servidor MCP de Código QR Original - A base sobre a qual isto foi construído
Model Context Protocol - Especificação e ferramentas MCP
Claude Desktop - Assistente de IA com suporte MCP

📊 Estatísticas do Repositório

Linguagem: Python 3.8+
Dependências: MCP, qrcode, Pillow
Cobertura de Testes: 100% (4/4 testes passando)
Documentação: Completa com exemplos
Licença: MIT

Enhanced QR Code MCP Server v2.0.0
Geração de código QR pronta para produção com saída automática de arquivo PNG e metadados abrangentes

Construído com ❤️ sobre a excelente base de @jwalsh/mcp-server-qrcode

Enhanced QR Code MCP Server

Documentação