cv-mcp-server

ariafarmani/cv-mcp-server

3.1

If you are the rightful owner of cv-mcp-server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

The CV MCP Server is a cutting-edge Model Context Protocol server designed to revolutionize CV processing by providing a conversational, recruiter-like experience.

Tools
5
Resources
0
Prompts
0

🎯 CV MCP Server - Conversational Recruitment Assistant

A revolutionary Model Context Protocol (MCP) server that transforms CV processing into a conversational, recruiter-like experience. Built with advanced natural language parsing, intelligent candidate matching, and intuitive tools that recruiters actually want to use.

✨ What Makes This Special?

🗣️ Speaks Like a Real Recruiter - No more technical JSON responses
🧠 Understands Natural Language - "Find senior Java developers" just works
⚖️ Smart Candidate Comparisons - Side-by-side analysis with professional recommendations
🎯 Intuitive Tools - Built for how recruiters actually think and work
😅 Encouraging Error Handling - Helpful suggestions, not technical errors

🚀 Quick Demo

# Instead of complex JSON queries...
Query: "senior java developers in Netherlands"

# Get recruiter-style responses! 
🎯 **Found 3 candidates for: 'senior java developers in Netherlands'**

Excellent! I've found some strong candidates that could be perfect for this role:

**1. Sarah van der Berg** ⭐ (Senior - 6 years)
   📊 **85% match** • 🏛️ Amsterdam
   💼 Currently: Senior Java Developer at ING Bank
   🔧 Key skills: Java ⭐, Spring Boot ⭐, Microservices 💪

💡 **Next steps:** Try `show candidate 1` or `compare candidates 1, 2, 3`

🛠️ Intuitive Recruiter Tools

🔍 Natural Language Candidate Search

"find senior java developers"
"python programmers with 3+ years experience"  
"experienced angular developers"
"fullstack engineers with react and node.js"
"devops engineer with docker and kubernetes"

⚖️ Smart Candidate Comparisons

"compare candidates 1, 2, 3"
"compare Sarah vs John"
"side by side of my top 3"

Get: Skills matrix • Experience analysis • Professional recommendations • Next steps

📊 Complete Database Overview

"show me all candidates"
"database stats"
"what candidates do I have?"

Get: Experience breakdown • Tech stack distribution • Location insights • Top candidates spotlight

👤 Rich Candidate Profiles

"show candidate 1"
"profile of Sarah van der Berg"
"details for candidate 5"

Get: Professional summary • Current role • Key achievements • Contact info • Next steps

🔄 Conversational Database Management

"refresh database"
"process new CVs"
"update candidates"

Get: Progress updates • File processing status • Helpful next steps

📋 Requirements & Installation

Prerequisites

  • Python 3.8+
  • Virtual environment (recommended)
  • PDF files containing Dutch/English CVs

Quick Setup

# 1. Clone and setup
git clone <repository-url>
cd cv-mcp-server
python3 -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

# 2. Install dependencies
pip install -r requirements.txt

# 3. Initialize database
python -c "from src.database import init_database; init_database()"

# 4. Add CV files
mkdir -p data/pdfs
# Copy your PDF files to data/pdfs/

# 5. Process CVs and start
python process_cvs.py
python src/mcp_server.py

🎬 Try It Live

Test the Conversational Interface

# Quick demo of all tools
python test_intuitive_tools.py --quick

# Full test suite with examples  
python test_intuitive_tools.py

# Test query parsing with 34+ scenarios
python test_query_parsing.py

# See transformation demo (before/after)
python demo_recruiter_experience.py

🧠 Advanced Natural Language Processing

Smart Query Understanding

The system automatically extracts and understands:

🔧 Technology Skills

  • java → Java, Spring, Spring Boot, JVM, Maven
  • javascript → JS, Node.js, TypeScript, React, Angular
  • python → Django, Flask, Pandas, NumPy
  • devops → Docker, Kubernetes, AWS, CI/CD

📈 Experience Levels

  • "senior" → 5+ years experience, senior level
  • "5+ years" → 5 years experience
  • "junior" → 1 year, junior level
  • "lead" → 7+ years, leadership level

🌍 Location Awareness

  • "Netherlands", "Dutch", "NL" → Netherlands
  • "Amsterdam" → Amsterdam with 🏛️ emoji
  • "Rotterdam" → Rotterdam with 🚢 emoji

Query Examples That Just Work

✅ "senior fullstack developers in Amsterdam with 7+ years"
✅ "java developers netherlands 5+ years experience"  
✅ "junior react developers in Rotterdam"
✅ "python data scientists senior level"
✅ "DevOps engineers with kubernetes experience"
✅ "lead java architects Netherlands"

📊 Project Structure

cv-mcp-server/
├── src/                              # Core implementation
│   ├── mcp_server.py                # Main MCP server with 7 intuitive tools
│   ├── database.py                  # SQLite operations & schema
│   ├── cv_parser.py                 # Advanced PDF text extraction
│   ├── matcher.py                   # Intelligent candidate matching
│   ├── mock_candidates.py           # Realistic test candidate database
│   └── models.py                    # Data structures
├── data/                             # Data directory  
│   ├── pdfs/                        # CV PDF files
│   ├── cv_database.db               # SQLite database
│   └── processed_files.json         # Processing log
├── test_*.py                         # Comprehensive test suite
├── demo_*.py                         # Interactive demonstrations
├── *_SUMMARY.md                     # Feature documentation
└── requirements.txt                 # Dependencies

