🎴 GitHub Dev Card Generator

An AI-powered web application that turns any public GitHub profile into a sleek, personalized developer card highlighting their technical strengths, top repositories, personality vibe, and custom themes.

Powered by Google Gemini, Google Agent Development Kit (ADK), Model Context Protocol (MCP), and FastAPI.

🚀 Live Demo

The application is deployed on Render and can be accessed live here:
👉 GitDev Live Demo

---

✨ Features

• Autonomous AI Agent: Built using Google ADK (LlmAgent) and Gemini 2.5 Flash to orchestrate tool calling and profiling.
• MCP Server Architecture: Modular Model Context Protocol tools for scraping GitHub profiles, analyzing skills with Gemini, rendering customized HTML, and saving card assets.
• 3-Tier Resilient Fallback:
  • Tier 1 (Agent): Full autonomous ADK multi-step agent.
  • Tier 2 (Direct AI): Direct pipeline execution with Gemini tools.
  • Tier 3 (Zero-AI Static): Rule-based fallback if AI API limits or network issues occur.
• Themed Cards: Dynamic developer aesthetics based on repo analysis:
  • 🟢 hacker
  • 🔵 builder
  • 🟣 researcher
  • 🌸 designer
  • 🟠 open-source-hero
• Modern UI: Clean dark-mode glassmorphic interface built with React and Tailwind CSS, featuring live preview and clipboard sharing.
• Multi-Deployment Ready: Configured for Render (render.yaml) and Vercel serverless (api/generate-card.js).

---

📁 Project Structure

github-card-generator/
├── api/
│   └── generate-card.js      # Vercel serverless function endpoint
├── backend/
│   ├── agent.py              # Google ADK agent configuration & orchestration
│   ├── main.py               # FastAPI application & API endpoints
│   ├── mcp_server.py         # FastMCP server with tools (scrape, analyze, render, save)
│   ├── test_mcp.py           # Test suite for MCP workflow
│   ├── requirements.txt      # Python dependencies
│   └── static/cards/         # Directory for generated HTML cards
├── frontend/
│   └── index.html            # React + Tailwind CSS client interface
├── render.yaml               # Cloud deployment specification for Render
├── .env.example              # Environment variables template
└── README.md                 # Project documentation

---

🛠️ Prerequisites

• Python 3.10+ (Tested with Python 3.13)
• Google Gemini API Key: Get one from Google AI Studio
• GitHub Personal Access Token (Optional): Generate one on GitHub to increase API rate limits.

---

🚀 Getting Started

1. Clone the Repository & Configure Environment

git clone <repo-url>
cd github-card-generator

Create a .env file in the root or backend/ directory:

GOOGLE_API_KEY=your_gemini_api_key_here
GITHUB_TOKEN=your_github_token_here

2. Set Up Python Virtual Environment

# Navigate to the backend directory
cd backend

# Create virtual environment
python -m venv venv

# Activate on Windows (PowerShell):
.\venv\Scripts\Activate.ps1

# Activate on macOS/Linux:
source venv/bin/activate

3. Install Dependencies

pip install -r requirements.txt

4. Run the Application

Start the FastAPI application with Uvicorn:

uvicorn main:app --reload --port 8000

Or run directly using Python:

python main.py

(Defaults to port 8080 or the PORT environment variable)

Open your browser and visit: 👉 http://localhost:8000

---

🧪 Testing & CLI Execution

Test MCP Tools Workflow Standalone

Run the end-to-end MCP pipeline without launching the web server:

python backend/test_mcp.py

Test ADK Agent in Terminal

Run the Google ADK autonomous agent workflow:

python backend/agent.py

---

🌐 Deployment

Render

This repository includes a render.yaml blueprint:

1. Connect your repository to Render.
2. Configure environment variables in the Render Dashboard:
   • GOOGLE_API_KEY
   • GITHUB_TOKEN
3. Live instance: https://gitdev-a688.onrender.com/

Vercel

Deploy the frontend and serverless function:

npm i -g vercel
vercel dev

---

📄 License

MIT License. Feel free to use, modify, and distribute.