# Job Matcher MCP

🎯 **AI-powered job search and resume customization MCP (Model Context Protocol) server**

Automate your job search and customize your resume for each role in under a minute. Powered by job APIs and Claude LLM.

---

## 📋 Table of Contents

- [Quick Start (5 minutes)](#quick-start)
- [Features](#features)
- [Installation](#installation)
- [Configuration](#configuration)
- [Usage](#usage)
- [MCP Tools Reference](#mcp-tools-reference)
- [Architecture](#architecture)
- [Troubleshooting](#troubleshooting)

---

## 🚀 Quick Start

**Goal:** Get the server running with mock data in 5 minutes (no API keys needed).

### 1. Clone the repository
\\\ash
cd job-matcher-mcp
\\\

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

### 3. Run with mock data
\\\ash
export USE_MOCK_DATA=true
python mcp_server.py
\\\

**Expected output:**
\\\
=== Testing search_jobs ===
{
  "success": true,
  "job_listings": [
    {
      "id": "mock_1",
      "title": "Senior Product Manager",
      "company": "TechCorp Inc",
      "location": "San Francisco, CA",
      ...
    }
  ],
  ...
}

=== Testing customize_resume ===
{
  "success": true,
  "customized_resume": "# John Doe...",
  ...
}
`

✅ **Success!** Your MCP server is working. Now let's add real API keys.

---

## ✨ Features

| Feature | Status | Description |
|---------|--------|-------------|
| **Job Search** | ✅ MVP | Query 1000s of job listings via Adzuna API |
| **Resume Customization** | ✅ MVP | AI-powered resume tailoring using Claude |
| **Skill Matching** | ✅ MVP | Identify matched/missing skills |
| **ATS Optimization** | ✅ MVP | Automatic keyword injection for ATS |
| **Mock Data Mode** | ✅ MVP | Test without API keys |
| **Multi-API Support** | 🔜 v1.2 | Add Indeed, LinkedIn, AngelList |
| **Cover Letter Generation** | 🔜 v1.2 | Auto-generate cover letters |
| **Application Tracking** | 🔜 v2.0 | Track applications & interviews |

---

## 🔧 Installation

### Prerequisites
- Python 3.10 or higher
- pip (Python package manager)
- Git

### Step 1: Clone the repository
\\\ash
git clone https://github.com/yourusername/job-matcher-mcp.git
cd job-matcher-mcp
\\\

### Step 2: Create virtual environment (recommended)
\\\ash
# macOS/Linux
python3 -m venv venv
source venv/bin/activate

# Windows
python -m venv venv
.\\venv\\Scripts\\Activate.ps1
\\\

### Step 3: Install dependencies
\\\ash
pip install -r requirements.txt
\\\

---

## ⚙️ Configuration

### 1. Get API Keys

#### Adzuna API (Free)
1. Go to https://developer.adzuna.com/
2. Create an account
3. Create an app to get **App ID** and **App Key**
4. Free tier: ~100 requests/day

#### Anthropic Claude API (Paid, \.50-5/month)
1. Go to https://console.anthropic.com/
2. Create an account
3. Generate an **API key**
4. Pricing: ~\.003 per 1K input tokens, \.015 per 1K output tokens

### 2. Create .env file
\\\ash
cp .env.example .env
\\\

### 3. Add your API keys to .env
\\\env
ADZUNA_APP_ID=your_actual_app_id
ADZUNA_APP_KEY=your_actual_app_key
ANTHROPIC_API_KEY=sk-ant-your_actual_api_key
USE_MOCK_DATA=false
LOG_LEVEL=INFO
\\\

### 4. Load environment variables
\\\ash
# macOS/Linux
export \

# Windows PowerShell
Get-Content .env | ForEach-Object {
    \, \ = \.Split('=')
    if (\) { Set-Item -Path env:\ -Value \ }
}
\\\

---

## 💻 Usage

### Run the server
\\\ash
python mcp_server.py
\\\

### Test with curl (example)
\\\ash
# Search for jobs
curl -X POST http://localhost:8000/tools/search_jobs \\
  -H "Content-Type: application/json" \\
  -d '{
    "role": "Product Manager",
    "location": "San Francisco, CA",
    "experience_years": 5,
    "max_results": 10
  }'

# Customize resume
curl -X POST http://localhost:8000/tools/customize_resume \\
  -H "Content-Type: application/json" \\
  -d '{
    "base_resume": "...",
    "job_description": "...",
    "template": "modern"
  }'
\\\

### Python example
\\\python
from mcp_server import JobMatcherMCPServer

server = JobMatcherMCPServer()

# Search jobs
jobs = server.search_jobs(
    role="Product Manager",
    location="San Francisco, CA",
    experience_years=5,
    max_results=10
)
print(jobs)

# Customize resume
resume = server.customize_resume(
    base_resume="Your resume text here...",
    job_description="Job description here...",
    template="modern"
)
print(resume)
\\\

---

## 🛠️ MCP Tools Reference

### Tool 1: \search_jobs\

Search for job listings based on criteria.

#### Input Schema
\\\json
{
  "role": "Product Manager",              // Required: Job title
  "location": "San Francisco, CA",        // Required: Geographic location
  "experience_years": 5,                  // Required: Years of experience
  "max_results": 10,                      // Optional: Limit results (default: 10)
  "use_mock_data": false                  // Optional: Use mock data (default: false)
}
\\\

#### Output Schema
\\\json
{
  "success": true,
  "job_listings": [
    {
      "id": "12345",
      "title": "Senior Product Manager",
      "company": "TechCorp",
      "location": "San Francisco, CA",
      "link": "https://...",
      "salary_min": 120000,
      "salary_max": 160000,
      "posted_date": "2026-08-17T10:00:00Z",
      "description_snippet": "We are looking for..."
    }
  ],
  "total_found": 123,
  "search_time_ms": 1234,
  "error": null
}
\\\

#### Example
\\\python
jobs = server.search_jobs(
    role="Product Manager",
    location="Remote",
    experience_years=3,
    max_results=5
)
\\\

---

### Tool 2: \customize_resume\

Customize resume for a specific job using AI.

#### Input Schema
\\\json
{
  "base_resume": "# Jane Doe...",                     // Required: Your resume text
  "job_description": "We are looking for...",         // Required: Job posting
  "template": "modern",                               // Optional: modern|classic|minimal
  "use_mock_data": false                              // Optional: Use mock data
}
\\\

#### Output Schema
\\\json
{
  "success": true,
  "customized_resume": "# Jane Doe...",
  "match_analysis": {
    "skills_match_percentage": 82,
    "matched_skills": ["Product Management", "Leadership"],
    "missing_skills": ["Machine Learning", "Cloud"],
    "suggestions": ["Add ML experience if applicable"],
    "keywords_added": ["Data-driven", "Cross-functional"]
  },
  "generation_time_ms": 2345,
  "error": null
}
\\\

#### Example
\\\python
customized = server.customize_resume(
    base_resume=open("resume.txt").read(),
    job_description=open("job_posting.txt").read(),
    template="modern"
)
\\\

---

## 🏗️ Architecture

`
┌─────────────────────────────────────────────────────┐
│  User/AI Agent (Chat, Script, API Client)          │
└────────────────┬────────────────────────────────────┘
                 │ MCP Protocol
┌────────────────▼────────────────────────────────────┐
│         Job Matcher MCP Server                      │
│ ┌──────────────────────────────────────────────┐   │
│ │  Tool: search_jobs()                         │   │
│ │  - Query Adzuna API                          │   │
│ │  - Parse & structure results                 │   │
│ └──────────────────────────────────────────────┘   │
│ ┌──────────────────────────────────────────────┐   │
│ │  Tool: customize_resume()                    │   │
│ │  - Send to Claude API                        │   │
│ │  - Parse & return customized resume          │   │
│ └──────────────────────────────────────────────┘   │
│ ┌──────────────────────────────────────────────┐   │
│ │  External APIs                               │   │
│ │  - Adzuna Job Search API                     │   │
│ │  - Anthropic Claude API                      │   │
│ └──────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────┘
`

---

## 🔍 Troubleshooting

### Issue: \ModuleNotFoundError: No module named 'anthropic'\
**Solution:** Install dependencies
\\\ash
pip install -r requirements.txt
\\\

### Issue: \API request failed: Unauthorized\
**Solution:** Check your API keys in .env
\\\ash
# Verify keys are set
echo \
echo \
\\\

### Issue: \No jobs found\
**Solution:** Try a different role/location or increase max_results
\\\python
# Try broader search
jobs = server.search_jobs(
    role="Manager",  # More general term
    location="New York, NY",
    experience_years=5,
    max_results=50
)
\\\

### Issue: \Claude API response too slow\
**Solution:** Use mock data for testing
\\\python
resume = server.customize_resume(
    base_resume="...",
    job_description="...",
    use_mock_data=True  # Skip API call
)
\\\

### Issue: \Rate limit exceeded\
**Solution:** Adzuna free tier has limits. Implement caching:
\\\python
# Store job search results
cached_jobs = {}
key = f"{role}_{location}_{experience_years}"
if key not in cached_jobs:
    cached_jobs[key] = server.search_jobs(...)
\\\

---

## 🚢 Deployment

### Deploy to Vercel
\\\ash
# 1. Create Vercel account at https://vercel.com
# 2. Install Vercel CLI
npm install -g vercel

# 3. Deploy
vercel

# 4. Add environment variables in Vercel dashboard
# Settings → Environment Variables
\\\

### Deploy to Railway
\\\ash
# 1. Create Railway account at https://railway.app
# 2. Connect your Git repository
# 3. Add environment variables in Railway dashboard
\\\

---

## 📊 Performance Metrics (Target)

| Operation | Target Time | Actual |
|-----------|------------|--------|
| Job search | <5 seconds | ~2-3s |
| Resume customization | <10 seconds | ~3-5s |
| Mock job search | <100ms | ~50ms |
| Mock resume customization | <500ms | ~200ms |

---

## 📚 API References

- **Adzuna API**: https://developer.adzuna.com/docs
- **Claude API**: https://docs.anthropic.com/
- **MCP Protocol**: https://modelcontextprotocol.io/

---

## 📝 License

MIT License - see LICENSE file for details

---

## 👨‍💼 Author

Built for tech product managers in job transition.

**Version:** 1.0.0  
**Last Updated:** 2026-08-17  
**Status:** MVP Ready