📄 Resume Parser

Deep resume parsing • ATS compatibility scoring • Actionable improvement insights

An agent skill, CLI tool, npm library, and MCP server that deeply parses resumes using the OpenResume 4-step algorithm, extracts structured information (Name, Email, Phone, Education, Work Experience, Skills, Projects), evaluates ATS compatibility, and provides prioritized, actionable suggestions.

Made with ❤️ by Dhanush Kandhan

✨ Features

🔍 Deep Parsing — Extracts 10+ fields from raw text or PDF using a feature-scoring engine
📊 ATS Scoring — Grades your resume A+ through F with per-field confidence ratings
💡 Smart Suggestions — Prioritized, categorized fixes (critical → low) with before/after examples
🤖 Agent Skill — Install via npx skills add for pi, Claude Code, Codex, Gemini CLI, and more
🖥️ CLI — Use directly from the command line
📡 MCP Server — Plug into Claude Desktop, ChatGPT, and other MCP-compatible apps
📖 Library — Import as an npm package for programmatic use
⚙️ Configurable — Lenient, moderate, or strict ATS evaluation modes
🔒 Privacy-first — Runs entirely locally, no external API calls

🚀 Quick Start

Choose how you want to use Resume Parser:

Method	Install	Best for
Agent Skill	`npx skills add dhanushk-offl/resume-parser`	AI agents (pi, Claude Code, Codex, Gemini CLI)
CLI	`npm install -g resume-parser-ats`	Quick one-off resume analysis
Library	`npm install resume-parser-ats`	Building apps, batch processing
MCP Server	`claude mcp add resume-parser -- npx -y resume-parser-ats --mcp`	Claude Code, Codex, Claude Desktop, Cursor

🤖 1. Agent Skill

Install as an agent skill for automatic activation in AI coding assistants:

npx skills add dhanushk-offl/resume-parser

Once installed, the skill activates automatically when you:

Ask to parse, review, or analyze a resume
Ask "is my resume ATS-friendly?"
Ask for resume improvement suggestions
Upload or reference a resume PDF

Works with: pi, Claude Code, OpenAI Codex, Gemini CLI, Cursor, Continue, and all Agent Skills compatible tools.

What the Agent Gets

Tool	Description
`parse_resume`	Parse a resume PDF/text → structured data
`analyze_resume`	Parse + compute ATS compatibility score with per-field confidence
`suggest_improvements`	Parse + analyze + generate prioritized improvement suggestions

Example Agent Prompts

"Is my resume ATS-friendly? Here's the PDF path: ./my-resume.pdf"
"Parse this resume and extract the contact info"
"Analyze my resume for ATS compatibility with strict grading"
"What can I improve on my resume to get past ATS filters?"

🖥️ 2. CLI

Install globally for command-line use:

npm install -g resume-parser-ats

# Parse a resume and output structured data
resume-parser-ats parse resume.pdf

# Parse + analyze ATS compatibility
resume-parser-ats analyze resume.pdf

# Full pipeline: parse + analyze + suggestions
resume-parser-ats insights resume.pdf

# Parse from raw text
resume-parser-ats parse "John Doe\njohn@email.com\nSoftware Engineer"

# Adjust ATS strictness
resume-parser-ats analyze resume.pdf --strictness strict

# Focus on specific areas
resume-parser-ats insights resume.pdf --focus ats,formatting

# Output as JSON
resume-parser-ats insights resume.pdf --json

Or use without installing:

npx resume-parser-ats parse resume.pdf

📖 3. Library (npm Package)

Install as a dependency for programmatic use:

npm install resume-parser-ats

import { parseResume, analyzeResume, suggestImprovements } from "resume-parser-ats";

// Parse — extract structured data
const parsed = parseResume({ filePath: "./resume.pdf" });
// or: parseResume({ rawText: "John Doe\njohn@email.com\n..." })

console.log(parsed.data.profile.name);    // "Jane Doe"
console.log(parsed.data.profile.email);   // "jane@example.com"
console.log(parsed.data.education[0]?.school);  // "MIT"