🌟 Key Features Deep Dive

🎯 Conversational Recruiter Experience

  • Responses feel like talking to a professional recruiter
  • Encouraging language instead of technical errors
  • Visual candidate presentation with emojis and formatting
  • Professional context showing current roles and achievements

🧠 Advanced Natural Language Processing

  • 34+ test scenarios covering all query formats
  • Intelligent skill synonym detection with job title mapping
  • Flexible experience parsing (years, levels, ranges)
  • Location-aware with Dutch city recognition
  • Quality scoring and intelligent suggestions

⚖️ Smart Candidate Comparisons

  • Side-by-side skills analysis with proficiency stars
  • Experience level analysis with recommendations
  • Overall strength scoring for easy decision making
  • Professional hiring recommendations with clear rationale

📊 Complete Database Analytics

  • Experience level breakdown (Junior 🌟, Senior ⭐, Lead 🏆)
  • Technology stack distribution across candidate pool
  • Location insights with Dutch city emojis
  • Top candidates spotlight with key metrics

😅 Friendly Error Handling

🔍 **No exact matches found for: 'quantum computing specialists'**

Don't worry! Let me suggest some alternatives:

📉 **Try lowering experience requirements:**
   • `senior quantum developer`
   • `quantum computing with 5+ years`

🌟 **Popular searches that work:**
   • `java developer netherlands`
   • `python data scientist`

📈 Performance & Scalability

  • Processing Speed: ~0.4 seconds per PDF
  • Search Response: < 0.5s for complex queries
  • Memory Efficient: Single-file processing
  • Smart Caching: Skip unchanged files
  • Error Recovery: Individual failures don't stop processing

🧪 Comprehensive Testing

Test Coverage

# Core functionality tests
python test_mcp_server.py              # MCP server tools
python test_query_parsing.py           # 34+ query parsing scenarios
python test_intuitive_tools.py         # Full recruiter workflow

# Demonstrations  
python demo_recruiter_experience.py    # Before/after transformation
python demo_natural_language.py        # Natural language examples

# Processing pipeline
python process_cvs.py --test           # CV processing pipeline
python check_results.py               # Validation & quality checks

What's Tested

  • ✅ Natural language query parsing (34+ scenarios)
  • ✅ Conversational tool responses with examples
  • ✅ Skills synonym detection and job title mapping
  • ✅ Experience level parsing (years, seniority, ranges)
  • ✅ Location detection for Netherlands and Dutch cities
  • ✅ Candidate comparison with professional recommendations
  • ✅ Database analytics and insights generation
  • ✅ Error handling with encouraging suggestions
  • ✅ PDF processing pipeline with quality validation

🔧 Advanced Configuration

Environment Variables

export CV_DATABASE_PATH="custom/path/cv_database.db"
export PDF_DIRECTORY="custom/pdfs/"
export LOG_LEVEL="DEBUG"

Processing Options

# Limit processing for testing
python process_cvs.py --limit 5

# Force reprocess all files  
python process_cvs.py --force

# Test mode (2-3 files only)
python process_cvs.py --test

🏗️ Built With Advanced Tech Stack

  • MCP (Model Context Protocol) - Modern AI integration standard
  • Advanced NLP - Regex patterns with intelligent parsing
  • SQLite - Efficient local database with comprehensive schema
  • PDF Processing - Robust text extraction with error handling
  • Fuzzy Matching - Intelligent candidate scoring algorithms
  • Dutch/English Support - Bilingual CV processing capabilities

🎯 Perfect For

  • Recruitment Agencies - Streamline candidate search and comparison
  • HR Departments - Efficient CV processing and candidate analytics
  • Startups - Quick talent assessment and hiring decisions
  • Consultants - Professional candidate presentation and reporting
  • Anyone - Processing Dutch/English CVs with intelligent matching

🚀 Production Ready

✅ Robust Error Handling - Graceful failures with helpful suggestions
✅ Comprehensive Logging - Detailed processing and parsing logs
✅ Performance Optimized - Efficient file processing and database operations
✅ Quality Validated - Extensive test coverage and validation checks
✅ User Friendly - Intuitive tools that feel natural to use
✅ Well Documented - Complete setup instructions and examples

📞 Support & Contributing

Getting Help

  • Check comprehensive test outputs for examples
  • Review detailed documentation files (*.md)
  • Use debug scripts for specific parsing issues
  • Check processing logs for troubleshooting

Contributing

  1. Fork the repository
  2. Create feature branch (git checkout -b feature/amazing-feature)
  3. Add tests for new functionality
  4. Commit changes (git commit -m 'Add amazing feature')
  5. Push to branch (git push origin feature/amazing-feature)
  6. Open Pull Request

🎉 Ready to Transform Your Recruitment Process!

🎯 From technical database queries → Conversational recruiter experience
🧠 From complex JSON → Natural language that just works
⚖️ From basic search → Professional candidate comparisons
😅 From technical errors → Encouraging, helpful guidance

Get Started Now:

git clone <repository-url>
cd cv-mcp-server && python3 -m venv venv && source venv/bin/activate
pip install -r requirements.txt && python test_intuitive_tools.py --quick

Your intelligent recruitment assistant is ready! 🚀

Built with ❤️ for modern recruitment workflows