# Resume Analyzer MCP Server 📄🎯

An open-source **Model Context Protocol (MCP)** server built with Python (`mcp` SDK) that allows AI models (Claude, Antigravity, Cursor) to analyze resumes, calculate objective ATS (Applicant Tracking System) scores, and suggest job-tailored CV improvements.

---

## 🌟 Features

### 🛠️ Tools
1. **`analyze_resume(resume_text: str, target_job_title: str)`**
   - Evaluates structural completeness (Summary, Experience, Education, Skills, Projects).
   - Detects high-impact action verbs and quantitative performance metrics (e.g. `%, $, multipliers`).
   - Identifies role-aligned key skills.

2. **`suggest_improvements(resume_text: str, target_job_title: str)`**
   - Generates actionable, role-tailored bullet point enhancements.
   - Identifies weak/passive phrasing and recommends high-impact verb upgrades.
   - Applies the Google 'XYZ Formula' (*Accomplished X, as measured by Y, by doing Z*).

3. **`calculate_ats_score(resume_text: str, job_description: str)`**
   - Compares resume text against a target job description.
   - Calculates a precise ATS Match Percentage Score (e.g. **ATS Score: 82%**).
   - Generates keyword match ratio, matched terms, and critical missing keywords.

### 📚 Resources
- **`resume://sample-template`**: Industry-standard markdown CV template.
- **`rules://ats-guidelines`**: ATS parsing standards and bullet-point scoring criteria.

### 💬 Prompts
- **`full_resume_review`**: Pre-built prompt template for running an end-to-end career review workflow.

---

## 💬 Example Prompts for Users & Clients

### 1. Resume Structural Analysis (`analyze_resume`)
> *"Can you use `analyze_resume` to review my CV below for a Backend Engineer position?"*
> ```markdown
> # John Smith
> Skills: Python, PostgreSQL, Docker, REST APIs
> Experience: Software Engineer at Acme Inc. Developed backend APIs in Python and reduced database latency by 30%.
> Education: B.S. in Computer Science
> ```

### 2. ATS Match Score (`calculate_ats_score`)
> *"Please run `calculate_ats_score` to check my match percentage against this job description."*
> - **Resume:** `Skills: Python, SQL, PostgreSQL, Docker`
> - **Job Description:** `Seeking Senior Backend Engineer proficient in Python, SQL, PostgreSQL, Redis, Docker, Kubernetes, CI/CD.`

### 3. Actionable CV Recommendations (`suggest_improvements`)
> *"Can you run `suggest_improvements` on my resume for a Data Engineer role?"*
> ```markdown
> Worked on data pipelines. Helped with SQL queries and handled daily reports.
> ```

### 4. Fetch Resources
> *"Can you read the resource `resume://sample-template` to show me a standard resume format?"*

---

## 🚀 Quick Start & Local Setup

### 1. Prerequisites
- Python 3.10 or higher
- Git

### 2. Installation
Clone or navigate to the project workspace:
```bash
cd D:\dev\resume-analyzer-mcp

# Create and activate virtual environment
python -m venv .venv
# On Windows PowerShell:
.\.venv\Scripts\Activate.ps1
# On macOS/Linux:
source .venv/bin/activate

# Install dependencies
pip install -e .
```

---

## 🧪 Running Local Verification Tests

Run the automated integration test suite which programmatically launches the MCP server via `stdio` and verifies tool calls, resources, and prompts:

```bash
python test_client.py
```

---

## 🔌 Connecting to MCP Clients

### Claude Desktop Configuration
Add the server configuration to your `claude_desktop_config.json`:

* **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
* **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`

```json
{
  "mcpServers": {
    "resume-analyzer": {
      "command": "D:\\dev\\resume-analyzer-mcp\\.venv\\Scripts\\python.exe",
      "args": [
        "D:\\dev\\resume-analyzer-mcp\\server.py"
      ]
    }
  }
}
```

### Antigravity / Gemini Configuration
Add to your workspace `.agents/mcp_config.json` or `~/.gemini/config/mcp_config.json`:

```json
{
  "mcpServers": {
    "resume-analyzer": {
      "command": "python",
      "args": ["D:/dev/resume-analyzer-mcp/server.py"]
    }
  }
}
```

---

## ☁️ Deploying to Smithery MCP Marketplace

[Smithery](https://smithery.ai) allows developers to discover, host, and install MCP servers automatically.

### Step 1: Push Repository to GitHub
```bash
git add .
git commit -m "Add example prompts and documentation"
git remote add origin https://github.com/your-username/resume-analyzer-mcp.git
git push -u origin main
```

### Step 2: Publish to Smithery
1. Visit [smithery.ai](https://smithery.ai) and sign in with GitHub.
2. Click **Submit Server** and select your `resume-analyzer-mcp` repository.
3. Smithery automatically builds your container from `smithery.yaml` and `Dockerfile` and renders your `README.md` with interactive sample prompts!

---

## 📄 License
MIT License. Free for commercial and non-commercial use.