// Analyze — ATS compatibility scoring
const analysis = analyzeResume({
  filePath: "./resume.pdf",
  parsedResume: parsed.data,
  strictness: "strict",
});

console.log(analysis.data.atsScore);  // 72
console.log(analysis.data.atsGrade);  // "B-"
console.log(analysis.data.fieldAnalyses);
console.log(analysis.data.formatIssues);

// Suggest — prioritized improvement recommendations
const suggestions = suggestImprovements({
  filePath: "./resume.pdf",
  parsedResume: parsed.data,
  analysisResult: analysis.data,
  focusAreas: ["ats", "content", "formatting"],
});

console.log(suggestions.data.quickWins);
console.log(suggestions.data.suggestions);

Full Pipeline

import { fullPipeline } from "resume-parser-ats";

const { parsed, analyzed, suggestions } = fullPipeline({
  filePath: "./resume.pdf",
  strictness: "moderate",
});

console.log(`ATS Score: ${analyzed.data.atsScore}/100 (${analyzed.data.atsGrade})`);

TypeScript Types

All types are exported:

import type {
  ParseResumeInput,
  ParseResumeOutput,
  AnalyzeResumeInput,
  AnalyzeResumeOutput,
  SuggestImprovementsInput,
  SuggestImprovementsOutput,
  ParsedResume,
  TextItem,
  LineItem,
  SectionItem,
} from "resume-parser-ats";

📡 4. MCP Server

Use Resume Parser as a Model Context Protocol (MCP) server to give AI assistants direct access to the parsing tools.

Quick Install

One command to add to each app:

# Claude Code
claude mcp add resume-parser -- npx -y resume-parser-ats --mcp

# OpenAI Codex
codex mcp add resume-parser -- npx -y resume-parser-ats --mcp

That's it. Restart the app and the tools are available.

Claude Code (CLI)

claude mcp add resume-parser -- npx -y resume-parser-ats --mcp

Add to a specific scope:

# User scope (available in all projects)
claude mcp add --scope user resume-parser -- npx -y resume-parser-ats --mcp

# Project scope (available in current project only)
claude mcp add --scope project resume-parser -- npx -y resume-parser-ats --mcp

Remove with:

claude mcp remove resume-parser

OpenAI Codex (CLI)

codex mcp add resume-parser -- npx -y resume-parser-ats --mcp

Remove with:

codex mcp remove resume-parser

Claude Desktop

Add to your Claude Desktop config file:

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

{
  "mcpServers": {
    "resume-parser": {
      "command": "npx",
      "args": ["-y", "resume-parser-ats", "--mcp"]
    }
  }
}

Restart Claude Desktop. You can now ask Claude to parse and analyze resumes:

"Can you analyze my resume for ATS compatibility? The file is at ~/Documents/my-resume.pdf"

Cursor

Add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "resume-parser": {
      "command": "npx",
      "args": ["-y", "resume-parser-ats", "--mcp"]
    }
  }
}

Other MCP-Compatible Apps

The server uses stdio transport. For any MCP-compatible application, configure:

{
  "mcpServers": {
    "resume-parser": {
      "command": "npx",
      "args": ["-y", "resume-parser-ats", "--mcp"]
    }
  }
}

If you have resume-parser-ats installed globally:

{
  "mcpServers": {
    "resume-parser": {
      "command": "resume-parser-ats",
      "args": ["--mcp"]
    }
  }
}

MCP Tools Available

Tool	Description	Parameters
`parse_resume`	Parse resume PDF/text → structured data	`filePath`, `rawText`
`analyze_resume`	Parse + ATS scoring	`filePath`, `rawText`, `strictness`
`suggest_improvements`	Parse + analyze + suggestions	`filePath`, `rawText`, `focusAreas`

🧠 How It Works: The 4-Step Algorithm

The parser implements the OpenResume algorithm, the same methodology used by real ATS systems:

