anmolvarshney77/MCP-Server

MCP Resume Server

A Model Context Protocol (MCP) server that provides resume analysis and email functionality through a REST API. The server parses PDF resumes, stores data in memory for natural language querying, and includes email sending capabilities via Gmail SMTP.

Table of Contents

• Features
• Prerequisites
• Installation
• Configuration
• Usage
• API Documentation
• Frontend Interface
• Project Structure
• Troubleshooting
• Contributing
• License

Features

• Resume Analysis: Parse PDF resumes and answer natural language questions about the content
• Email Functionality: Send emails through Gmail SMTP with full error handling
• Web Interface: Simple HTML frontend for testing both functionalities
• Fallback Data: Automatic placeholder data when PDF parsing fails
• Error Handling: Comprehensive error handling and logging throughout the application
• Health Monitoring: Built-in health check endpoint for monitoring server status

Prerequisites

Before you begin, ensure you have the following installed:

• Node.js: Version 14.0.0 or higher
• npm: Comes with Node.js installation
• Gmail Account: With 2-Factor Authentication enabled for App Password generation

Installation

1. Clone or download the project:

   git clone <repository-url>
   cd mcp-resume-server
   

2. Install dependencies:

   npm install
   

3. Add your resume file:

   • Place your resume PDF file in the project root directory
   • Name it Resume.pdf (case-sensitive)
   • If no resume is found, the server will use placeholder data

Configuration

Environment Variables

1. Copy the environment template:

   cp .env.example .env
   

2. Edit the .env file with your configuration:

   # Email Configuration
   EMAIL_USER=your-email@gmail.com
   EMAIL_PASS=your-app-specific-password
   
   # Server Configuration (optional)
   PORT=3000
   

Gmail App Password Setup

To use the email functionality, you need to create a Gmail App Password:

1. Enable 2-Factor Authentication on your Google Account:

   • Go to Google Account Security
   • Enable 2-Step Verification

2. Generate App Password:

   • Go to Security > App passwords
   • Select "Mail" and your device
   • Copy the generated 16-character password
   • Use this password in your .env file (not your regular Gmail password)

Usage

Starting the Server

1. Development mode:

   npm run dev
   

2. Production mode:

   npm start
   

3. Custom port:

   PORT=8080 npm start
   

Server Output

When the server starts successfully, you'll see:

🚀 MCP Resume Server starting...
📄 Loading resume data...
✅ Resume data loaded successfully
👤 Resume for: John Doe
💼 Experience entries: 2
🎓 Education entries: 1
🛠️  Skills count: 12

🎉 MCP Resume Server is now running!
==================================================
🌐 Frontend interface: http://localhost:3000/
💬 Resume chat endpoint: http://localhost:3000/api/chat
📧 Email endpoint: http://localhost:3000/api/send-email
🏥 Health check: http://localhost:3000/api/health
==================================================

API Documentation

Base URL

http://localhost:3000

Endpoints

1. Resume Chat

POST /api/chat

Ask natural language questions about the resume content.

Request Body:

{
  "question": "What is the most recent job position?"
}

Response (Success):

{
  "success": true,
  "answer": "My most recent position was Senior Software Developer at Tech Innovations Inc. (2021-2023). Led development of web applications using React and Node.js."
}

Response (Error):

{
  "success": false,
  "error": "Question parameter is required and must be a non-empty string",
  "code": "INVALID_QUESTION"
}

Example Questions:

• "What is your name?"
• "What are your technical skills?"
• "What is your most recent job?"
• "What is your educational background?"
• "Do you have experience with JavaScript?"

2. Send Email

POST /api/send-email

Send emails through the configured Gmail SMTP.

Request Body:

{
  "to": "recipient@example.com",
  "subject": "Test Email",
  "body": "This is a test message from MCP Resume Server."
}

Response (Success):

{
  "success": true,
  "message": "Email sent successfully"
}

Response (Error):

{
  "success": false,
  "error": "Invalid email credentials",
  "code": "AUTH_ERROR"
}

3. Health Check

GET /api/health

Check server status and resume loading status.

Response:

{
  "success": true,
  "message": "MCP Resume Server is running",
  "timestamp": "2024-01-15T10:30:00.000Z",
  "resumeLoaded": true,
  "uptime": 3600.5
}

4. Frontend Interface

GET /

Serves the HTML frontend interface for testing both functionalities.

Error Codes

Frontend Interface

The server includes a built-in web interface accessible at http://localhost:3000/.

Features:

• Resume Chat Section: Ask questions about the resume and view conversation history
• Email Testing Section: Send test emails with form validation
• Real-time Status: Loading indicators and success/error messages
• Responsive Design: Works on desktop and mobile devices

Usage:

1. Open http://localhost:3000/ in your browser
2. Use the left panel to ask resume questions
3. Use the right panel to send test emails
4. View responses and status messages in real-time

Project Structure

mcp-resume-server/
├── server.js              # Main Express server application
├── resumeParser.js        # Resume parsing and querying logic
├── index.html            # Frontend web interface
├── package.json          # Project dependencies and scripts
├── .env.example          # Environment variables template
├── .env                  # Your environment configuration (create this)
├── Resume.pdf            # Your resume file (add this)
└── README.md             # This documentation file

Key Components:

• server.js: Main application entry point with Express server setup, API routes, and error handling
• resumeParser.js: Handles PDF parsing, data extraction, and natural language querying
• index.html: Self-contained frontend with embedded CSS and JavaScript
• package.json: Defines dependencies, scripts, and project metadata

Troubleshooting

Common Issues

1. Server Won't Start

Error: Port 3000 is already in use

# Solution: Use a different port
PORT=3001 npm start

Error: Cannot find module 'express'

# Solution: Install dependencies
npm install

2. Resume Parsing Issues

Issue: Resume not loading or using placeholder data

Solutions:

• Ensure Resume.pdf exists in the project root directory
• Check file permissions (file should be readable)
• Verify the PDF is not corrupted or password-protected
• Check server logs for specific parsing errors

Example log output:

⚠️  Resume parsing encountered an issue: Error: Invalid PDF structure
📋 Server will continue with placeholder data

3. Email Functionality Issues

Error: Invalid email credentials

Solutions:

1. Check .env file configuration:

   EMAIL_USER=your-email@gmail.com
   EMAIL_PASS=your-16-character-app-password
   

2. Verify Gmail App Password:

   • Ensure 2-Factor Authentication is enabled
   • Generate a new App Password if needed
   • Use the App Password, not your regular Gmail password

3. Test email configuration:

   # Check if environment variables are loaded
   node -e "require('dotenv').config(); console.log('EMAIL_USER:', process.env.EMAIL_USER);"
   

Error: SMTP connection failed

Solutions:

• Check internet connection
• Verify Gmail SMTP is not blocked by firewall
• Try using a different network (some corporate networks block SMTP)

4. API Request Issues

Error: CORS policy error (when testing from external domains)

Solution: The server includes CORS middleware, but if you're testing from a different domain, ensure the request includes proper headers.

Error: 404 Not Found for API endpoints

Solutions:

• Verify the correct endpoint URL: /api/chat or /api/send-email
• Ensure you're using POST method for API endpoints
• Check server logs for request details

5. Frontend Interface Issues

Issue: Frontend not loading or showing errors

Solutions:

• Clear browser cache and reload
• Check browser console for JavaScript errors
• Verify server is running and accessible
• Try accessing http://localhost:3000/api/health to test server connectivity

Debug Mode

To enable detailed logging, you can modify the server startup:

# Enable debug logging (if implemented)
DEBUG=* npm start

# Or check server logs
npm start 2>&1 | tee server.log

Getting Help

If you encounter issues not covered here:

1. Check server logs for detailed error messages
2. Verify all prerequisites are installed and configured
3. Test individual components:
   • Health check: curl http://localhost:3000/api/health
   • Resume chat: Test with simple questions first
   • Email: Verify Gmail configuration separately

Performance Considerations

• Memory Usage: Resume data is stored in memory for fast access
• File Size: Large PDF files may take longer to parse on startup
• Concurrent Requests: Server handles multiple simultaneous requests
• Email Rate Limits: Gmail has sending limits; avoid rapid successive emails

Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature-name
3. Make your changes and test thoroughly
4. Commit your changes: git commit -am 'Add feature'
5. Push to the branch: git push origin feature-name
6. Submit a pull request

Development Guidelines

• Follow existing code style and commenting patterns
• Add error handling for new functionality
• Update documentation for any API changes
• Test both success and error scenarios

License

This project is licensed under the MIT License - see the package.json file for details.

Quick Start Checklist

• Node.js 14+ installed
• Dependencies installed (npm install)
• Resume.pdf file added to project root
• .env file created and configured with Gmail credentials
• Gmail App Password generated and added to .env
• Server started (npm start)
• Frontend accessible at http://localhost:3000
• API endpoints tested and working

For additional support or questions, please refer to the troubleshooting section above.