hr-edge-recruit-mcp-server 0.1.0

A custom MCP server using FastAPI, AWS, Firebase, and LangChain for real-time audio analysis.

AI RecruitEdge MCP Server

A comprehensive AI-powered recruitment workflow automation server that generates interview questions, analyzes media files, and provides candidate scoring.

Features

• Question Generation: AI-powered interview question generation based on job descriptions and resumes
• Media Analysis: Audio/video transcription and analysis for candidate evaluation
• Candidate Scoring: Comprehensive scoring system with technical, communication, and emotional intelligence assessment
• Database Integration: Full Firebase Firestore support for storing questions, analyses, and scores
• File Management: Complete file upload, validation, and storage system
• Configuration Management: Centralized configuration with environment variables
• Health Monitoring: Comprehensive health checks for all services

Architecture

Services

1. DatabaseService: Handles all database operations using Firebase Firestore
2. ConfigService: Manages application configuration and environment variables
3. FileService: Handles file uploads, validation, and storage
4. AWSServices: Manages AWS services (S3, Bedrock, Transcribe, Rekognition)
5. PineconeService: Manages vector store operations for similarity search

Agents

1. QuestionGeneratorAgent: Generates interview questions using LLM
2. MediaAnalyzerAgent: Analyzes audio/video files for candidate evaluation
3. ScoringAgent: Provides comprehensive candidate scoring

Required Services & Infrastructure

1. AWS Services

Amazon Bedrock

• Purpose: LLM inference for question generation, media analysis, and scoring
• Models Required:
  • anthropic.claude-3-sonnet-20240229-v1:0 (default)
  • amazon.titan-embed-text-v1 (embeddings)
• Setup: Enable Bedrock access in AWS console, configure IAM permissions

Amazon S3

• Purpose: Media file storage and transcription output
• Bucket: ai-recruitedge-media (configurable)
• Permissions: Read/Write access for media files and transcriptions
• CORS: Configure for web uploads

Amazon Transcribe

• Purpose: Audio/video transcription for media analysis
• Features: Real-time and batch transcription
• Languages: English (en-US) by default
• Output: JSON format to S3

Amazon Rekognition

• Purpose: Emotion analysis in video files
• Features: Face detection and emotion analysis
• Permissions: Access to S3 bucket for video analysis

AWS IAM Configuration

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "bedrock:InvokeModel",
                "bedrock:ListFoundationModels"
            ],
            "Resource": "*"
        },
        {
            "Effect": "Allow",
            "Action": [
                "s3:GetObject",
                "s3:PutObject",
                "s3:DeleteObject",
                "s3:ListBucket"
            ],
            "Resource": [
                "arn:aws:s3:::ai-recruitedge-media",
                "arn:aws:s3:::ai-recruitedge-media/*"
            ]
        },
        {
            "Effect": "Allow",
            "Action": [
                "transcribe:StartTranscriptionJob",
                "transcribe:GetTranscriptionJob",
                "transcribe:ListTranscriptionJobs"
            ],
            "Resource": "*"
        },
        {
            "Effect": "Allow",
            "Action": [
                "rekognition:DetectFaces",
                "rekognition:DetectLabels"
            ],
            "Resource": "*"
        }
    ]
}

2. Database Services

Firebase Firestore (Production)

• Purpose: NoSQL database for all application data
• Collections: questions, media_analyses, candidate_scores, interview_sessions
• Features: Real-time updates, automatic scaling, offline support
• Security: Row-level security rules
• Backup: Automated daily backups

Firebase Emulator (Development)

• Purpose: Local development database
• Setup: Firebase emulator suite
• Features: Local testing without Firebase costs

3. Vector Database

Pinecone

• Purpose: Vector similarity search for question context
• Index: recruitedge-questions (configurable)
• Dimensions: 1536 (Titan embedding dimension)
• Metric: Cosine similarity
• Environment: Production environment

4. File Storage

Local Storage

• Upload Directory: ./uploads (configurable)
• Temp Directory: ./temp (configurable)
• Permissions: Read/Write access
• Cleanup: Automated cleanup of old files

S3 Storage (Production)

• Bucket: ai-recruitedge-media
• CORS Configuration:

{
    "CORSRules": [
        {
            "AllowedHeaders": ["*"],
            "AllowedMethods": ["GET", "POST", "PUT", "DELETE"],
            "AllowedOrigins": ["*"],
            "ExposeHeaders": []
        }
    ]
}

5. Application Infrastructure

Web Server

• Framework: FastAPI with Uvicorn
• Port: 8000 (configurable)
• Host: 0.0.0.0 (configurable)
• SSL: HTTPS in production

Load Balancer (Production)

• Type: Application Load Balancer (AWS ALB)
• Health Checks: /health endpoint
• SSL Termination: Configure SSL certificate
• Auto Scaling: Based on CPU/memory usage

Monitoring & Logging

• Application Logs: Structured JSON logging
• Metrics: Prometheus metrics endpoint
• Health Checks: Comprehensive service health monitoring
• Alerting: CloudWatch alarms for critical metrics

Installation & Setup

1. Prerequisites

System Requirements

• Python: 3.9+
• Memory: 4GB+ RAM
• Storage: 50GB+ for media files
• CPU: 2+ cores recommended

Operating System

• Linux: Ubuntu 20.04+ (recommended)
• Windows: Windows 10+ (development)
• macOS: 10.15+ (development)

2. Environment Setup

Create Virtual Environment

python -m venv venv
source venv/bin/activate  # Linux/macOS
# or
venv\Scripts\activate  # Windows

Install Dependencies

pip install -r requirements.txt

3. AWS Setup

Install AWS CLI

# Linux
curl "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip" -o "awscliv2.zip"
unzip awscliv2.zip
sudo ./aws/install

# macOS
brew install awscli

# Windows
# Download from AWS website

Configure AWS Credentials

aws configure
# Enter your AWS Access Key ID
# Enter your AWS Secret Access Key
# Enter your default region (e.g., us-east-1)

Create S3 Bucket

aws s3 mb s3://ai-recruitedge-media
aws s3api put-bucket-cors --bucket ai-recruitedge-media --cors-configuration file://cors.json

4. Firebase Setup

Create Firebase Project

1. Go to Firebase Console
2. Create a new project or select existing project
3. Enable Firestore Database
4. Set up security rules

Install Firebase CLI

# Install Firebase CLI
npm install -g firebase-tools

# Login to Firebase
firebase login

# Initialize Firebase in your project
firebase init firestore

Configure Firebase Credentials

# Download service account key
# Go to Firebase Console > Project Settings > Service Accounts
# Click "Generate new private key"
# Save the JSON file securely

Firestore Security Rules

rules_version = '2';
service cloud.firestore {
  match /databases/{database}/documents {
    // Questions collection
    match /questions/{questionId} {
      allow read, write: if request.auth != null;
    }
    
    // Media analyses collection
    match /media_analyses/{analysisId} {
      allow read, write: if request.auth != null;
    }
    
    // Candidate scores collection
    match /candidate_scores/{scoreId} {
      allow read, write: if request.auth != null;
    }
    
    // Interview sessions collection
    match /interview_sessions/{sessionId} {
      allow read, write: if request.auth != null;
    }
  }
}

5. Pinecone Setup

Create Pinecone Account

1. Sign up at pinecone.io
2. Get API key and environment details
3. Create index:

import pinecone
pinecone.init(api_key="your-api-key", environment="your-environment")
pinecone.create_index("recruitedge-questions", dimension=1536, metric="cosine")

6. Environment Configuration

Create .env File

# AWS Configuration
AWS_REGION=us-east-1
AWS_ACCESS_KEY_ID=your_aws_access_key_id
AWS_SECRET_ACCESS_KEY=your_aws_secret_access_key

# Bedrock Configuration
BEDROCK_MODEL_ID=anthropic.claude-3-sonnet-20240229-v1:0

# S3 Configuration
S3_BUCKET_NAME=ai-recruitedge-media

# Pinecone Configuration
PINECONE_API_KEY=your_pinecone_api_key
PINECONE_ENVIRONMENT=your_pinecone_environment
PINECONE_INDEX_NAME=recruitedge-questions

# Firebase Configuration
FIREBASE_PROJECT_ID=your-firebase-project-id
FIREBASE_SERVICE_ACCOUNT_PATH=path/to/serviceAccountKey.json
FIREBASE_DATABASE_URL=https://your-project-id.firebaseio.com

