# QR Code Generator + MCP

A standalone QR code generator with beautiful styling options and Model Context Protocol (MCP) integration.

## Features

### Web App
- 10 pre-designed style presets
- Mobile-responsive design
- Custom logo upload support
- Export as SVG or PNG
- Logo positioning options (center, bottom-right)
- Dark/Light/System theme switcher
- Interactive sound effects with toggle control
- Built with Next.js 15 and React 19
- Full Kalypso design system styling

### MCP Integration
- AI-powered QR code generation via Claude Desktop & Cursor
- HTTP and stdio transport support
- Access all 10 style presets programmatically
- No browser needed - generate QR codes directly from AI tools
- Hosted endpoint or local deployment options

## Getting Started

### Web App

#### Installation

```bash
npm install
```

#### Development

```bash
npm run dev
```

Open [http://localhost:3000](http://localhost:3000) to see the QR code generator.

#### Build

```bash
npm run build:next
npm start
```

### MCP Server

#### Quick Start with Claude Desktop

Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "qr-tool": {
      "url": "https://qr-tool-mcp.vercel.app/api/mcp"
    }
  }
}
```

Restart Claude Desktop and you can now generate QR codes with AI!

**Example usage:**
```
Generate a QR code for https://instagram.com/kalypsodesigns using the neon-pulse style
```

#### Local MCP Server Development

```bash
npm run build:mcp
npm run start:mcp
```

For detailed setup instructions:
- [Claude Desktop Setup Guide](./CLAUDE_DESKTOP_SETUP.md)
- [Cursor IDE Setup Guide](./CURSOR_SETUP.md)

## Project Structure

```
├── src/
│   ├── app/                    # Next.js app directory
│   │   ├── qr-generator/       # QR code generator feature
│   │   ├── layout.tsx          # Root layout
│   │   └── page.tsx            # Home page
│   ├── components/             # Reusable components
│   │   ├── ui/                 # UI components (button, input, etc.)
│   │   └── mobile-tool-wrapper.tsx
│   ├── hooks/                  # Custom React hooks
│   ├── lib/                    # Utility functions
│   └── styles/                 # Global styles
├── public/                     # Static assets
└── package.json
```

## Available Scripts

### Web App
- `npm run dev` - Start development server
- `npm run build:next` - Build Next.js app for production
- `npm start` - Start production server

### MCP Server
- `npm run build:mcp` - Build MCP server
- `npm run start:mcp` - Start MCP server (stdio mode)
- `npm run build` - Build both web app and MCP server

### Code Quality
- `npm run lint` - Run linter
- `npm run lint:fix` - Fix linting issues
- `npm run format` - Format code with Biome
- `npm run type-check` - Run TypeScript type checking

## Technologies

### Frontend
- **Next.js 15** - React framework
- **React 19** - UI library
- **TypeScript** - Type safety
- **Tailwind CSS** - Styling
- **Radix UI** - Accessible components
- **next-themes** - Theme management
- **Motion** - Smooth animations

### MCP Server
- **@modelcontextprotocol/sdk** - MCP protocol implementation
- **Zod** - Schema validation
- **jsdom** - Headless DOM for server-side QR generation
- **qr-code-styling** - QR code generation
- **jszip** - ZIP file generation for batch downloads

### Code Quality
- **Biome** - Linting and formatting
- **Husky** - Git hooks
- **TypeScript** - Type safety

## MCP Tools

### `generate_qr_code`
Generate a styled QR code with custom options.

**Parameters:**
- `url` (required) - The URL or text to encode
- `style` (optional) - Style preset ID (default: "slate-ember")
- `format` (optional) - "svg" or "png" (default: "svg")
- `size` (optional) - Dimensions 256-2048px (default: 768)
- `logoPosition` (optional) - "center" or "bottom-right"

### `generate_qr_urls_batch`
Generate QR codes for multiple URLs at once. Returns a single ZIP file download URL containing all QR codes with filenames based on the URLs.

**Parameters:**
- `urls` (required) - Array of URLs or text content to encode (max 100)
- `style` (optional) - Style preset to apply to all QR codes (default: "slate-ember")

**Returns:**
A single download URL that delivers a ZIP file containing all QR codes as SVG files. Filenames are automatically generated from the URLs (e.g., `001-example-com-page.svg`, `002-github-com-user.svg`).

**Example:**
```
Generate QR codes for these URLs: https://example.com, https://github.com/user, https://twitter.com/handle
```

### `get_available_styles`
List all available QR code style presets with color schemes.

### `preview_qr_url`
Generate a shareable web preview URL for customization.

## Available Styles

1. **slate-ember** - Dark slate with orange accent (default)
2. **ink-lime** - Deep black with lime green
3. **charcoal-cyan** - Navy charcoal with cyan
4. **night-sky** - Midnight blue with sky blue
5. **graphite-gold** - Dark graphite with gold
6. **espresso-rose** - Dark brown with rose pink
7. **plum-ice** - Deep purple with lavender
8. **forest-mint** - Forest green with mint
9. **cocoa-orange** - Warm brown with orange
10. **mono-high** - High contrast black & white

## License

MIT License - see [LICENSE](./LICENSE) file for details.