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

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

Validation : Tests, build et vérifications
Versioning : Mise à jour package.json et création du tag
Docker Build : Build et push multi-architecture
Security Scan : Analyse de sécurité avec Trivy
GitHub Release : Création avec notes automatiques
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

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