Enhanced MCP QR Generator

A powerful and flexible MCP (Model Context Protocol) server for generating QR codes from URLs and text.

Developed by James Karanja at Zavora AI.

Features

• QR Code Generation: Create QR codes from any text or URL
• Multiple Output Formats: Generate QR codes as PNG, SVG, base64, or terminal ASCII art
• Customization Options: Control size, margins, colors, and error correction levels
• Logo Integration: Add custom logos to the center of QR codes
• File Saving: Save generated QR codes to files with custom or auto-generated names
• MCP Integration: Full Model Context Protocol support for AI assistants
• Docker Support: Easy deployment with Docker and Docker Compose
• Health Monitoring: Built-in health check endpoint

Installation

1npm install enhanced-mcp-qr-generator

Server Architecture

The Enhanced MCP QR Generator uses a single HTTP server that handles:

1. JSON-RPC Requests: For MCP protocol communication
2. Health Check Endpoint: Available at /health for monitoring

Port Configuration

The server uses port 9999 by default. You can change this by:

1. Setting the PORT environment variable
2. When using Docker, updating the PORT environment variable in docker-compose.yml
3. When using Docker, updating the port mapping in docker-compose.yml

Example:

1# Run with a custom port
2PORT=8080 npx enhanced-mcp-qr-generator

Configuration Precedence

Configuration values are determined in the following order (highest priority first):

1. Command line arguments
2. Environment variables
3. Default values from config.ts

As an MCP Server

1# Run directly from command line
2npx enhanced-mcp-qr-generator
3
4# With custom options
5npx enhanced-mcp-qr-generator --error-correction-level=H --format=svg --size=500

MCP Integration

The Enhanced MCP QR Generator implements the Model Context Protocol (MCP), allowing it to be used with various AI assistants and tools.

Available MCP Tools

• generate_qr: Generate a QR code from text or URL
• save_qr: Generate a QR code and save it to a file

Using with AI Assistants

Amazon Q CLI

To use with Amazon Q CLI, create an MCP configuration file:

1# Create a configuration directory if it doesn't exist
2mkdir -p ~/.aws/amazonq
3
4# Create the MCP configuration file
5cat > ~/.aws/amazonq/mcp.json << EOF
6{
7  "mcpServers": {
8    "qr-generator": {
9      "command": "npx",
10      "args": ["-y", "enhanced-mcp-qr-generator"]
11    }
12  }
13}
14EOF
15
16# Start Amazon Q with MCP support enabled
17q chat

You can also place the configuration in your project directory at .amazonq/mcp.json to share it with your team.

Claude Desktop

To use with Claude Desktop, create an MCP configuration file:

1{
2  "mcpServers": {
3    "qr-generator": {
4      "command": "npx",
5      "args": ["-y", "enhanced-mcp-qr-generator"]
6    }
7  }
8}

Add this configuration to your Claude Desktop settings file.

You can then use the QR generator tools in your conversation:

> Can you generate a QR code for my website https://example.com?

Docker Configuration

You can also run the server using Docker:

1{
2  "mcpServers": {
3    "qr-generator": {
4      "command": "docker",
5      "args": ["run", "-i", "--rm", "zavorai/enhanced-mcp-qr-generator"]
6    }
7  }
8}

Configuration

Create a custom configuration to control server behavior:

1import { generateQR, ServerConfig } from 'enhanced-mcp-qr-generator';
2
3const config: ServerConfig = {
4  defaultErrorCorrectionLevel: 'H',
5  defaultFormat: 'svg',
6  defaultSize: 500,
7  defaultMargin: 2,
8  defaultColor: '#000000',
9  defaultBackgroundColor: '#ffffff',
10  maxQRCodeSize: 2000,
11  maxLogoSize: 2 * 1024 * 1024, // 2MB
12  // ... other options
13};
14
15// Use the configuration with any operation
16const qrCode = await generateQR('https://example.com', {}, config);

Command Line Options

