GitHub Dev Card Generator

A powerful web application built with Google ADK, FastMCP, and Gemini 2.5 Flash that takes a GitHub username, scrapes their public data, analyzes their coding personality, and generates a beautiful, shareable Dev Card.

Tech Stack

• Backend: FastAPI (Python), uv package manager
• Agent Orchestration: Google ADK
• Tooling/Integration: MCP (FastMCP)
• LLM: Gemini 2.5 Flash
• Frontend: HTML/JS, Tailwind CSS (Single-page UI)
• Deployment: Google Cloud Run (Docker)

The Prompts Used to Build This App

This entire application was generated step-by-step by executing the following sequence of commands/prompts:

1. Project Setup:

   "Create a complete project scaffold for a GitHub Dev Card Generator with this folder structure... Create all files with the correct boilerplate — empty functions are fine, just get the imports and structure right. Use uv for Python deps."

2. MCP Tool Implementation:

   "In backend/mcp_server.py, implement a FastMCP server with exactly these 4 tools: scrape_github, analyze_profile, generate_card_html, save_card. Run the server with: uv run python mcp_server.py"

3. End-to-End Testing:

   "Connect to my local MCP server and test it end to end. Run these steps in sequence: Call scrape_github with username 'torvalds', pass that result into analyze_profile, generate an HTML card... Tell me if any tool fails."

4. ADK Agent Orchestration:

   "In backend/agent.py, create an ADK Agent called 'github_card_agent' using Gemini 2.5 Flash. Connect it to the MCP server at backend/mcp_server.py using McpToolset with stdio transport. System instruction: You are a GitHub profile analyst and dev card generator..."

5. FastAPI Backend:

   "In backend/main.py, create a FastAPI app that: Imports github_card_agent, Sets up InMemorySessionService, Creates a Runner, Exposes POST /generate endpoint... Exposes GET /card/{username}... Exposes GET /health... Add CORS middleware."

6. Frontend UI:

   "Create frontend/index.html as a single self-contained file (no build step, no npm) with this UI: Dark background (#0d1117), Centered layout, Big heading, Subheading, Input field + 'Generate Card' button. Loading state: pulsing skeleton... Result area... Share button... Make it look genuinely polished."

7. Dockerization:

   "Write Dockerfiles for both services. backend/Dockerfile: python:3.12-slim, uv... frontend/Dockerfile: nginx:alpine, Replace the hardcoded localhost:8080 backend URL with an environment variable BACKEND_URL using envsubst... Also write docker-compose.yml"

8. Google Cloud Run Deployment:

   "Deploy two Cloud Run services to Google Cloud for my GitHub Dev Card Generator project: Service 1 — backend (Port 8080, Memory 512Mi, allow unauth). Service 2 — frontend (Port 80, env var BACKEND_URL, Memory 256Mi). Deploy backend first, get its URL, then deploy frontend..."

Running Locally

1. Setup your .env file in the root directory:

   GEMINI_API_KEY=your_gemini_api_key_here
   GITHUB_TOKEN=your_github_token_here

2. Start the services using Docker Compose:

   docker-compose up --build

3. Open http://localhost:3000 in your browser.