Step 1 — Read Text Items from PDF

Extract every text item with position, bold, and newline metadata:

{ text: "John Doe", x1: 72, x2: 144, y: 720, bold: true, newLine: true }

Step 2 — Group Text Items into Lines

Merge adjacent items when their horizontal gap is less than average character width. Group by Y-coordinate to reconstruct the natural reading order.

Step 3 — Group Lines into Sections

Detect section titles using two heuristics:

Primary: Only text item in line + bold + ALL UPPERCASE
Fallback: Keyword match (EDUCATION, EXPERIENCE, SKILLS, etc.)

Step 4 — Extract Attributes via Feature Scoring

Each attribute has feature sets with scoring functions. The text item with the highest total score wins:

Attribute	Core Pattern	Example
Name	Only letters/spaces/periods	`John Doe`
Email	Email format	`john@email.com`
Phone	`(xxx) xxx-xxxx`	`(555) 123-4567`
Location	`City, ST`	`New York, NY`
School	Contains "University" etc.	`MIT`
Degree	Contains "B.S.", "M.A." etc.	`B.S. Computer Science`

Name scoring example: Only letters (+3), bolded (+2), uppercase (+2), has @ (-4), has digit (-4)

See resume-parser-ats/references/algorithm.md for the full specification.

📊 ATS Compatibility Scoring

Dimension	Weight	What it checks
Name extraction	20 pts	Can the parser identify a full name?
Email extraction	20 pts	Is there a valid email address?
Phone extraction	10 pts	Is there a parseable phone number?
Section detection	15 pts	Are sections properly structured?
Education parsing	10 pts	Are school, degree, and date parsed?
Experience parsing	15 pts	Are company, title, and date parsed?
Skills parsing	10 pts	Are skills extracted correctly?

Grading Scale

Grade	Score	Meaning
A+	90-100	Excellent — ATS will parse everything correctly
A	85-89	Great — minor issues only
B+	80-84	Good — most fields parse correctly
B	75-79	Adequate — some sections need improvement
B-	70-74	Below average — multiple parsing issues
C+	65-69	Needs work — significant ATS problems
C	60-64	Poor — many fields fail to parse
D	50-59	Bad — critical fields missing
F	0-49	Failing — unrecognizable as a resume

Issue Severity Levels

🔴 CRITICAL — Name or email cannot be parsed (ATS will discard)
🟠 HIGH — Sections missing, dates unparseable, phone not found
🟡 MEDIUM — Skills not clean, formatting merge issues
🟢 LOW — Minor inconsistencies, optional fields missing

📊 Use Cases

🎯 Job Seeker — ATS Optimization

Before applying, see what an ATS actually extracts:

resume-parser-ats insights my-resume.pdf --strictness strict --json

🏢 Recruiter — Bulk Resume Screening

import { parseResume, analyzeResume } from "resume-parser-ats";
import fs from "fs";

const files = fs.readdirSync("resumes/");
for (const file of files) {
  const parsed = parseResume({ filePath: `resumes/${file}` });
  const analysis = analyzeResume({ parsedResume: parsed.data, strictness: "moderate" });
  console.log(`${file}: ${analysis.data.atsScore}/100 (${analysis.data.atsGrade})`);
}

📈 Career Platform — Resume Health Dashboard

Parse on upload → store ATS score → visualize → suggest improvements → track progress.

🎓 University Career Center — Student Reviews

Batch-parse resumes, flag common issues, generate improvement templates.

🏗️ Architecture

