# Mobile Design Intelligence MCP

Full-package MCP for **Flutter** & **React Native** mobile UI/UX design.

Three modules, 12 tools — covering the full design workflow: **research → audit → assets**.

---

## 🎨 Features

### Module 1 : Design Research
Search real apps, extract their design DNA.

| Tool | What it does |
|---|---|
| `mdesign_search_apps_ios` | Search real iOS apps via iTunes Search API (free, no key). Returns metadata, ratings, screenshot URLs, icon. |
| `mdesign_search_apps_android` | Search Google Play apps via anti-bot browser scraping. Returns package ids, names, icons. |
| `mdesign_get_app_android` | Full Google Play page: description, rating, icon, HD screenshots. |
| `mdesign_extract_palette` | Extract dominant colors from any image URL. Returns hex + semantic roles (primary/accent/background) + WCAG luminance. |

### Module 2 : Design Audit
WCAG compliance, touch targets, tech stack detection.

| Tool | What it does |
|---|---|
| `mdesign_audit_contrast` | Check WCAG AA/AAA contrast ratios between hex colors. Flags failing pairs. |
| `mdesign_audit_touch_targets` | Validate touch targets against iOS HIG 44pt / Material Design 48dp minimums. |
| `mdesign_detect_stack_from_files` | Detect Flutter vs React Native vs native from file names in an APK/IPA. |
| `mdesign_full_audit_report` | Full audit: contrast + touch targets + actionable fix recommendations. |

### Module 3 : Asset Factory
Generate production-ready assets from a single source image.

| Tool | What it does |
|---|---|
| `mdesign_generate_app_icons` | One source → iOS AppIcon.appiconset (17 sizes + Contents.json) + Android launcher icons (5 densities, round + square) + adaptive icon layers with auto-extracted background color. |
| `mdesign_generate_splash` | Android 12+ splash icon sets (all densities) with themed background. |
| `mdesign_generate_theme` | Extract palette from image URL → emit Flutter ThemeData (`app_theme.dart`) or RN design tokens (`theme.ts`). |
| `mdesign_research_to_theme` | One-shot pipeline: search app → grab icon → extract palette → generate theme code. Perfect for "design like X" requests. |

### Module 4 : Component Generator
Generate production-ready Flutter & React Native components from a design image.

| Tool | What it does |
|---|---|
| `mdesign_generate_component` | Extract palette from image → generate theme + component code. Supports: `bottom_navigation`, `app_bar`, `primary_button`, `card`. |

### Module 5 : A/B App Comparison
Side-by-side design metrics comparison between two apps.

| Tool | What it does |
|---|---|
| `mdesign_compare_apps` | Compare two apps on palette, WCAG contrast pass rate, ratings. Returns verdict + recommendation. |

---

## 🚀 Quick Start

### Windows
```powershell
cd mobile-design-mcp
python -m venv .venv
.\.venv\Scripts\activate
pip install -r requirements.txt
patchright install chromium
```

### Linux / macOS
```bash
cd mobile-design-mcp
chmod +x install.sh
./install.sh
```

---

## 🔌 Integration (Claude Desktop / OpenCode)

```json
{
  "mcpServers": {
    "mobile-design": {
      "command": "/path/to/mobile-design-mcp/.venv/Scripts/python.exe",
      "args": ["/path/to/mobile-design-mcp/server.py"],
      "cwd": "/path/to/mobile-design-mcp"
    }
  }
}
```

---

## 📱 Example Prompts

> *"Search for top ride-hailing apps and generate a Flutter theme based on the most popular one"*
> → `mdesign_research_to_theme("ride hailing", framework="flutter")` → `app_theme.dart` ready to paste

> *"Audit the contrast of my app's palette: #FC5404, #FFFFFF, #1C1B1F, #8CDCC4"*
> → `mdesign_full_audit_report(colors=[...], elements=[...])` → verdict + fixes

> *"Generate all the icons I need for iOS and Android from this 1024x1024 logo"*
> → `mdesign_generate_app_icons("~/logo.png")` → 42 files in `output/icons/`

> *"Is this APK built with Flutter or React Native?"*
> → `mdesign_detect_stack_from_files(["lib/armeabi-v7a/libflutter.so", ...])` → "flutter"

---

## 🌍 Portability

| | Windows | Linux | macOS |
|---|---|---|---|
| iTunes Search API | ✅ | ✅ | ✅ |
| Play Store scraping | ✅ | ✅ | ✅ |
| Image processing | ✅ | ✅ | ✅ |
| Asset generation | ✅ | ✅ | ✅ |
| Chrome auto-detect | ✅ | ✅ | ✅ |

---

## 🔒 Privacy

This MCP is **100% local**. No API keys required (iTunes Search API is free and anonymous). Your design files never leave your machine.