# Application Configuration
APP_HOST=0.0.0.0
APP_PORT=8000
APP_DEBUG=false
LOG_LEVEL=INFO

# Security Configuration
CORS_ORIGINS=*
API_KEY_HEADER=X-API-Key
API_KEY=your_api_key_here

# Feature Flags
ENABLE_EMBEDDINGS=true
ENABLE_VECTOR_STORE=true
ENABLE_DATABASE=true

# Media Processing Configuration
MAX_FILE_SIZE=100
ALLOWED_MEDIA_TYPES=mp4,avi,mov,wav,mp3
TRANSCRIPTION_LANGUAGE=en-US
ANALYSIS_TIMEOUT=300

# Cleanup Configuration
CLEANUP_DAYS_OLD=30

# File Storage Configuration
UPLOAD_DIR=./uploads
TEMP_DIR=./temp

7. Application Startup

Development Mode

python main.py

Production Mode

# Using Gunicorn
pip install gunicorn
gunicorn main:app -w 4 -k uvicorn.workers.UvicornWorker --bind 0.0.0.0:8000

# Using systemd service (Linux)
sudo nano /etc/systemd/system/recruitedge.service

Systemd Service File

[Unit]
Description=AI RecruitEdge MCP Server
After=network.target

[Service]
Type=simple
User=recruitedge
WorkingDirectory=/opt/recruitedge
Environment=PATH=/opt/recruitedge/venv/bin
ExecStart=/opt/recruitedge/venv/bin/python main.py
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

Production Deployment

1. Direct Server Deployment

Server Setup

# Update system
sudo apt update && sudo apt upgrade -y

# Install Python and dependencies
sudo apt install python3.9 python3.9-venv python3.9-dev build-essential

# Create application user
sudo useradd -m -s /bin/bash recruitedge
sudo usermod -aG sudo recruitedge

# Switch to application user
sudo su - recruitedge

# Clone application
git clone https://github.com/your-repo/ai-recruitedge.git
cd ai-recruitedge

# Create virtual environment
python3.9 -m venv venv
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Create directories
mkdir -p uploads temp

# Set permissions
chmod 755 uploads temp

Environment Configuration

# Create environment file
nano .env
# Add all environment variables as shown above

# Set proper permissions
chmod 600 .env

# Create Firebase service account key
nano firebase-key.json
# Paste your Firebase service account key
chmod 600 firebase-key.json

Process Management

# Install PM2 for process management
npm install -g pm2

# Create PM2 ecosystem file
nano ecosystem.config.js

PM2 Configuration

module.exports = {
  apps: [{
    name: 'recruitedge',
    script: 'main.py',
    interpreter: './venv/bin/python',
    cwd: '/opt/recruitedge',
    instances: 'max',
    exec_mode: 'cluster',
    env: {
      NODE_ENV: 'production'
    },
    error_file: './logs/err.log',
    out_file: './logs/out.log',
    log_file: './logs/combined.log',
    time: true
  }]
};

Start Application

# Start with PM2
pm2 start ecosystem.config.js

# Save PM2 configuration
pm2 save

# Setup PM2 to start on boot
pm2 startup

2. Nginx Configuration

Install Nginx

sudo apt install nginx

Configure Nginx

sudo nano /etc/nginx/sites-available/recruitedge

Nginx Configuration

