# ATS Scanner MCP Server

An MCP (Model Context Protocol) server that automates ATS resume scanning through Jobscan. Connect it to Claude (or any MCP-compatible AI assistant) and let it scan, analyze gaps, optimize, and rescan your resume against any job description automatically.

## What It Does

Instead of manually copying your resume and job description into an ATS scanner, reading the gaps, editing, and rescanning over and over, this server lets Claude do the entire loop:

1. **Scan** your resume against a job description
2. **Read the gaps** (missing hard skills, soft skills, keyword matches)
3. **Edit** the resume to close those gaps
4. **Rescan** to verify the score improved
5. **Repeat** until the match rate hits your target (e.g., 90%+)

All in one conversation. No tab switching. No manual copy-paste.

## Tools Exposed

| Tool | Description |
|---|---|
| `jobscan_login` | Authenticate with Jobscan. Auto-runs on first scan if not called explicitly. |
| `jobscan_scan` | Scan a resume against a job description. Returns match rate, found/missing skills. |
| `jobscan_rescan` | Rescan with an updated resume (JD already loaded from previous scan). Faster than a full scan. |
| `jobscan_get_gaps` | Get a focused list of missing keywords from the most recent scan. |
| `jobscan_raw_results` | Get the full raw scan results as JSON for detailed analysis. |

## Prerequisites

- Node.js 18+
- A [Jobscan](https://www.jobscan.co/) account (free or paid)
- Chrome/Chromium installed (Playwright uses it in headed mode for Cloudflare bypass)

## Setup

1. **Clone the repo:**
   ```bash
   git clone https://github.com/jhansy29/ats-scanner-mcp.git
   cd ats-scanner-mcp
   ```

2. **Install dependencies:**
   ```bash
   npm install
   npx playwright install chromium
   ```

3. **Create your `.env` file:**
   ```bash
   cp .env.example .env
   ```
   Then edit `.env` with your Jobscan credentials:
   ```
   JOBSCAN_EMAIL=your-email@example.com
   JOBSCAN_PASSWORD=your-password
   ```

4. **Build:**
   ```bash
   npm run build
   ```

## Connect to Claude

Add this to your Claude MCP config (e.g., `claude_desktop_config.json` or `.claude/settings.json`):

```json
{
  "mcpServers": {
    "ats-scanner": {
      "command": "node",
      "args": ["path/to/ats-scanner-mcp/dist/index.js"]
    }
  }
}
```

## Usage

Once connected, just tell Claude:

> "Here's my resume and the job description. Scan it, find the gaps, update the resume, and rescan until it's above 90%."

Claude will call the MCP tools in sequence to handle the full optimization loop.

### Important: Build a Knowledge Base First

This works best when the AI has access to a **knowledge base of your real experiences, projects, and bullet variants**. Without it, the AI is guessing when it edits. With it, every optimization is grounded in work you actually did. No fabrication, just better keyword alignment.

## How It Works

- Uses **Playwright** to automate a real Chrome browser session with your Jobscan credentials
- Launches Chrome in headed mode to handle Cloudflare verification
- Parses scan results (match rate, hard/soft skill gaps, searchability, recruiter tips) and returns structured data to the AI
- The `rescan` tool reuses the existing session so the JD stays loaded, making iterations fast

## Tech Stack

- TypeScript
- [Model Context Protocol SDK](https://github.com/modelcontextprotocol/sdk)
- [Playwright](https://playwright.dev/)
- [Zod](https://zod.dev/) for input validation

## License

MIT