QR Code MCP Server

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

Fonctionnalits

• Gnration de QR codes en multiple formats : DataURL (base64), SVG, et affichage terminal
• Options de personnalisation avances : Niveau de correction d'erreur, taille, marge, couleurs
• Gnration en lot : Traiter plusieurs textes/URLs en une seule commande
• Interface MCP standardise : Compatible avec tous les clients MCP
• Support TypeScript complet : Types srs et auto-compltion

Installation

Option 1: Docker/Podman (Recommand)

Prrequis: Docker ou Podman install sur votre systme

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

# Ou avec Podman (plus scuris, 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

Prrequis:

• Node.js 18.0.0 ou suprieur
• npm ou yarn

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

# Installer les dpendances
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 scuris)
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 dveloppement
docker-compose --profile dev up qrcode-mcp-dev
# ou
podman-compose --profile dev up qrcode-mcp-dev

Dveloppement local

# Mode dveloppement avec rechargement automatique
npm run dev

# Ou en mode watch
npm run watch

# Builder pour la production
npm run build

# Lancer la version builde
npm start

Outils MCP disponibles

1. generate-qrcode-dataurl

Gnre un QR code et le retourne sous forme de Data URL (base64).

Paramtres :

• text (string, requis) : Le texte ou URL encoder
• options (object, optionnel) : Options de gnration
  • errorCorrectionLevel : 'L', 'M', 'Q', ou 'H' (dfaut: 'M')
  • width : Largeur en pixels (50-2000)
  • margin : Marge en modules (0-10, dfaut: 4)
  • color.dark : Couleur des modules sombres (dfaut: '#000000')
  • color.light : Couleur de l'arrire-plan (dfaut: '#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

Gnre un QR code au format SVG.

Paramtres :

• text (string, requis) : Le texte ou URL encoder
• options (object, optionnel) : Options de gnration (similaires dataurl)

Exemple d'utilisation :

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

3. generate-qrcode-terminal

Gnre un QR code pour affichage dans le terminal.

Paramtres :

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

Exemple d'utilisation :

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

4. generate-qrcode-batch

Gnre plusieurs QR codes en une seule opration (maximum 10).

Paramtres :

• texts (array[string], requis) : Tableau de textes/URLs encoder (max 10)
• format (string, optionnel) : Format de sortie ('dataurl', 'svg', 'terminal', dfaut: 'dataurl')
• options (object, optionnel) : Options de gnration

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 scuris, 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

Gnrer un QR code simple

Gnrez un QR code pour "https://github.com"

QR code personnalis

Gnrez un QR code pour "Mon site web" avec une largeur de 400px et des couleurs personnalises (sombre: #2563eb, clair: #eff6ff)

QR codes en lot

Gnrez des QR codes pour ces URLs : https://github.com, https://stackoverflow.com, https://nodejs.org

QR code pour terminal

Gnrez un QR code terminal pour "Test terminal" en format compact

Scurit

Mesures de scurit implmentes

• Container scuris : Utilisation d'un utilisateur non-root (UID 1001)
• Image Alpine : Image de base minimale pour rduire la surface d'attaque
• Capabilities limites : Suppression de toutes les capabilities Linux non ncessaires
• Read-only filesystem : Container en lecture seule pour prvenir les modifications
• Resource limits : Limites CPU et mmoire pour viter les attaques DoS
• Security scanning : Scan automatique des vulnrabilits avec Trivy
• Dependency audit : Vrification automatique des dpendances npm
• Multi-stage build : Build optimis sans outils de dveloppement en production

Bonnes pratiques

• Utilisez toujours la dernire version tague
• Vrifiez rgulirement les mises jour de scurit
• Surveillez les alertes GitHub Security
• Utilisez des secrets GitHub pour les tokens DockerHub

CI/CD

Processus automatis

• Tests automatiques : TypeScript, build et audits de scurit
• Build multi-architecture : Support AMD64 et ARM64
• Push automatique : DockerHub avec tags appropris
• Scan de scurit : Trivy pour dtecter les vulnrabilits
• Release automatique : GitHub Releases avec notes gnres

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 compils
 Dockerfile            # Configuration Docker
 docker-compose.yml    # Orchestration Docker
 .dockerignore         # Exclusions Docker
 package.json          # Dpendances et scripts
 tsconfig.json         # Configuration TypeScript
 CONFIGURATION.md      # Guide de configuration
 README.md            # Documentation

Technologies utilises

• Node.js : Runtime JavaScript
• TypeScript : Typage statique
• @modelcontextprotocol/sdk : SDK MCP officiel
• qrcode : Bibliothque de gnration de QR codes
• zod : Validation de schmas

Niveaux de correction d'erreur

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

Dpannage

Erreur "Module not found"

Assurez-vous d'avoir install les dpendances :

npm install

Erreur de compilation TypeScript

Vrifiez la configuration dans tsconfig.json et rebuilder :

npm run build

Le serveur ne dmarre pas

Vrifiez que Node.js 18+ est install :

node --version

Release et Dploiement

Crer une nouvelle release

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

# Ou dclencher manuellement via GitHub Actions
# GitHub  Actions  Release  Run workflow

Processus de release automatique

1. Validation : Tests, build et vrifications
2. Versioning : Mise jour package.json et cration du tag
3. Docker Build : Build et push multi-architecture
4. Security Scan : Analyse de scurit avec Trivy
5. GitHub Release : Cration avec notes automatiques
6. Notification : Confirmation du succs

Images Docker disponibles

# Dernire version stable
docker pull antobrugnot/qrcode-mcp-server:latest

# Version spcifique
docker pull antobrugnot/qrcode-mcp-server:v1.0.0

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

Contribution

Les contributions sont les bienvenues ! N'hsitez pas ouvrir une issue ou soumettre une pull request.

Processus de contribution

1. Fork le projet
2. Crer 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 fonctionnalits
• Mettez jour la documentation si ncessaire

Licence

MIT License - voir le fichier LICENSE pour plus de dtails.

Liens utiles

• Model Context Protocol
• SDK TypeScript MCP
• Bibliothque QRCode