server {
    listen 80;
    server_name your-domain.com;
    
    location / {
        proxy_pass http://localhost:8000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
    
    location /uploads {
        alias /opt/recruitedge/uploads;
        expires 30d;
        add_header Cache-Control "public, immutable";
    }
}

Enable Site

sudo ln -s /etc/nginx/sites-available/recruitedge /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl restart nginx

3. SSL Configuration

Install Certbot

sudo apt install certbot python3-certbot-nginx

Obtain SSL Certificate

sudo certbot --nginx -d your-domain.com

4. Monitoring & Observability

CloudWatch Configuration

# CloudWatch Logs
- logGroupName: /aws/recruitedge/application
  logStreamName: recruitedge-logs
  retentionInDays: 30

# CloudWatch Metrics
- metricName: RequestCount
  namespace: RecruitEdge
  dimensions:
    - Service: recruitedge
    - Environment: production

# CloudWatch Alarms
- alarmName: recruitedge-high-error-rate
  metricName: ErrorCount
  threshold: 10
  period: 300
  evaluationPeriods: 2

Prometheus Metrics

# Add to main.py
from prometheus_client import Counter, Histogram, generate_latest

# Metrics
REQUEST_COUNT = Counter('http_requests_total', 'Total HTTP requests', ['method', 'endpoint'])
REQUEST_DURATION = Histogram('http_request_duration_seconds', 'HTTP request duration')

@app.middleware("http")
async def prometheus_middleware(request, call_next):
    start_time = time.time()
    response = await call_next(request)
    duration = time.time() - start_time
    
    REQUEST_COUNT.labels(method=request.method, endpoint=request.url.path).inc()
    REQUEST_DURATION.observe(duration)
    
    return response

@app.get("/metrics")
async def metrics():
    return Response(generate_latest(), media_type="text/plain")

5. Security Configuration

SSL/TLS Setup

# Generate SSL certificate
openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -days 365 -nodes

# Configure Nginx
server {
    listen 443 ssl;
    server_name your-domain.com;
    
    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;
    
    location / {
        proxy_pass http://localhost:8000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

API Key Authentication

# Add to main.py
from fastapi import Security, HTTPException
from fastapi.security import HTTPBearer

security = HTTPBearer()

async def verify_api_key(api_key: str = Security(security)):
    if api_key != config_service.api_key:
        raise HTTPException(status_code=401, detail="Invalid API key")
    return api_key

@app.post("/generate-questions")
async def generate_questions(
    request: QuestionGenerationRequest,
    api_key: str = Depends(verify_api_key)
):
    # Implementation

Backup & Recovery

1. Firebase Backup

# Export Firestore data
gcloud firestore export gs://your-backup-bucket/recruitedge-backup/$(date +%Y%m%d)

# Automated backup script
#!/bin/bash
BACKUP_BUCKET="your-backup-bucket"
DATE=$(date +%Y%m%d_%H%M%S)
gcloud firestore export gs://$BACKUP_BUCKET/recruitedge-backup/$DATE

2. File Backup

# S3 backup
aws s3 sync s3://ai-recruitedge-media s3://ai-recruitedge-backup/$(date +%Y%m%d)

# Local file backup
tar -czf uploads_backup_$(date +%Y%m%d).tar.gz uploads/

3. Configuration Backup

# Backup environment files
cp .env .env.backup.$(date +%Y%m%d)

Troubleshooting

Common Issues

1. AWS Credentials

# Check AWS credentials
aws sts get-caller-identity

# Verify Bedrock access
aws bedrock list-foundation-models

2. Firebase Connection

# Test Firebase connection
import firebase_admin
from firebase_admin import firestore

# Initialize Firebase
firebase_admin.initialize_app()
db = firestore.client()

# Test write operation
doc_ref = db.collection('test').document('test-doc')
doc_ref.set({'test': 'data'})
print("Firebase connection successful")

3. Pinecone Connection

# Test Pinecone connection
import pinecone
pinecone.init(api_key="your-key", environment="your-env")
print(pinecone.list_indexes())

4. File Permissions

# Fix upload directory permissions
chmod 755 uploads/
chmod 755 temp/

5. Memory Issues

# Monitor memory usage
htop
free -h

# Increase swap if needed
sudo fallocate -l 2G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile

Performance Optimization

1. Firebase Optimization

# Use batch operations for multiple writes
batch = db.batch()
for i in range(100):
    doc_ref = db.collection('questions').document()
    batch.set(doc_ref, {'data': f'item_{i}'})
batch.commit()

# Use indexes for complex queries
# Create composite indexes in Firebase Console

2. Application Optimization

# Connection pooling for Firebase
# Firebase handles this automatically

# Caching with Redis
import redis
from functools import wraps

redis_client = redis.Redis(host='localhost', port=6379, db=0)

def cache_result(expire_time=3600):
    def decorator(func):
        @wraps(func)
        async def wrapper(*args, **kwargs):
            cache_key = f"{func.__name__}:{hash(str(args) + str(kwargs))}"
            cached_result = redis_client.get(cache_key)
            if cached_result:
                return json.loads(cached_result)
            
            result = await func(*args, **kwargs)
            redis_client.setex(cache_key, expire_time, json.dumps(result))
            return result
        return wrapper
    return decorator

License

This project is licensed under the MIT License.