gem-mcp

<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
• Google Gemini API Key (Get one here)

Installation

# 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

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

# Edit with your API keys
nano .env

Required keys in .env:

# 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:

# Edit ~/.claude.json

Add this configuration:

{
  "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

# 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>