Sample MCP Server - Python (qr-code-server)

[crivetimihai]

Overview

Create a simple MCP Server in Python that provides QR code generation and decoding capabilities, perfect for beginners to learn MCP server development.

Server Specifications

Server Details

• Name: qr-code-server
• Language: Python 3.11+
• Location: mcp-servers/python/qr_code_server/
• Complexity: ⭐ Beginner-friendly
• Purpose: Demonstrate simple utility MCP server with practical functionality

Core Features

• QR code generation from text, URLs, and data
• QR code decoding from image files
• Multiple output formats (PNG, SVG, ASCII)
• Customizable QR code styling and error correction
• Batch processing support

Tools Provided

1. generate_qr_code

Generate QR codes from text or data

@dataclass
class QRGenerationRequest:
    data: str  # Text, URL, or data to encode
    format: str = "png"  # png, svg, ascii
    size: int = 10  # QR code module size
    border: int = 4  # Border size in modules
    error_correction: str = "M"  # L, M, Q, H
    fill_color: str = "black"
    back_color: str = "white"
    save_path: Optional[str] = None
    return_base64: bool = False

2. decode_qr_code

Decode QR codes from image files

@dataclass
class QRDecodingRequest:
    image_data: str  # base64 image data or file path
    image_format: str = "auto"  # auto, png, jpg, gif
    multiple_codes: bool = False  # Detect multiple QR codes
    return_positions: bool = False  # Return QR code positions
    preprocessing: bool = True  # Image preprocessing for better detection

3. generate_batch_qr_codes

Generate multiple QR codes efficiently

@dataclass
class BatchQRGenerationRequest:
    data_list: List[str]  # List of data to encode
    format: str = "png"
    size: int = 10
    naming_pattern: str = "qr_{index}"  # File naming pattern
    output_directory: str = "./qr_codes/"
    zip_output: bool = False  # Create ZIP archive

4. validate_qr_data

Validate and analyze QR code data before generation

@dataclass
class QRValidationRequest:
    data: str
    target_version: Optional[int] = None  # QR code version (1-40)
    error_correction: str = "M"
    check_capacity: bool = True
    suggest_optimization: bool = True

Implementation Requirements

Directory Structure

mcp-servers/python/qr_code_server/
├── src/
│   └── qr_code_server/
│       ├── __init__.py
│       ├── server.py
│       ├── tools/
│       │   ├── __init__.py
│       │   ├── generator.py
│       │   ├── decoder.py
│       │   └── validator.py
│       ├── utils/
│       │   ├── __init__.py
│       │   ├── image_utils.py
│       │   └── file_utils.py
│       └── config.py
├── tests/
│   ├── __init__.py
│   ├── test_generator.py
│   ├── test_decoder.py
│   └── fixtures/
│       ├── sample_qr_codes/
│       └── test_images/
├── requirements.txt
├── requirements-dev.txt
├── pyproject.toml
├── README.md
├── examples/
│   ├── basic_usage.py
│   ├── batch_generation.py
│   └── web_integration.py
└── Makefile

Dependencies

# requirements.txt
mcp>=1.0.0
qrcode[pil]>=7.4.2
pillow>=10.0.0
pyzbar>=0.1.9
opencv-python>=4.8.0
pydantic>=2.5.0
base64>=0.0.1

# Optional dependencies for enhanced features
cairosvg>=2.7.1  # SVG support
numpy>=1.24.0    # Image processing

Configuration

# config.yaml
qr_generation:
  default_size: 10
  default_border: 4
  default_error_correction: "M"  # L=7%, M=15%, Q=25%, H=30%
  max_data_length: 4296  # Max characters for QR code
  supported_formats: ["png", "svg", "ascii"]
  
output:
  default_directory: "./output/"
  max_batch_size: 100
  enable_zip_export: true
  
decoding:
  preprocessing_enabled: true
  max_image_size: "10MB"
  supported_image_formats: ["png", "jpg", "jpeg", "gif", "bmp", "tiff"]
  
performance:
  cache_generated_codes: false  # Don't cache for security
  max_concurrent_requests: 10

Usage Examples

Basic QR Code Generation

# Generate QR code for a URL
echo '{
  "method": "tools/call",
  "params": {
    "name": "generate_qr_code",
    "arguments": {
      "data": "https://github.com/IBM/mcp-context-forge",
      "format": "png",
      "size": 10,
      "error_correction": "M",
      "save_path": "./github_qr.png"
    }
  }
}' | qr-code-server

QR Code Decoding

# Decode QR code from image file
echo '{
  "method": "tools/call",
  "params": {
    "name": "decode_qr_code",
    "arguments": {
      "image_data": "./sample_qr.png",
      "multiple_codes": false,
      "return_positions": true
    }
  }
}' | qr-code-server

Batch Generation

# Generate multiple QR codes
echo '{
  "method": "tools/call",
  "params": {
    "name": "generate_batch_qr_codes",
    "arguments": {
      "data_list": [
        "https://example.com/page1",
        "https://example.com/page2", 
        "Contact: John Doe, email@example.com"
      ],
      "format": "png",
      "naming_pattern": "batch_qr_{index}",
      "zip_output": true
    }
  }
}' | qr-code-server

Advanced Features

• Custom Styling: Logo embedding, custom colors, rounded corners
• Data Types: Support for URLs, vCards, WiFi credentials, SMS
• Error Correction: Multiple levels with capacity optimization
• Image Processing: Automatic image enhancement for better decoding
• Validation: Pre-generation data validation and optimization

Testing Requirements

• Unit tests for generation and decoding functions
• Integration tests with various data types
• Performance tests with large batches
• Image quality tests for different formats
• Error handling tests for invalid inputs

Acceptance Criteria

• Python MCP server with 4+ QR code tools
• QR code generation in multiple formats (PNG, SVG, ASCII)
• QR code decoding from various image formats
• Batch processing capabilities
• Data validation and optimization
• Customizable styling options
• Error correction level support
• Comprehensive test suite (>90% coverage)
• Complete documentation with examples
• Simple and intuitive API design

Priority

Low - Great beginner project for learning MCP server development

Use Cases

• Contact information sharing (vCard QR codes)
• URL sharing and link shortening integration
• Event ticket and registration systems
• WiFi credential sharing
• Payment and cryptocurrency addresses
• Inventory and asset management
• Marketing and promotional campaigns
• Educational and training materials