GitHubDevCard MCPAgent

🃏 GitHub Dev Card Generator

Generate beautiful, AI-powered developer cards from any public GitHub profile. Stack: FastAPI · Google ADK · Gemini 2.5 Flash · FastMCP · React/HTML Frontend · Cloud Run

---

✨ Features

• 🔍 GitHub scraper — fetches profile, repos, languages via GitHub REST API
• 🧠 AI analysis — Gemini 2.5 Flash generates a developer vibe, top skills, and fun facts
• 🎨 5 card themes — hacker, builder, researcher, designer, open-source-hero
• 💾 Persistent cards — saved HTML cards with shareable URLs
• 🤖 ADK agent — full orchestration via Google Agent Development Kit (optional)
• ☁️ Cloud Run ready — one-command deployment

---

🚀 Quick Start (Local)

1. Prerequisites

• Python 3.12+
• A Gemini API key → Get one free
• (Optional) GitHub token for higher rate limits

2. Set up environment

cd github-card-generator
cp .env.example .env
# Edit .env and add your GEMINI_API_KEY

3. Install dependencies & run backend

cd backend

# Option A: pip
pip install -r requirements.txt
uvicorn main:app --reload --port 8080

# Option B: uv
uv venv && .venv/Scripts/activate   # Windows
# or: source .venv/bin/activate     # Mac/Linux
uv pip install -r requirements.txt
uvicorn main:app --reload --port 8080

4. Open the frontend

Just open frontend/index.html in your browser — or serve it:

cd frontend
python -m http.server 3000
# Visit http://localhost:3000

The frontend auto-connects to http://localhost:8080.

---

🐳 Docker Compose (recommended)

# Copy and fill in your keys
cp .env.example .env

# Start both services
docker-compose up --build

# Frontend: http://localhost:3000
# Backend:  http://localhost:8080
# API docs: http://localhost:8080/docs

---

🌐 API Endpoints

| Method | Path | Description | |--------|------|-------------| | POST | /generate | Generate a dev card {"username": "torvalds"} | | GET | /card/{username} | Serve a saved card as HTML | | GET | /cards | List all generated cards | | GET | /health | Health check | | GET | /docs | OpenAPI / Swagger UI |

Example

curl -X POST http://localhost:8080/generate \
  -H "Content-Type: application/json" \
  -d '{"username": "torvalds"}'

---

☁️ Deploy to Google Cloud Run

chmod +x deploy.sh
./deploy.sh YOUR_GCP_PROJECT_ID YOUR_GEMINI_API_KEY

Or set env vars first:

export GOOGLE_CLOUD_PROJECT=my-project
export GEMINI_API_KEY=AIza...
./deploy.sh

---

🧠 Architecture

User
 │
 ▼
frontend/index.html
 │  POST /generate
 ▼
backend/main.py  (FastAPI)
 │
 ├── Direct mode: calls MCP tools directly
 │    └── mcp_server.py
 │         ├── scrape_github()    → GitHub REST API
 │         ├── analyze_profile()  → Gemini 2.5 Flash
 │         ├── generate_card_html()
 │         └── save_card()
 │
 └── ADK mode (if google-adk installed):
      └── agent.py (github_card_agent)
           └── MCPToolset → mcp_server.py (stdio)

---

🎨 Card Themes

| Theme | Style | Triggered by | |-------|-------|--------------| | hacker | Dark, green terminal | Systems/security/kernel work | | builder | Clean light/blue | Full-stack/web/product builders | | researcher | Dark navy/red | ML/AI/data science/academic | | designer | Light purple/pastel | UI/UX/creative/frontend | | open-source-hero | Dark, amber/gold | Massive OSS contributions |

---

🔑 Environment Variables

| Variable | Required | Description | |----------|----------|-------------| | GEMINI_API_KEY | ✅ Yes | Gemini API key for AI analysis | | GITHUB_TOKEN | Optional | PAT for 5000 req/hr (vs 60) | | GOOGLE_CLOUD_PROJECT | Cloud only | GCP project ID | | AGENT_ENGINE_ID | Optional | Vertex AI memory bank ID |

---

🧩 Adding Google ADK (optional)

The backend works without ADK in direct mode. To enable full agent orchestration:

pip install google-adk google-genai

The app auto-detects ADK and switches to agent mode.

---

📁 Project Structure

github-card-generator/
├── backend/
│   ├── mcp_server.py      # 4 MCP tools (scrape, analyze, generate, save)
│   ├── agent.py           # ADK agent definition
│   ├── main.py            # FastAPI app (direct + ADK modes)
│   ├── deploy_memory.py   # Vertex AI memory bank setup
│   ├── requirements.txt
│   ├── Dockerfile
│   └── static/
│       └── cards/         # Generated HTML cards saved here
├── frontend/
│   ├── index.html         # Single-page UI
│   └── Dockerfile
├── docker-compose.yml
├── deploy.sh
├── .env.example
└── README.md

---

🌍 Live Services

| Service | URL | |---------|-----| | Frontend | Open App | | Backend | Backend API | | API Docs | Swagger Docs | | Health Check | Health Endpoint |

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: HARIHARANS24
• Source: HARIHARANS24/GitHubDevCard-MCPAgent
• License: MIT
• Homepage: https://github-card-frontend-833959947283.us-central1.run.app/

Install and usage instructions live in the source repository linked above.