MCP 服务器

gem-mcp

An autonomous MCP server for AI-powered software generation using Gemini and Groq, with features like dual-engine strategy, visual inspection, and QA sentinel.

README

Flash-Fabric Architecture — An autonomous MCP server for AI-powered software generation

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

✨ 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