<p align="center">
  <img src="https://img.shields.io/badge/MCP-Server-blueviolet?style=for-the-badge&logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAyNCAyNCI+PHBhdGggZmlsbD0id2hpdGUiIGQ9Ik0xMiAyQzYuNDggMiAyIDYuNDggMiAxMnM0LjQ4IDEwIDEwIDEwIDEwLTQuNDggMTAtMTBTMTcuNTIgMiAxMiAyem0wIDE4Yy00LjQxIDAtOC0zLjU5LTgtOHMzLjU5LTggOC04IDggMy41OSA4IDgtMy41OSA4LTggOHoiLz48L3N2Zz4=" alt="MCP Server">
  <img src="https://img.shields.io/badge/Gemini_2.5-Flash%20%7C%20Pro-4285F4?style=for-the-badge&logo=google&logoColor=white" alt="Gemini">
  <img src="https://img.shields.io/badge/Groq-Fallback-F55036?style=for-the-badge&logo=groq&logoColor=white" alt="Groq">
  <img src="https://img.shields.io/badge/Python-3.10+-3776AB?style=for-the-badge&logo=python&logoColor=white" alt="Python">
</p>

<h1 align="center">💎 gem-mcp</h1>

<p align="center">
  <strong>Flash-Fabric Architecture</strong> — An autonomous MCP server for AI-powered software generation
</p>

<p align="center">
  <a href="#-features">Features</a> •
  <a href="#-quick-start">Quick Start</a> •
  <a href="#-configuration">Configuration</a> •
  <a href="#-tools">Tools</a> •
  <a href="#-architecture">Architecture</a>
</p>

---

## ✨ Features

| Feature | Description |
|---------|-------------|
| 🧠 **Dual-Engine Strategy** | Uses Gemini 2.5 Pro for reasoning and Flash for high-speed generation |
| 🔄 **API Key Rotation** | Multiple Gemini keys with random load balancing to avoid rate limits |
| 🔁 **Groq Fallback** | Automatic fallback to Groq when Gemini quota is exceeded |
| 👁️ **Visual Inspector** | Multimodal UI validation with Playwright + Gemini Vision (OCR fallback) |
| 🛡️ **QA Sentinel** | Auto-healing test execution with smart diagnostics |
| ⚡ **Lazy Loading** | Sub-5 second startup time |

---

## 🚀 Quick Start

### Prerequisites

- Python 3.10+
- [Claude Code CLI](https://docs.anthropic.com/claude-code)
- Google Gemini API Key ([Get one here](https://aistudio.google.com/apikey))

### Installation

```bash
# Clone the repository
git clone https://github.com/riccardosecchi/gem-mcp.git
cd gem-mcp

# Create virtual environment
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Install Playwright browsers (for visual inspection)
playwright install chromium
```

### Environment Setup

```bash
# Copy the example env file
cp .env.example .env

# Edit with your API keys
nano .env
```

**Required keys in `.env`:**

```ini
# Single Gemini key
GEMINI_API_KEY=your_key_here

# OR multiple keys for rotation (recommended)
GEMINI_API_KEYS=key1,key2,key3,key4

# Groq fallback (optional but recommended)
GROQ_API_KEY=gsk_your_groq_key
```

---

## ⚙️ Configuration

### Connect to Claude Code

Add the server to your Claude Code global configuration:

```bash
# Edit ~/.claude.json
```

Add this configuration:

```json
{
  "mcpServers": {
    "gem-mcp": {
      "command": "/path/to/gem-mcp/venv/bin/python3",
      "args": [
        "/path/to/gem-mcp/server.py"
      ]
    }
  }
}
```

> 💡 **Tip:** Replace `/path/to/gem-mcp` with your actual installation path

### Verify Connection

```bash
# Start Claude Code
claude

# Inside Claude, check MCP servers
/mcp
```

You should see `gem-mcp` with a green checkmark ✓

---

## 🛠️ Tools

### `sequential_thinking`
Meta-cognitive buffer for complex reasoning. Enables 50-step planning before code generation.

```
Use: "Think through the requirements for building a todo app"
```

### `architect_blueprint`
Generates Clean Architecture JSON blueprints with folder structure and tech stack.

```
Use: "Create a blueprint for a Flutter expense tracker app"
```

### `scaffold_project`
Creates physical folder structure. Full Flutter support with all platforms.

```
Use: "Scaffold the project based on the blueprint"
```

### `intelligent_code_writer`
Flash-powered code generation with framework-specific linting rules.

```
Use: "Write the main.dart file with dependency injection setup"
```

### `visual_inspector`
Takes screenshots and validates UI against design expectations.

```
Use: "Check if the login page matches the design mockup"
```

### `qa_sentinel`
Executes tests with self-healing diagnostics.

```
Use: "Run pytest and fix any failures"
```

### `search_codebase`
Smart code search with context.

```
Use: "Find all usages of the UserRepository class"
```

---

## 🏛️ Architecture

```
┌─────────────────────────────────────────────────────────────┐
│                     Claude Code (LLM)                        │
└───────────────────────────┬─────────────────────────────────┘
                            │ MCP Protocol
                            ▼
┌─────────────────────────────────────────────────────────────┐
│                      gem-mcp Server                          │
├─────────────────────────────────────────────────────────────┤
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐  │
│  │  Architect  │  │ Fabricator  │  │   Visual Engine     │  │
│  │ (Pro Model) │  │(Flash Model)│  │ (Playwright+Flash)  │  │
│  └─────────────┘  └─────────────┘  └─────────────────────┘  │
├─────────────────────────────────────────────────────────────┤
│                    Tool Layer (8 Agents)                     │
│  • sequential_thinking    • intelligent_code_writer         │
│  • architect_blueprint    • visual_inspector                │
│  • scaffold_project       • qa_sentinel                     │
│  • search_codebase        • clear_thought_process           │
└─────────────────────────────────────────────────────────────┘
```

---

## 📁 Project Structure

```
gem-mcp/
├── server.py          # Main MCP server with all tools
├── requirements.txt   # Python dependencies
├── .env.example       # Environment template
├── CLAUDE.md          # Instructions for Claude
└── README.md          # This file
```

---

## 🔒 Security

- API keys are loaded from `.env` (never committed)
- Dangerous shell commands are blocked
- Test execution has timeout limits
- All external calls use async with proper error handling

---

## 📄 License

MIT © 2025

---

<p align="center">
  Made with 💎 by the Flash-Fabric Architecture
</p>