resume-parser/
├── resume-parser-ats/           # Agent skill (npx skills add)
│   ├── SKILL.md                # Skill manifest & instructions
│   └── references/
│       └── algorithm.md        # Full algorithm specification
├── src/                        # TypeScript source
│   ├── index.ts                # Exports + fullPipeline()
│   ├── tools/
│   │   ├── parse-resume.ts    # Step 1-4 parsing engine
│   │   ├── analyze-resume.ts  # ATS scoring & analysis
│   │   └── suggest-improvements.ts  # Suggestion generator
│   └── prompts/
│       ├── parser-prompt.ts    # Parsing prompt templates
│       └── insights-prompt.ts  # Insights prompt templates
├── bin/
│   └── cli.js                 # CLI entry point
├── mcp-server/
│   └── server.ts              # MCP server implementation
├── test/evals/                # Test suites (86 tests)
├── AGENTS.md                  # Agent configuration
├── CONTRIBUTING.md            # Contributing guide
├── package.json
└── tsconfig.json

🗺️ Future Roadmap

We have big plans. Here's what's coming — and where we need your help:

🛠️ CLI Resume Builder

A CLI-based tool for creating resumes in multiple formats (PDF, HTML, Markdown, LaTeX) — with templates, theming, and interactive prompts. No more fighting with Word formatting.

📄 Terminal-Native PDF Parsing

Improved parsing of various PDF encodings directly in the terminal — resolving canvas rendering issues, CID font mapping, and other common ATS-breaking PDF problems that current parsers silently fail on.

🤖 Agent-Driven Parsing Pipeline

An agent-based orchestration layer that intelligently routes different resume formats and encodings through the optimal parsing path, with fallback strategies and self-healing extraction.

🎯 Dynamic Skill Updates from JDs

Automatically adjust parsing weights, keyword extraction, and skill identification based on a target Job Description — so the parser focuses on what matters for that role.

⚙️ OpenResume-Grade Parsing Algorithm

Continuing to refine our implementation toward (and beyond) the full OpenResume parsing spec — including bullet-point extraction, date-range normalization, multi-column layout detection, and cross-section reference resolution.

We're actively looking for contributors! If any of these areas excite you — whether it's PDF internals, parsing algorithms, CLI design, or agent orchestration — check out CONTRIBUTING.md and open an issue. Every contribution matters.

🤝 Contributing

See CONTRIBUTING.md for the full guide:

Development setup & prerequisites
Project structure
Code style & testing conventions
Commit message format
Pull request checklist

Found a bug or have an idea? Open an issue!

📄 License

Made with ❤️ by Dhanush Kandhan

If this project helped you, consider giving it a ⭐ on GitHub!

Name		Name	Last commit message	Last commit date
Latest commit History 16 Commits
.github		.github
bin		bin
mcp-server		mcp-server
resume-parser-ats		resume-parser-ats
src		src
test/evals		test/evals
.gitignore		.gitignore
.npmignore		.npmignore
AGENTS.md		AGENTS.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
eslint.config.mjs		eslint.config.mjs
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json

Folders and files

Latest commit

History

Repository files navigation

📄 Resume Parser

✨ Features

🚀 Quick Start

🤖 1. Agent Skill

What the Agent Gets

Example Agent Prompts

🖥️ 2. CLI

📖 3. Library (npm Package)

Full Pipeline

TypeScript Types

📡 4. MCP Server

Quick Install

Claude Code (CLI)

OpenAI Codex (CLI)

Claude Desktop

Cursor

Other MCP-Compatible Apps

MCP Tools Available

🧠 How It Works: The 4-Step Algorithm

Step 1 — Read Text Items from PDF

Step 2 — Group Text Items into Lines

Step 3 — Group Lines into Sections

Step 4 — Extract Attributes via Feature Scoring

📊 ATS Compatibility Scoring

Grading Scale

Issue Severity Levels

📊 Use Cases

🎯 Job Seeker — ATS Optimization

🏢 Recruiter — Bulk Resume Screening

📈 Career Platform — Resume Health Dashboard

🎓 University Career Center — Student Reviews

🏗️ Architecture

🗺️ Future Roadmap

🛠️ CLI Resume Builder

📄 Terminal-Native PDF Parsing

🤖 Agent-Driven Parsing Pipeline

🎯 Dynamic Skill Updates from JDs

⚙️ OpenResume-Grade Parsing Algorithm

🤝 Contributing

📄 License

About

Topics

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases 6

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages