antoBrugnot/qrcode-mcp

QR Code MCP Server

Un serveur MCP (Model Context Protocol) pour générer des QR codes à partir de texte ou d'URLs en utilisant Node.js et TypeScript.

🚀 Fonctionnalités

• Génération de QR codes en multiple formats : DataURL (base64), SVG, et affichage terminal
• Options de personnalisation avancées : Niveau de correction d'erreur, taille, marge, couleurs
• Génération en lot : Traiter plusieurs textes/URLs en une seule commande
• Interface MCP standardisée : Compatible avec tous les clients MCP
• Support TypeScript complet : Types sûrs et auto-complétion

📦 Installation

Option 1: Docker/Podman (Recommandé) 🐳

Prérequis: Docker ou Podman installé sur votre système

# Avec Docker
docker pull antobrugnot/qrcode-mcp-server:latest

# Ou avec Podman (plus sécurisé, rootless)
podman pull antobrugnot/qrcode-mcp-server:latest

# Build local avec Docker
docker build -t qrcode-mcp-server .

# Build local avec Podman
podman build -t qrcode-mcp-server .

Option 2: Installation locale

Prérequis:

• Node.js 18.0.0 ou supérieur
• npm ou yarn

# Cloner le projet
git clone <votre-repo>
cd qrcode-mcp

# Installer les dépendances
npm install

# Builder le projet
npm run build

🛠️ Utilisation

Avec Docker/Podman (Recommandé)

# Avec Docker
docker run -i --rm antobrugnot/qrcode-mcp-server:latest

# Avec Podman (plus sécurisé)
podman run -i --rm antobrugnot/qrcode-mcp-server:latest

# Avec Docker Compose
docker-compose up qrcode-mcp-server

# Avec Podman Compose
podman-compose up qrcode-mcp-server

# Mode développement
docker-compose --profile dev up qrcode-mcp-dev
# ou
podman-compose --profile dev up qrcode-mcp-dev

Développement local

# Mode développement avec rechargement automatique
npm run dev

# Ou en mode watch
npm run watch

# Builder pour la production
npm run build

# Lancer la version buildée
npm start

🔧 Outils MCP disponibles

1. generate-qrcode-dataurl

Génère un QR code et le retourne sous forme de Data URL (base64).

Paramètres :

• text (string, requis) : Le texte ou URL à encoder
• options (object, optionnel) : Options de génération
  • errorCorrectionLevel : 'L', 'M', 'Q', ou 'H' (défaut: 'M')
  • width : Largeur en pixels (50-2000)
  • margin : Marge en modules (0-10, défaut: 4)
  • color.dark : Couleur des modules sombres (défaut: '#000000')
  • color.light : Couleur de l'arrière-plan (défaut: '#FFFFFF')
  • type : Type MIME ('image/png', 'image/jpeg', 'image/webp')

Exemple d'utilisation :

{
  "text": "https://github.com",
  "options": {
    "width": 300,
    "errorCorrectionLevel": "H",
    "color": {
      "dark": "#1f2937",
      "light": "#f3f4f6"
    }
  }
}

2. generate-qrcode-svg

Génère un QR code au format SVG.

Paramètres :

• text (string, requis) : Le texte ou URL à encoder
• options (object, optionnel) : Options de génération (similaires à dataurl)

Exemple d'utilisation :

{
  "text": "Hello, World!",
  "options": {
    "width": 200,
    "margin": 2
  }
}

3. generate-qrcode-terminal

Génère un QR code pour affichage dans le terminal.

Paramètres :

• text (string, requis) : Le texte ou URL à encoder
• options (object, optionnel) :
  • small (boolean) : Utiliser le format compact (défaut: false)

Exemple d'utilisation :

{
  "text": "Terminal QR Code",
  "options": {
    "small": true
  }
}

4. generate-qrcode-batch

Génère plusieurs QR codes en une seule opération (maximum 10).

Paramètres :

• texts (array[string], requis) : Tableau de textes/URLs à encoder (max 10)
• format (string, optionnel) : Format de sortie ('dataurl', 'svg', 'terminal', défaut: 'dataurl')
• options (object, optionnel) : Options de génération

Exemple d'utilisation :

{
  "texts": [
    "https://github.com",
    "https://www.google.com",
    "Hello World"
  ],
  "format": "dataurl",
  "options": {
    "width": 200
  }
}

🎯 Utilisation avec des clients MCP

Claude Desktop (ou Github Copilot)

ℹ️ Astuce GitHub Copilot :
Pour GitHub Copilot, la clé mcpServers dans la configuration devient simplement servers.

Option 1: Avec Docker/Podman (Recommandé)

Ajoutez cette configuration à votre claude_desktop_config.json :

{
  "mcpServers": {
    "qrcode-generator": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "antobrugnot/qrcode-mcp-server:latest"]
    }
  }
}

Ou avec Podman (plus sécurisé, rootless) :

{
  "mcpServers": {
    "qrcode-generator": {
      "command": "podman",
      "args": ["run", "-i", "--rm", "antobrugnot/qrcode-mcp-server:latest"]
    }
  }
}

Option 2: Installation locale