When running as an MCP server, the following command line options are available:

--error-correction-level=<L|M|Q|H>  Set error correction level
--format=<png|svg|base64|terminal>  Set output format
--size=<pixels>                     Set QR code size
--margin=<modules>                  Set margin size
--color=<color>                     Set QR code color
--background-color=<color>          Set background color

API Documentation

generateQR(text, options, config)

Generates a QR code from text or URL.

• text: Text or URL to encode in the QR code
• options: QR code generation options
  • errorCorrectionLevel: Error correction level ('L', 'M', 'Q', 'H')
  • format: Output format ('png', 'svg', 'base64', 'terminal')
  • size: Size of QR code in pixels
  • margin: Margin around the QR code in modules
  • color: Color of the QR code (dark modules)
  • backgroundColor: Background color of the QR code (light modules)
  • logo: Logo options
    • image: URL or base64 encoded image
    • size: Size of the logo as a percentage of the QR code size
• config: Server configuration (optional)

Returns a QRCodeResult object:

• data: Generated QR code data
• mimeType: MIME type of the generated QR code
• format: Format of the generated QR code
• size: Size of the generated QR code in pixels
• content: Original text or URL encoded in the QR code
• timestamp: Timestamp when the QR code was generated

saveQRToFile(qrResult, outputPath)

Saves a QR code to a file.

• qrResult: QR code result from generateQR
• outputPath: Output file path

Returns the path to the saved file.

MCP Protocol Implementation

This project implements the Model Context Protocol (MCP) specification, providing a standardized way for AI assistants to generate QR codes. The implementation follows the JSON-RPC 2.0 format required by MCP.

Tool Specifications

The MCP server provides two tools:

1. generate_qr: Generates a QR code and returns it in the specified format

   • Input: Text/URL, format options, styling options
   • Output: QR code data with metadata

2. save_qr: Generates a QR code and saves it to a file

   • Input: Text/URL, output path, format options, styling options
   • Output: File path and metadata

JSON-RPC Format

All requests and responses follow the JSON-RPC 2.0 format:

1// Example request
2{
3  "jsonrpc": "2.0",
4  "id": 1,
5  "method": "tools/call",
6  "params": {
7    "name": "generate_qr",
8    "arguments": {
9      "text": "https://example.com",
10      "format": "png",
11      "size": 300
12    }
13  }
14}
15
16// Example response
17{
18  "jsonrpc": "2.0",
19  "id": 1,
20  "result": {
21    "content": [
22      {
23        "type": "image",
24        "data": "base64-encoded-data",
25        "mimeType": "image/png"
26      }
27    ],
28    "structuredContent": {
29      "format": "png",
30      "size": 300,
31      "content": "https://example.com",
32      "timestamp": "2025-05-30T21:00:00Z"
33    }
34  }
35}

Development

Prerequisites

• Node.js (v14 or later)
• npm or yarn

Building

1# Install dependencies
2npm install
3
4# Build the project
5npm run build
6
7# Run tests
8npm test

Permission Management

If you encounter permission issues with node_modules, use one of these solutions:

Option 1: Fix Permissions Script

Run the included script to fix permissions:

1./fix-permissions.sh

This script will:

1. Check current ownership of node_modules
2. Create backups of package.json and package-lock.json
3. Remove the node_modules directory
4. Reinstall dependencies with correct permissions
5. Verify the fix worked correctly

Option 2: Docker-based npm

Use the Docker-based npm script to avoid permission issues:

1# Install dependencies
2./docker-npm.sh install
3
4# Or use npm ci for clean install
5./docker-npm.sh ci

This runs npm commands in a Docker container with your user permissions, preventing any root-owned files.

Testing

The project includes both unit tests and integration tests:

1# Run all tests
2npm test
3
4# Run only unit tests
5npm run test:unit
6
7# Run only integration tests
8npm run test:integration
9
10# Run tests with coverage
11npm run test:coverage

License

MIT License - see the LICENSE file for details.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.