# Frontend Guru MCP

Transform designs to Elevate 2.0 design system - MCP server + web interface

## 🎯 What This Does

Takes design inputs (URLs, screenshots, descriptions) and transforms them into production-ready React components that follow G2's Elevate 2.0 design system.

**Two interfaces:**
- **MCP Server** - For Claude Code users (CLI + Desktop tab)
- **Web Interface** - For everyone else (GUI, zero setup)

---

## 🚀 Quick Start

### For Claude Code Users (MCP Server)

**1. Install dependencies:**
```bash
npm install
npm run build
```

**2. Configure Claude Code/Desktop:**

Add to your MCP config file:

**Claude Desktop:** `~/Library/Application Support/Claude/claude_desktop_config.json`
**Claude Code:** `~/.claude/mcp_servers.json`

```json
{
  "mcpServers": {
    "frontend-guru": {
      "command": "node",
      "args": ["/Users/abedell/Developer/frontend-guru-mcp/dist/mcp/index.js"]
    }
  }
}
```

**3. Restart Claude**

**4. Use it:**
```
/frontend-guru https://example.com
```

Claude will ask you questions about format, then run the transformation.

---

### For Web Interface Users

**Coming soon** - Will be deployed to: https://g2-frontend-guru.vercel.app

---

## 📁 Project Structure

```
src/
├── core/              # Shared logic (used by both MCP and web)
│   ├── agents/        # Agent prompts (orchestrator, analyzer, planner, etc.)
│   ├── orchestrator/  # Transformation workflow
│   └── exports/       # Output format handlers
├── mcp/               # MCP server (Claude Code)
└── web/               # Web interface (Next.js) - TODO
```

---

## 🔧 Development

**Run MCP server in dev mode:**
```bash
npm run dev:mcp
```

**Build everything:**
```bash
npm run build
```

---

## 📝 Next Steps (TODO)

- [ ] Complete web interface (Next.js app in `src/web/`)
- [ ] Deploy web interface to Vercel
- [ ] Implement actual agent workflow integration (currently returns mock data)
- [ ] Add export handlers (ZIP, preview URL, clipboard)
- [ ] Add progress tracking for long builds
- [ ] Add build history/listing

---

## 🎓 How It Works

1. **User provides input** (URL, screenshot, or description)
2. **Analyzer agent** identifies all sections in the design
3. **Planner agent** creates optimal build plan
4. **Builder agent** transforms design to React code (with design system rules)
5. **Validator agent** checks completeness and compliance
6. **Refiner agent** fixes any design system violations
7. **Export** in requested format (React, ZIP, preview, clipboard)

All agents follow the "transformation mindset" - adapting designs to match Elevate 2.0 standards, not just copying them.

---

## 📚 Documentation

- **Agents**: See `src/core/agents/` for all agent prompts
- **Design System Rules**: See `src/core/agents/frontend-guardian.md` for all 41 rules
- **Orchestrator**: See `src/core/agents/orchestrator.md` for workflow

---

## 🆘 Troubleshooting

**MCP server not showing up in Claude:**
1. Check config file path is correct
2. Verify file has valid JSON (no trailing commas)
3. Restart Claude completely
4. Check logs: MCP server logs to stderr

**Build fails:**
- Ensure all agents are present in `src/core/agents/`
- Check that Node.js version is 18+ (`node --version`)

---

## 📄 License

Private - G2 internal use only