cv-mirror-mcp

Model Context Protocol server that lints a CV against 5 real ATS parsers.

What it does

Exposes three MCP tools so any MCP-compatible AI agent (Claude Code, Cursor, Windsurf, Zed, OpenCode, Cline, etc.) can analyse a CV against the documented quirks of:

• Workday
• Greenhouse
• Lever
• Taleo (Oracle)
• iCIMS

These are the 5 most-used enterprise ATS systems. Each one parses CVs slightly differently. A "0–100 ATS score" averages those differences into noise. This server surfaces what each one actually does — column handling, emoji stripping, header-footer dropping, date-format quirks — as concrete lint findings with concrete fixes.

The lint rules are derived from public vendor documentation. See docs/vendor-sources.md for citations.

Tools

Tool	Description
analyze_cv	Full report. Takes a CV file path (PDF or DOCX), returns per-vendor lint findings with severity (error / warn / info) and fixes.
lint_for_vendor	Single-vendor lint. Takes a path + vendor name. Faster when the user only cares about one ATS.
get_express_url	Returns the URL of the visual web companion (cv-mirror-web.vercel.app) for users who prefer a side-by-side parser view in their browser instead of an agent session.

Install

npm (recommended)

npm install -g cv-mirror-mcp

MCP client config

Add to your MCP client's config file:

Claude Code (~/.claude/mcp.json or .claude.json in project):

{
  "mcpServers": {
    "cv-mirror": {
      "command": "npx",
      "args": ["-y", "cv-mirror-mcp"]
    }
  }
}

Cursor / Windsurf / Zed / Cline: same config format (paste into wherever your client reads mcpServers).

Restart the client. The three tools above auto-register.

Usage

Once installed, just ask your agent:

Scan my CV at ~/Documents/resume.pdf and tell me what each ATS would do to it.

The agent calls analyze_cv, the lint engine runs locally (no network, no upload), and the agent surfaces the structured output:

CV Mirror — multi-vendor ATS lint report
Source: /Users/jane/Documents/resume.pdf
Format: pdf
Pages: 2
Words: 542

[ERROR] Workday
  - ERROR WORKDAY_MULTI_COLUMN: 35% of lines look multi-column. Workday's parser
    reads left-to-right and interleaves both columns into one stream.
    Fix: Convert to single-column layout. Move sidebars (Skills, Tools, Languages)
    above or below the main content.

[OK] Greenhouse
  No issues detected by the simulated parser.

[WARN] Lever
  - WARN LEVER_HEADER_FOOTER: Header/footer-like text detected ("Page 1 of 2").
    Lever historically drops content placed in PDF headers/footers.
    Fix: Remove headers and footers. Page numbers are not needed on a CV.
...

What the lint actually checks

These are real heuristics derived from public ATS docs and vendor support articles. The full list with citations lives in docs/vendor-sources.md.

Rule	Vendor	Severity	Trigger
WORKDAY_MULTI_COLUMN	Workday	error	>15% of lines have a 5+-space gap
WORKDAY_QUARTER_DATES	Workday	warn	Dates use "Q3 2024" format
WORKDAY_CONTACT_MISSING	Workday	error	No email or phone in plain text
GREENHOUSE_EMOJI	Greenhouse	warn	Any emoji codepoint detected
GREENHOUSE_FANCY_BULLETS	Greenhouse	info	Non-standard bullet glyphs
GREENHOUSE_NONSTANDARD_HEADER	Greenhouse	warn	"My Story", "Highlights Reel", etc.
LEVER_HEADER_FOOTER	Lever	warn	"Page X of Y" pattern detected
LEVER_NO_STANDARD_HEADERS	Lever	error	No "Experience"/"Education" sections
TALEO_ISO_DATES	Taleo	warn	ISO dates outnumber Month-Year dates
TALEO_LOW_TEXT_DENSITY	Taleo	error	<1 word per kB of file size
TALEO_SMART_QUOTES	Taleo	info	Curly quotes detected
ICIMS_MULTI_COLUMN	iCIMS	error	>20% of lines multi-column
ICIMS_FEW_HEADERS	iCIMS	warn	<2 standard headers found

Requirements

• Node.js >= 18
• An MCP-compatible client (Claude Code, Cursor, Windsurf, Zed, Cline, etc.)

Privacy

The server runs locally inside your agent's process. No upload endpoint. No telemetry. Your CV bytes never leave your machine.

The visual web companion at cv-mirror-web.vercel.app is also fully client-side — same engine, runs in the browser.

Tests

git clone https://github.com/goofypluto999/cv-mirror-mcp.git
cd cv-mirror-mcp
npm install
npm test

19 unit tests covering signal extraction and per-vendor rule firing.

Sister projects

• CV Mirror (web) — visual side-by-side parser view. Same lint engine. Drag-drop a PDF, see the reading-order overlay on the actual document.
• Vantage AI — once your CV passes the parsers, the next problem is the application: tailored cover letter, mock interview, fit analysis. Vantage handles that flow. Paid (£5 starter / 20 tokens, 10 free tokens at signup).

Contributing

Pull requests welcome. Particularly interested in:

• More vendor simulators (BambooHR, SmartRecruiters, JazzHR, Recruitee, etc.)
• Updated rules when vendors change their parsing behaviour (open an issue with the source link)
• Translations of the lint output

License

MIT. Workday, Greenhouse, Lever, Taleo, and iCIMS are trademarks of their respective owners. This project is not affiliated with any of them; the names are used for descriptive reference (nominative fair use).

Built by Vantage Labs.