Hackathon Recommender

Estimated reading: 2 minutes 60 views

AI Agents Hackathon Project Recommender

Discover your perfect hackathon project with AI-powered GitHub profile analysis

An intelligent system that analyzes GitHub profiles and generates personalized hackathon project recommendations using AI agents, Model Context Protocol (MCP), and real-time data integration.

Features

AI-Powered Analysis: Intelligent GitHub profile analysis using AI agents
Real-Time Data: Live integration with GitHub API through MCP servers
Personalized Recommendations: Tailored hackathon projects based on skills and interests
Secure Architecture: Containerized microservices with proper secrets management
Modern Stack: Next.js + Python + Docker + MCP integration
Production Ready: Scalable architecture with comprehensive tooling

Architecture

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Next.js UI    │───▶│  Python Agents  │───▶│   MCP Gateway   │
│   (Port 3003)   │    │   (Port 7777)   │    │   (Port 8811)   │
└─────────────────┘    └─────────────────┘    └─────────────────┘
         │                       │                       │
         │                       │                       ▼
         │                       │              ┌─────────────────┐
         │                       │              │  GitHub Tools   │
         │                       │              │  DuckDuckGo     │
         │                       │              │  Fetch Tools    │
         │                       │              │  (76 tools)     │
         │                       │              └─────────────────┘
         │                       ▼
         │              ┌─────────────────┐
         │              │   AI Models     │
         │              │   Qwen3 Small   │
         │              │   (Local/API)   │
         │              └─────────────────┘
         ▼
┌─────────────────┐
│     User        │
│   Browser       │
└─────────────────┘

Quick Start

Prerequisites

Docker & Docker Compose
GitHub Personal Access Token
8GB+ RAM (for local AI models)

1. Clone & Setup

git clone https://github.com/ajeetraina/ai-agents-hackathon-recommender
cd ai-agents-hackathon-recommender

2. Configure Secrets

Create a file .mcp.env and add your GitHub PAT

nano .mcp.env
github.personal_access_token=XXX

3. Launch the Application

# Build and start all services
docker compose up -d --build

# Monitor the logs
docker compose logs -f

4. Access the Application

Web Interface: http://localhost:3003
Agents API: http://localhost:7777
Health Check: http://localhost:7777/health

🎯 Usage

Open the web interface at http://localhost:3003
Enter any GitHub username (e.g., “microsoft”, “torvalds”, “ajeetraina”)
Click “Get Recommendations”
Receive personalized hackathon project suggestions!

🔧 Development

Local Development Setup

# Start in development mode
docker compose up --build

# Watch logs
docker compose logs -f agents-ui
docker compose logs -f agents

API Endpoints

Agents Service (Port 7777)

GET /health – Health check
POST /analyze – Analyze GitHub profile
GET /agents – List available agents

# Example API usage
curl -X POST http://localhost:7777/analyze \
  -H "Content-Type: application/json" \
  -d '{"username": "microsoft", "agent": "hackathon_recommender"}'

Hackathon Recommender

AI Agents Hackathon Project Recommender

Features

Architecture

Quick Start

Prerequisites

1. Clone & Setup

2. Configure Secrets

3. Launch the Application

4. Access the Application

🎯 Usage

🔧 Development

Local Development Setup

API Endpoints

Agents Service (Port 7777)

Leave a Reply Cancel reply

Hackathon Recommender