{
  "mcpServers": {
    "qrcode-generator": {
      "command": "node",
      "args": ["/chemin/vers/qrcode-mcp/dist/index.js"]
    }
  }
}

Autres clients MCP

Le serveur utilise le transport stdio standard et peut être utilisé avec n'importe quel client MCP compatible.

📋 Exemples d'utilisation

Générer un QR code simple

Générez un QR code pour "https://github.com"

QR code personnalisé

Générez un QR code pour "Mon site web" avec une largeur de 400px et des couleurs personnalisées (sombre: #2563eb, clair: #eff6ff)

QR codes en lot

Générez des QR codes pour ces URLs : https://github.com, https://stackoverflow.com, https://nodejs.org

QR code pour terminal

Générez un QR code terminal pour "Test terminal" en format compact

🔒 Sécurité

Mesures de sécurité implémentées

• Container sécurisé : Utilisation d'un utilisateur non-root (UID 1001)
• Image Alpine : Image de base minimale pour réduire la surface d'attaque
• Capabilities limitées : Suppression de toutes les capabilities Linux non nécessaires
• Read-only filesystem : Container en lecture seule pour prévenir les modifications
• Resource limits : Limites CPU et mémoire pour éviter les attaques DoS
• Security scanning : Scan automatique des vulnérabilités avec Trivy
• Dependency audit : Vérification automatique des dépendances npm
• Multi-stage build : Build optimisé sans outils de développement en production

Bonnes pratiques

• Utilisez toujours la dernière version taguée
• Vérifiez régulièrement les mises à jour de sécurité
• Surveillez les alertes GitHub Security
• Utilisez des secrets GitHub pour les tokens DockerHub

🔄 CI/CD

Processus automatisé

• Tests automatiques : TypeScript, build et audits de sécurité
• Build multi-architecture : Support AMD64 et ARM64
• Push automatique : DockerHub avec tags appropriés
• Scan de sécurité : Trivy pour détecter les vulnérabilités
• Release automatique : GitHub Releases avec notes générées

Variables d'environnement à configurer

# Dans GitHub Secrets
DOCKERHUB_TOKEN=your_dockerhub_token

🏗️ Architecture

qrcode-mcp/
├── .github/
│   └── workflows/        # GitHub Actions CI/CD
├── scripts/
│   └── release.sh        # Script de release
├── src/
│   └── index.ts          # Serveur MCP principal
├── dist/                 # Fichiers compilés
├── Dockerfile            # Configuration Docker
├── docker-compose.yml    # Orchestration Docker
├── .dockerignore         # Exclusions Docker
├── package.json          # Dépendances et scripts
├── tsconfig.json         # Configuration TypeScript
├── CONFIGURATION.md      # Guide de configuration
└── README.md            # Documentation

🔧 Technologies utilisées

• Node.js : Runtime JavaScript
• TypeScript : Typage statique
• @modelcontextprotocol/sdk : SDK MCP officiel
• qrcode : Bibliothèque de génération de QR codes
• zod : Validation de schémas

📝 Niveaux de correction d'erreur

• L (Low) : ~7% de récupération d'erreur
• M (Medium) : ~15% de récupération d'erreur (recommandé)
• Q (Quartile) : ~25% de récupération d'erreur
• H (High) : ~30% de récupération d'erreur

🐛 Dépannage

Erreur "Module not found"

Assurez-vous d'avoir installé les dépendances :

npm install

Erreur de compilation TypeScript

Vérifiez la configuration dans tsconfig.json et rebuilder :

npm run build

Le serveur ne démarre pas

Vérifiez que Node.js 18+ est installé :

node --version

🚀 Release et Déploiement

Créer une nouvelle release

# Utiliser le script de release
./scripts/release.sh v1.0.0

# Ou déclencher manuellement via GitHub Actions
# GitHub → Actions → Release → Run workflow

Processus de release automatique

1. Validation : Tests, build et vérifications
2. Versioning : Mise à jour package.json et création du tag
3. Docker Build : Build et push multi-architecture
4. Security Scan : Analyse de sécurité avec Trivy
5. GitHub Release : Création avec notes automatiques
6. Notification : Confirmation du succès

Images Docker disponibles

# Dernière version stable
docker pull antobrugnot/qrcode-mcp-server:latest

# Version spécifique
docker pull antobrugnot/qrcode-mcp-server:v1.0.0

# Version de développement (branch develop)
docker pull antobrugnot/qrcode-mcp-server:develop

🤝 Contribution

Les contributions sont les bienvenues ! N'hésitez pas à ouvrir une issue ou soumettre une pull request.

Processus de contribution

1. Fork le projet
2. Créer une branche feature (git checkout -b feature/amazing-feature)
3. Commiter vos changements (git commit -m 'Add amazing feature')
4. Pousser vers la branche (git push origin feature/amazing-feature)
5. Ouvrir une Pull Request

Standards de code

• Utilisez TypeScript avec strict mode
• Suivez les conventions ESLint/Prettier
• Ajoutez des tests pour les nouvelles fonctionnalités
• Mettez à jour la documentation si nécessaire

📄 Licence

MIT License - voir le fichier LICENSE pour plus de détails.

🔗 Liens utiles

• Model Context Protocol
• SDK TypeScript MCP
• Bibliothèque QRCode