resume-parser-ats 1.1.1 → 1.2.1

package/CONTRIBUTING.md

@@ -0,0 +1,272 @@
+# Contributing to Resume Parser
+
+First off, thank you for considering contributing! 🎉
+
+This project is a resume parsing agent skill, npm CLI tool, and MCP server. Contributions of all kinds are welcome: bug fixes, features, documentation improvements, test cases, and more.
+
+## Table of Contents
+
+- [Code of Conduct](#code-of-conduct)
+- [Getting Started](#getting-started)
+- [Development Setup](#development-setup)
+- [Project Structure](#project-structure)
+- [Making Changes](#making-changes)
+- [Running Tests](#running-tests)
+- [Code Style](#code-style)
+- [Commit Messages](#commit-messages)
+- [Pull Requests](#pull-requests)
+- [Reporting Bugs](#reporting-bugs)
+- [Feature Requests](#feature-requests)
+
+## Code of Conduct
+
+Be respectful, constructive, and inclusive. We're all here to make resume parsing better for everyone.
+
+## Getting Started
+
+1. **Fork** the repository on GitHub
+2. **Clone** your fork locally:
+   ```bash
+   git clone https://github.com/YOUR_USERNAME/resume-parser-skill.git
+   cd resume-parser-skill
+   ```
+3. **Install** dependencies:
+   ```bash
+   npm install
+   ```
+4. **Build** the project:
+   ```bash
+   npm run build
+   ```
+
+## Development Setup
+
+### Prerequisites
+
+- **Node.js** >= 18 (tested on 18, 20, 22)
+- **npm** >= 9
+
+### Key Commands
+
+| Command | Description |
+|---------|-------------|
+| `npm install` | Install dependencies |
+| `npm run build` | Compile TypeScript to `dist/` |
+| `npm test` | Run all evaluation tests |
+| `npm run lint` | Lint source files |
+| `npm run dev` | Run index.ts directly with ts-node |
+| `npm run mcp` | Start the MCP server locally |
+
+### Verify Everything Works
+
+```bash
+# Build and test
+npm run build && npm test
+
+# Verify CLI
+node bin/cli.js --help
+
+# Quick parse test
+node bin/cli.js parse "John Doe
+john@example.com
+(555) 123-4567
+Software Engineer"
+```
+
+## Project Structure
+
+```
+resume-parser-skill/
+├── resume-parser-ats/         # Agent skill directory (npx skills add)
+│   ├── SKILL.md               # Skill manifest & agent instructions
+│   └── references/
+│       └── algorithm.md       # Full 4-step algorithm spec
+├── src/                       # TypeScript source code
+│   ├── index.ts               # Main entry, 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 (npx resume-parser-ats)
+├── mcp-server/
+│   └── server.ts              # MCP server implementation
+├── test/evals/                # Test suites
+│   ├── parse-resume.test.mjs
+│   ├── analyze-resume.test.mjs
+│   └── suggest-improvements.test.mjs
+├── AGENTS.md                  # Agent configuration (skills spec)
+├── package.json
+├── tsconfig.json
+└── README.md
+```
+
+## Making Changes
+
+### Branch Naming
+
+Use descriptive branch names:
+
+```
+feature/add-bullet-point-parsing
+fix/education-date-extraction
+docs/mcp-setup-guide
+test/strict-mode-edge-cases
+```
+
+### Code Changes
+
+1. **Create a branch** from `master`:
+   ```bash
+   git checkout -b feature/your-feature
+   ```
+
+2. **Make your changes** — follow the existing code patterns
+
+3. **Update tests** — add or modify tests in `test/evals/`
+
+4. **Update documentation** — if you add a feature, update:
+   - `SKILL.md` if it affects agent-facing instructions
+   - `README.md` if it affects user-facing docs
+   - `references/algorithm.md` if it changes the parsing algorithm
+
+5. **Verify** — build and test:
+   ```bash
+   npm run build && npm test
+   ```
+
+### Important Files to Update
+
+| If you change... | Also update |
+|---|---|
+| Parsing logic in `src/tools/parse-resume.ts` | `resume-parser-ats/references/algorithm.md` |
+| Output format of any tool | `resume-parser-ats/SKILL.md` and `README.md` |
+| CLI commands or flags | `bin/cli.js` help text and `README.md` |
+| MCP tool definitions | `mcp-server/server.ts` and `README.md` |
+| Scoring or grading | `resume-parser-ats/SKILL.md` scoring tables |
+
+## Running Tests
+
+```bash
+# Run all 86 tests
+npm test
+
+# Run specific test suite
+node --test test/evals/parse-resume.test.mjs
+node --test test/evals/analyze-resume.test.mjs
+node --test test/evals/suggest-improvements.test.mjs
+
+# Run a single test with verbose output
+node --test test/evals/parse-resume.test.mjs --test-name-pattern "Step 1"
+```
+
+Tests use Node.js built-in test runner (`node:test`) and assert module (`node:assert/strict`). No additional test framework needed.
+
+### Writing New Tests
+
+Add test cases in the appropriate file under `test/evals/`:
+
+```javascript
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { parseResume } from "../../dist/src/tools/parse-resume.js";
+
+describe("My New Feature", () => {
+  it("should handle the new case correctly", () => {
+    const result = parseResume({ rawText: "..." });
+    assert.equal(result.success, true);
+    assert.equal(result.data.profile.name, "Expected Name");
+  });
+});
+```
+
+## Code Style
+
+- **TypeScript** for all source code (`src/` and `mcp-server/`)
+- **ES modules** with CommonJS compilation output
+- **2-space indentation**
+- Run `npm run lint` before committing — ESLint with TypeScript plugin
+
+Key conventions:
+- Use Zod for input validation schemas
+- Always return `{ success: boolean, data: T, metadata: {...} }` format
+- Include `warnings` array in metadata for non-fatal issues
+- Feature scoring uses additive positive and negative scores
+
+## Commit Messages
+
+Follow [Conventional Commits](https://www.conventionalcommits.org/):
+
+```
+feat: add bullet-point parsing for experience sections
+fix: handle edge case in date extraction for seasonal dates
+docs: add MCP setup guide for Claude Desktop
+test: add strict mode edge cases for phone parsing
+refactor: simplify section grouping logic
+chore: update dependencies
+```
+
+Prefixes: `feat:`, `fix:`, `docs:`, `test:`, `refactor:`, `perf:`, `chore:`, `ci:`
+
+## Pull Requests
+
+1. **Push** your branch to your fork:
+   ```bash
+   git push origin feature/your-feature
+   ```
+
+2. **Open a Pull Request** against the `master` branch
+
+3. **Describe your changes** — what, why, and how to test
+
+4. **Ensure CI passes** — all tests must pass across Node 18, 20, 22
+
+5. **Respond to review feedback** promptly
+
+### PR Checklist
+
+- [ ] Code compiles (`npm run build` succeeds)
+- [ ] All tests pass (`npm test`)
+- [ ] Lint passes (`npm run lint`)
+- [ ] New features have tests
+- [ ] Documentation updated (SKILL.md, README.md, algorithm.md as needed)
+- [ ] Commit messages follow conventional commits format
+
+## Reporting Bugs
+
+Open a [GitHub Issue](https://github.com/dhanushk-offl/resume-parser-skill/issues/new) with:
+
+1. **What you did** — exact command or input
+2. **What happened** — actual output or error
+3. **What you expected** — desired output
+4. **Environment** — Node.js version, OS, how you're using it (CLI, library, MCP, skill)
+
+## Feature Requests
+
+Open a [GitHub Issue](https://github.com/dhanushk-offl/resume-parser-skill/issues/new) with:
+
+1. **Use case** — what problem does this solve?
+2. **Proposed solution** — how should it work?
+3. **Alternatives considered** — other approaches you thought of
+4. **Which interface** — does this affect the skill, CLI, library, or MCP?
+
+## Release Process
+
+Maintainers only:
+
+```bash
+# Bump version
+npm version patch   # or minor, major
+
+# Push with tags
+git push --follow-tags
+
+# CI automatically publishes to npm and creates a GitHub release
+```
+
+---
+
+Thank you for contributing! 💛

package/README.md

@@ -1,279 +1,459 @@
+<div align="center">
+
 # 📄 Resume Parser
 
-<p align="center">
-  <strong>Deep resume parsing • ATS compatibility scoring • Actionable improvement insights</strong>
-</p>
+**Deep resume parsing • ATS compatibility scoring • Actionable improvement insights**
 
-<p align="center">
-  Made with ❤️ by <strong>Dhanush Kandhan</strong>
-</p>
+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**
+
+[![npm version](https://img.shields.io/npm/v/resume-parser-ats.svg)](https://www.npmjs.com/package/resume-parser-ats)
+[![CI](https://github.com/dhanushk-offl/resume-parser-skill/actions/workflows/ci.yml/badge.svg)](https://github.com/dhanushk-offl/resume-parser-skill/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
 
-A powerful agent skill that deeply parses resumes using the **OpenResume 4-step algorithm**, extracts structured information (Name, Email, Phone, Education, Work Experience, Skills, Projects), evaluates ATS (Applicant Tracking System) compatibility, and provides prioritized, actionable suggestions to improve your resume.
+</div>
+
+---
 
 ## ✨ 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 detailed per-field confidence ratings
+- **📊 ATS Scoring** — Grades your resume A+ through F with per-field confidence ratings
 - **💡 Smart Suggestions** — Prioritized, categorized fixes (critical → low) with before/after examples
-- **🛠️ CLI & MCP Server** — Use interactively from the command line or as an MCP tool
-- **⚙️ Configurable Strictness** — Lenient, moderate, or strict ATS evaluation modes
-- **🔒 Zero Dependencies on Proprietary APIs** — Runs entirely locally with no external calls
+- **🤖 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:
 
-## 📦 Installation
+| Method | Install | Best for |
+|--------|---------|----------|
+| **Agent Skill** | `npx skills add dhanushk-offl/resume-parser-skill` | 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** | `npm install resume-parser-ats` | Claude Desktop, ChatGPT, Cursor |
+
+---
+
+## 🤖 1. Agent Skill
+
+Install as an agent skill for automatic activation in AI coding assistants:
 
 ```bash
-# Clone the repo
-git clone https://github.com/dhanushk-offl/resume-parser-skill.git
-cd resume-parser-skill
+npx skills add dhanushk-offl/resume-parser-skill
+```
+
+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](https://agentskills.io) compatible tools.
 
-# Install dependencies
-npm install
+### What the Agent Gets
 
-# Build
-npm run build
+| 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?"
 ```
 
-## 🚀 Usage
+---
+
+## 🖥️ 2. CLI
 
-### As a CLI Tool
+Install globally for command-line use:
+
+```bash
+npm install -g resume-parser-ats
+```
 
 ```bash
 # Parse a resume and output structured data
-npx resume-parser-ats parse resume.pdf
+resume-parser-ats parse resume.pdf
 
 # Parse + analyze ATS compatibility
-npx resume-parser-ats analyze resume.pdf
+resume-parser-ats analyze resume.pdf
 
-# Full pipeline: parse + analyze + actionable suggestions
-npx resume-parser-ats insights resume.pdf
+# Full pipeline: parse + analyze + suggestions
+resume-parser-ats insights resume.pdf
 
 # Parse from raw text
-npx resume-parser-ats parse "John Doe\njohn@email.com\nSoftware Engineer"
+resume-parser-ats parse "John Doe\njohn@email.com\nSoftware Engineer"
 
 # Adjust ATS strictness
-npx resume-parser-ats analyze resume.pdf --strictness strict
+resume-parser-ats analyze resume.pdf --strictness strict
 
 # Focus on specific areas
-npx resume-parser-ats insights resume.pdf --focus ats,formatting --json
+resume-parser-ats insights resume.pdf --focus ats,formatting
+
+# Output as JSON
+resume-parser-ats insights resume.pdf --json
+```
+
+Or use without installing:
+
+```bash
+npx resume-parser-ats parse resume.pdf
 ```
 
-### As a Library
+---
+
+## 📖 3. Library (npm Package)
+
+Install as a dependency for programmatic use:
+
+```bash
+npm install resume-parser-ats
+```
 
 ```typescript
 import { parseResume, analyzeResume, suggestImprovements } from "resume-parser-ats";
 
-// Step 1: Parse
-const parsed = parseResume({ rawText: "..." });
-console.log(parsed.data.profile.name);     // "Jane Doe"
-console.log(parsed.data.profile.email);    // "jane@example.com"
+// 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"
 
-// Step 2: Analyze ATS compatibility
+// Analyze — ATS compatibility scoring
 const analysis = analyzeResume({
-  rawText: "...",
+  filePath: "./resume.pdf",
   parsedResume: parsed.data,
-  strictness: "moderate",
+  strictness: "strict",
 });
+
 console.log(analysis.data.atsScore);  // 72
 console.log(analysis.data.atsGrade);  // "B-"
+console.log(analysis.data.fieldAnalyses);
+console.log(analysis.data.formatIssues);
 
-// Step 3: Get improvement suggestions
+// Suggest — prioritized improvement recommendations
 const suggestions = suggestImprovements({
-  rawText: "...",
+  filePath: "./resume.pdf",
   parsedResume: parsed.data,
   analysisResult: analysis.data,
-  focusAreas: ["ats", "content", "formatting", "structure"],
+  focusAreas: ["ats", "content", "formatting"],
 });
-console.log(suggestions.data.quickWins);           // ["Fix your name format...", ...]
-console.log(suggestions.data.suggestions[0].title); // "Name is not parseable by ATS"
+
+console.log(suggestions.data.quickWins);
+console.log(suggestions.data.suggestions);
 ```
 
-### As an MCP Server
+### Full Pipeline
 
-```bash
-npm run mcp
+```typescript
+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})`);
 ```
 
-Starts a Model Context Protocol server exposing three tools:
+### TypeScript Types
 
-| Tool | Description |
-|------|-------------|
-| `parse_resume` | Parse a resume PDF or raw text and return structured data |
-| `analyze_resume` | Parse + compute ATS compatibility score with per-field confidence |
-| `suggest_improvements` | Parse + analyze + generate prioritized improvement suggestions |
+All types are exported:
 
-## 🧠 How It Works: The 4-Step Algorithm
+```typescript
+import type {
+  ParseResumeInput,
+  ParseResumeOutput,
+  AnalyzeResumeInput,
+  AnalyzeResumeOutput,
+  SuggestImprovementsInput,
+  SuggestImprovementsOutput,
+  ParsedResume,
+  TextItem,
+  LineItem,
+  SectionItem,
+} from "resume-parser-ats";
+```
 
-The parser follows the **OpenResume algorithm**, a proven methodology used by real ATS systems:
+---
 
-### Step 1 — Read Text Items
+## 📡 4. MCP Server
 
-Extracts all text items from the resume, including:
-- Text content
-- X/Y positions (relative to bottom-left origin)
-- Bold metadata
-- Newline markers
+Use Resume Parser as a Model Context Protocol (MCP) server to give AI assistants direct access to the parsing tools.
 
-### Step 2 — Group Into Lines
+### Claude Desktop
 
-Merges adjacent text items on the same Y-coordinate when their horizontal distance is less than the average character width. Groups by Y-coordinate to reconstruct the line-by-line reading order.
+Add to your Claude Desktop config file:
 
-### Step 3 — Group Into Sections
+**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
 
-Detects section titles using two heuristics:
-1. **Primary**: Only text item in line + bold + ALL UPPERCASE
-2. **Fallback**: Keyword match against known headers (EDUCATION, EXPERIENCE, SKILLS, etc.)
+```json
+{
+  "mcpServers": {
+    "resume-parser": {
+      "command": "npx",
+      "args": ["-y", "resume-parser-ats", "--mcp"]
+    }
+  }
+}
+```
 
-### Step 4 — Extract Attributes via Feature Scoring
+Restart Claude Desktop. You can now ask Claude to parse and analyze resumes:
 
-Each attribute (Name, Email, Phone, etc.) has **feature sets** — matching functions with positive/negative scores. The text item with the highest total score wins. This is how real ATS systems rank candidates:
+```
+"Can you analyze my resume for ATS compatibility? The file is at ~/Documents/my-resume.pdf"
+```
 
-| Feature (Name) | Score | Feature (Email) | Score |
-|---|---|---|---|
-| Contains only letters/spaces/periods | +3 | Matches email regex | +4 |
-| Is bolded | +2 | Contains @ symbol | +4 |
-| Is ALL UPPERCASE | +2 | Looks like a name (no @) | -1 |
-| Contains @ (probably email) | -4 | Contains digits (no @) | -2 |
-| Contains numbers (probably phone) | -4 | — | — |
+### ChatGPT / Codex (OpenAI)
 
-## 📊 Use Cases
+Add to your OpenAI MCP configuration:
 
-### 1. 🎯 Job Seeker — ATS Optimization
+```json
+{
+  "mcpServers": {
+    "resume-parser": {
+      "command": "npx",
+      "args": ["-y", "resume-parser-ats", "--mcp"]
+    }
+  }
+}
+```
 
-> *Before applying to jobs, run your resume through the parser to see what an ATS actually extracts.*
+### Cursor
 
-```bash
-npx resume-parser-ats insights my-resume.pdf --strictness strict --json
+Add to `~/.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "resume-parser": {
+      "command": "npx",
+      "args": ["-y", "resume-parser-ats", "--mcp"]
+    }
+  }
+}
 ```
 
-Identify critical issues like a missing email, unparseable name, or sections an ATS can't detect — and fix them *before* you apply.
+### Other MCP-Compatible Apps
 
-### 2. 🏢 Recruiter — Bulk Resume Screening
+The server uses stdio transport. For any MCP-compatible application, configure:
 
-> *Programmatically parse and score hundreds of resumes to rank candidates by ATS readability.*
+```json
+{
+  "mcpServers": {
+    "resume-parser": {
+      "command": "npx",
+      "args": ["-y", "resume-parser-ats", "--mcp"]
+    }
+  }
+}
+```
 
-```typescript
-import { parseResume, analyzeResume } from "resume-parser-ats";
-import fs from "fs";
+If you have `resume-parser-ats` installed globally:
 
-const files = fs.readdirSync("resumes/");
-for (const file of files) {
-  const parsed = parseResume({ filePath: `resumes/${file}` });
-  const analysis = analyzeResume({
-    filePath: `resumes/${file}`,
-    parsedResume: parsed.data,
-    strictness: "moderate",
-  });
-  console.log(`${file}: ATS Score ${analysis.data.atsScore}/100 (${analysis.data.atsGrade})`);
+```json
+{
+  "mcpServers": {
+    "resume-parser": {
+      "command": "resume-parser-ats",
+      "args": ["--mcp"]
+    }
+  }
 }
 ```
 
-### 3. 🤖 Agent Integration — AI-Powered Resume Coach
+### MCP Tools Available
 
-> *Embed the skill into an AI agent that reviews resumes and gives personalized coaching.*
+| 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` |
 
-```typescript
-import { fullPipeline } from "resume-parser-ats";
+---
+
+## 🧠 How It Works: The 4-Step Algorithm
+
+The parser implements the **OpenResume algorithm**, the same methodology used by real ATS systems:
 
-const result = fullPipeline({ rawText: resumeText, strictness: "strict" });
+### Step 1 — Read Text Items from PDF
 
-// result.parsed — structured data
-// result.analyzed — ATS score + field analysis
-// result.suggestions — prioritized actions
+Extract every text item with position, bold, and newline metadata:
 
-// Feed to an LLM for natural-language coaching
-const prompt = `You are a resume coach. Here is the analysis:
-${JSON.stringify(result.analyzed.data)}
-Suggest improvements in a friendly, encouraging tone.`;
+```typescript
+{ text: "John Doe", x1: 72, x2: 144, y: 720, bold: true, newLine: true }
 ```
 
-### 4. 📈 Career Platform — Resume Health Dashboard
+### 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:
+1. **Primary**: Only text item in line + bold + ALL UPPERCASE
+2. **Fallback**: Keyword match (EDUCATION, EXPERIENCE, SKILLS, etc.)
+
+### Step 4 — Extract Attributes via Feature Scoring
 
-> *Show users a "resume health score" on your career platform dashboard.*
+Each attribute has feature sets with scoring functions. The text item with the **highest total score** wins:
 
-- Parse on upload → store `atsScore`, `atsGrade`, and `fieldAnalyses`
-- Display a visual dashboard with color-coded field ratings
-- Surface `quickWins` as a checklist
-- Track score improvements over time as users update their resumes
+| 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` |
 
-### 5. 🎓 University Career Center — Student Resume Reviews
+**Name scoring example**: Only letters (+3), bolded (+2), uppercase (+2), has @ (-4), has digit (-4)
+
+See [`resume-parser-ats/references/algorithm.md`](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
 
-> *Automate initial resume screening for career centers at scale.*
+### 🎯 Job Seeker — ATS Optimization
 
-- Batch-parse student resumes and generate summary reports
-- Flag common issues (missing dates, non-standard section headers)
-- Provide standardized improvement templates
+Before applying, see what an ATS actually extracts:
 
-### 6. 🔄 Resume Migration Tool
+```bash
+resume-parser-ats insights my-resume.pdf --strictness strict --json
+```
 
-> *Convert resumes from one format to structured JSON for database ingestion.*
+### 🏢 Recruiter — Bulk Resume Screening
 
 ```typescript
-import { parseResume } from "resume-parser-ats";
+import { parseResume, analyzeResume } from "resume-parser-ats";
+import fs from "fs";
 
-const result = parseResume({ filePath: "legacy-resume.pdf" });
-// result.data is a clean, typed JSON object ready for your database
+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/
-├── package.json              # Project metadata & scripts
-├── README.md                 # This file
-├── LICENSE                   # MIT License — Dhanush Kandhan
-├── AGENTS.md                 # Agent-facing configuration
-├── SKILL.md                  # Skill definition for agent consumption
-├── src/
-│   ├── index.ts              # Main entry point + fullPipeline()
+resume-parser-skill/
+├── 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   # Fix suggestions generator
+│   │   ├── parse-resume.ts    # Step 1-4 parsing engine
+│   │   ├── analyze-resume.ts  # ATS scoring & analysis
+│   │   └── suggest-improvements.ts  # Suggestion generator
 │   └── prompts/
-│       ├── parser-prompt.ts          # Prompt templates for parsing
-│       └── insights-prompt.ts        # Prompt templates for insights
-├── mcp-server/
-│   └── server.ts             # MCP server implementation
+│       ├── parser-prompt.ts    # Parsing prompt templates
+│       └── insights-prompt.ts  # Insights prompt templates
 ├── bin/
-│   └── cli.js                # CLI entry point
-└── test/
-    └── evals/                # Evaluation test suites
-        ├── parse-resume.test.js
-        ├── analyze-resume.test.js
-        └── suggest-improvements.test.js
+│   └── 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
 ```
 
+---
+
 ## 🧪 Testing
 
 ```bash
-# Run all tests
+# Run all 86 tests
 npm test
 
-# Run evaluation suites
-node --test test/evals/parse-resume.test.js
-node --test test/evals/analyze-resume.test.js
-node --test test/evals/suggest-improvements.test.js
-```
+# Run a specific suite
+node --test test/evals/parse-resume.test.mjs
+node --test test/evals/analyze-resume.test.mjs
+node --test test/evals/suggest-improvements.test.mjs
 
-## 🤝 Contributing
+# Filter by test name
+node --test test/evals/parse-resume.test.mjs --test-name-pattern "Step 1"
+```
 
-1. Fork the repository
-2. Create a feature branch (`git checkout -b feature/amazing-feature`)
-3. Commit your changes (`git commit -m 'Add amazing feature'`)
-4. Push to the branch (`git push origin feature/amazing-feature`)
-5. Open a Pull Request
+---
 
 ## ☁️ CI/CD
 
-This project uses GitHub Actions for continuous integration and npm publishing:
-
 | Workflow | Trigger | What it does |
 |----------|---------|-------------|
-| **Build & Test** | Push/PR to `master` | Lint, build, and test across Node 18/20/22 |
-| **Publish to npm** | Tag push `v*` (e.g. `v1.0.0`) | Builds and publishes to npmjs with provenance |
+| **Build & Test** | Push/PR to `master` | Lint, build, and test across Node 18, 20, 22 |
+| **Publish to npm** | Tag push `v*` | Builds and publishes to npmjs with provenance |
 
 To publish a new version:
 
@@ -282,13 +462,30 @@ npm version patch   # or minor, major
 git push --follow-tags
 ```
 
+---
+
+## 🤝 Contributing
+
+See [CONTRIBUTING.md](./CONTRIBUTING.md) for:
+
+- Development setup
+- Project structure guide
+- Code style and testing conventions
+- Commit message format
+- Pull request checklist
+
+---
+
 ## 📄 License
 
 MIT License — Copyright (c) 2025 **Dhanush Kandhan**. See [LICENSE](./LICENSE) for details.
 
 ---
 
-<p align="center">
-  Made with ❤️ by <strong>Dhanush Kandhan</strong><br>
-  <em>If this project helped you, consider giving it a ⭐ on GitHub!</em>
-</p>
+<div align="center">
+
+Made with ❤️ by **Dhanush Kandhan**
+
+If this project helped you, consider giving it a ⭐ on [GitHub](https://github.com/dhanushk-offl/resume-parser-skill)!
+
+</div>

package/bin/cli.js

@@ -7,6 +7,7 @@
  *   resume-parser-ats parse <file|text>          Parse a resume and output structured data
  *   resume-parser-ats analyze <file|text>         Parse + analyze ATS compatibility
  *   resume-parser-ats insights <file|text>       Full pipeline: parse + analyze + suggestions
+ *   resume-parser-ats --mcp                     Start MCP server for Claude/ChatGPT/Cursor
  */
 
 const path = require("path");
@@ -35,6 +36,7 @@ Options:
   --strictness <level>    ATS strictness: lenient, moderate, strict (default: moderate)
   --focus <areas>         Focus areas: ats,content,formatting,structure (default: all)
   --json                  Output raw JSON instead of formatted report
+  --mcp                   Start MCP server (for Claude Desktop, ChatGPT, Cursor, etc.)
   --help                  Show this help message
 
 Examples:
@@ -42,12 +44,37 @@ Examples:
   resume-parser-ats analyze resume.pdf --strictness strict
   resume-parser-ats insights resume.pdf --focus ats,formatting --json
   resume-parser-ats parse "John Doe\\njohn@email.com\\nSoftware Engineer"
+
+MCP Server:
+  resume-parser-ats --mcp
+
+  Add to Claude Desktop config:
+  {
+    "mcpServers": {
+      "resume-parser": {
+        "command": "npx",
+        "args": ["-y", "resume-parser-ats", "--mcp"]
+      }
+    }
+  }
 `);
 }
 
 function main() {
   const args = process.argv.slice(2);
 
+  // Handle --mcp flag: start MCP server
+  if (args.includes("--mcp")) {
+    try {
+      require("../dist/mcp-server/server.js");
+    } catch (err) {
+      console.error("Error: MCP server not built. Run `npm run build` first.");
+      console.error(err.message);
+      process.exit(1);
+    }
+    return;
+  }
+
   if (args.length === 0 || args.includes("--help") || args.includes("-h")) {
     printUsage();
     process.exit(0);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "resume-parser-ats",
-  "version": "1.1.1",
+  "version": "1.2.1",
   "description": "An agent skill that deeply parses resumes, extracts structured data, and provides actionable insights to improve ATS compatibility and readability.",
   "main": "dist/src/index.js",
   "types": "dist/src/index.d.ts",
@@ -18,8 +18,10 @@
   "files": [
     "dist/",
     "bin/",
+    "resume-parser-ats/",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "CONTRIBUTING.md"
   ],
   "keywords": [
     "resume",
@@ -27,7 +29,9 @@
     "ATS",
     "agent-skill",
     "resume-parser",
-    "career"
+    "career",
+    "skills",
+    "npx-skills"
   ],
   "author": "dhanush",
   "license": "MIT",

package/resume-parser-ats/SKILL.md

@@ -0,0 +1,218 @@
+---
+name: resume-parser-ats
+description: >
+  Deeply parses resume PDFs using the OpenResume 4-step algorithm, extracts structured information
+  (Name, Email, Phone, Education, Work Experience, Skills, etc.), evaluates ATS compatibility,
+  and provides actionable improvement suggestions. Use when a user asks to parse, review, or
+  analyze a resume, check ATS-friendliness, or get resume improvement suggestions.
+---
+
+# Resume Parser — ATS Intelligence
+
+You are a resume parsing and ATS analysis specialist. When activated, deeply parse resumes and provide structured, actionable insights.
+
+## When to Activate
+
+- User asks to parse, review, or analyze a resume
+- User asks "is my resume ATS-friendly?"
+- User asks for resume improvement suggestions
+- User uploads or references a resume PDF
+- User wants to compare what an ATS sees vs. their intended content
+
+## Tools Available
+
+For programmatic use, install the npm package:
+
+```bash
+npm install resume-parser-ats
+```
+
+### `parse_resume` — Extract structured data from a resume
+
+```bash
+npx resume-parser-ats parse <file.pdf>
+```
+
+```javascript
+import { parseResume } from "resume-parser-ats";
+const result = parseResume({ filePath: "/path/to/resume.pdf" });
+// or: parseResume({ rawText: "John Doe\njohn@email.com..." })
+```
+
+**Input**: `{ filePath?: string, rawText?: string }`
+**Output**: Structured data with profile, education, experience, skills, projects.
+
+---
+
+### `analyze_resume` — Parse + ATS compatibility scoring
+
+```bash
+npx resume-parser-ats analyze <file.pdf> --strictness strict
+```
+
+```javascript
+import { analyzeResume } from "resume-parser-ats";
+const result = analyzeResume({ filePath: "/path/to/resume.pdf", strictness: "moderate" });
+```
+
+**Input**: `{ filePath?, rawText?, strictness?: "lenient"|"moderate"|"strict" }`
+**Output**: ATS score (0-100), letter grade (A+ to F), per-field confidence, section detection, format issues.
+
+---
+
+### `suggest_improvements` — Parse + analyze + prioritized suggestions
+
+```bash
+npx resume-parser-ats insights <file.pdf> --strictness strict --focus ats,formatting
+```
+
+```javascript
+import { suggestImprovements } from "resume-parser-ats";
+const result = suggestImprovements({ filePath: "/path/to/resume.pdf", focusAreas: ["ats", "content"] });
+```
+
+**Input**: `{ filePath?, rawText?, strictness?, focusAreas?: string[] }`
+**Output**: Overall score, grade, quick wins, prioritized suggestions (critical → low), section analysis.
+
+---
+
+## Manual Parsing Algorithm
+
+Use this algorithm when the npm package is unavailable or for understanding the parsing logic:
+
+### Step 1: Read Text Items from PDF
+
+Extract all text items from the PDF. Each item includes:
+- `text` — text content
+- `x1`, `x2` — left/right X positions (origin at bottom-left)
+- `y` — Y position from bottom
+- `bold` — whether text is bold
+- `newLine` — whether this item starts a new line
+
+### Step 2: Group Text Items into Lines
+
+1. **Merge adjacent items**: When `Distance = RightTextItem.X₁ - LeftTextItem.X₂` is less than average character width, merge them
+2. **Average character width**: Total character widths / total character count (exclude bold and newline elements)
+3. **Group by Y-coordinate**: Same Y = same line
+
+### Step 3: Group Lines into Sections
+
+**Section title detection** (must satisfy ALL 3):
+1. It is the only text item in the line
+2. It is bolded
+3. Its letters are all UPPERCASE
+
+**Fallback**: Keyword match against known headers:
+PROFILE, SUMMARY, OBJECTIVE, ABOUT, EDUCATION, ACADEMIC, DEGREES, EXPERIENCE, WORK EXPERIENCE, EMPLOYMENT, PROFESSIONAL EXPERIENCE, SKILLS, TECHNICAL SKILLS, COMPETENCIES, PROJECTS, PORTFOLIO, CERTIFICATIONS, LICENSES, HONORS, AWARDS, VOLUNTEER, COMMUNITY, LEADERSHIP, PUBLICATIONS, RESEARCH, INTERESTS, ACTIVITIES, HOBBIES
+
+Lines before any section title go into PROFILE.
+
+### Step 4: Extract Attributes via Feature Scoring
+
+Each attribute has feature sets (matching function + score). The text item with the **highest total score** wins.
+
+| Attribute | Core Feature | Regex |
+|-----------|-------------|-------|
+| Name | Only letters/spaces/periods | `/^[a-zA-Z\s\.]+$/` |
+| Email | Email format | `/\S+@\S+\.\S+/` |
+| Phone | Phone format | `/\(?\d{3}\)?[\s-]?\d{3}[\s-]?\d{4}/` |
+| Location | City, ST format | `/[A-Z][a-zA-Z\s]+, [A-Z]{2}/` |
+| URL | URL format | `/\S+\.[a-z]+\/\S+/` |
+
+**Name scoring example**: Only letters (+3), bolded (+2), uppercase (+2), has @ (-4), has digit (-4), has comma (-4), has slash (-4)
+
+**Subsection detection** (for Education, Work Experience):
+- Primary: vertical line gap > typical line gap × 1.4
+- Fallback: text item is bolded
+
+See [references/algorithm.md](references/algorithm.md) for the full specification.
+
+---
+
+## ATS Compatibility Scoring
+
+| Dimension | Weight |
+|-----------|--------|
+| Name extraction | 20 pts |
+| Email extraction | 20 pts |
+| Phone extraction | 10 pts |
+| Section detection | 15 pts |
+| Education parsing | 10 pts |
+| Experience parsing | 15 pts |
+| Skills parsing | 10 pts |
+
+**Grading**: A+ (90-100), A (85-89), B+ (80-84), B (75-79), B- (70-74), C+ (65-69), C (60-64), D (50-59), F (0-49)
+
+## Issue Severity Levels
+
+- **CRITICAL**: Name or email cannot be parsed → ATS will likely discard
+- **HIGH**: Key sections missing, dates unparseable, phone not found
+- **MEDIUM**: Skills not extracted cleanly, formatting merge issues
+- **LOW**: Minor inconsistencies, optional fields missing
+
+## Output Format
+
+Always provide results in this structured format:
+
+```
+## 📊 Resume Parsing Report
+
+### ATS Compatibility Score: XX/100 (Grade: X)
+
+### ✅ Successfully Parsed Fields
+| Field | Parsed Value | Confidence |
+|-------|-------------|------------|
+| Name  | John Doe    | High       |
+
+### ⚠️ Issues Found
+| # | Severity | Field | Issue | Suggestion |
+|---|----------|-------|-------|------------|
+| 1 | CRITICAL | Email | ...  | ...        |
+
+### 📝 Priority Fixes
+1. **[Fix Title]**: Description of what to change and why
+   - Before: `current state`
+   - After: `suggested state`
+
+### 📋 Section-by-Section Analysis
+#### Profile
+- Analysis notes...
+```
+
+## Important Rules
+
+1. **Always run all 4 parsing steps** — do not skip steps
+2. **Always provide the ATS compatibility score** — this is the primary metric
+3. **Every suggestion must be actionable** — not "improve formatting" but "Move the date to the same line as the company name"
+4. **Prioritize Name and Email extraction** — if they fail, flag as CRITICAL
+5. **Explain WHY** each suggestion matters in ATS terms
+6. **Compare parsed output vs. likely intended content** — surface discrepancies
+7. **Never modify the original file** — this is a read-only analysis tool
+8. **If a PDF cannot be parsed**, fall back to raw text and note the limitation
+9. **Flag when text items break unexpectedly** (e.g., phone numbers split across items)
+
+## Programmatic Access
+
+### As an npm Library
+
+```bash
+npm install resume-parser-ats
+```
+
+```typescript
+import { parseResume, analyzeResume, suggestImprovements } from "resume-parser-ats";
+
+const result = parseResume({ filePath: "resume.pdf" });
+```
+
+### As an MCP Server
+
+Start the MCP server for use with Claude Desktop, ChatGPT, Cursor, and other MCP-compatible apps:
+
+```bash
+resume-parser-ats --mcp
+# or
+npx resume-parser-ats --mcp
+```
+
+See README for full MCP configuration instructions.

package/resume-parser-ats/references/algorithm.md

@@ -0,0 +1,126 @@
+# OpenResume 4-Step Parsing Algorithm
+
+This document provides the full technical reference for the resume parsing algorithm.
+
+## Step 1: Read Text Items from PDF
+
+Extract all text items from the PDF using `pdfjs-dist`. Each text item includes:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `text` | string | The text content |
+| `x1` | number | Left X position |
+| `x2` | number | Right X position |
+| `y` | number | Y position (from page bottom) |
+| `bold` | boolean | Whether the text is bold |
+| `newLine` | boolean | Whether this item starts a new line |
+
+X,Y coordinates are relative to the bottom-left corner (origin 0,0).
+
+## Step 2: Group Text Items into Lines
+
+1. **Merge adjacent items** when `Distance = RightTextItem.X₁ - LeftTextItem.X₂` is less than average character width
+2. Average character width = total character widths / total character count (exclude bold and newline elements)
+3. **Group by Y-coordinate** to form lines (same Y = same line)
+
+This reconstructs the line-by-line reading order that may be lost in PDF extraction.
+
+## Step 3: Group Lines into Sections
+
+### Section Title Detection (primary heuristic — must satisfy ALL 3):
+
+1. It is the only text item in the line
+2. It is bolded
+3. Its letters are all UPPERCASE
+
+### Fallback Heuristic: Keyword matching
+
+Known section titles: PROFILE, SUMMARY, OBJECTIVE, ABOUT, EDUCATION, ACADEMIC, DEGREES, EXPERIENCE, WORK EXPERIENCE, EMPLOYMENT, PROFESSIONAL EXPERIENCE, SKILLS, TECHNICAL SKILLS, COMPETENCIES, PROJECTS, PORTFOLIO, CERTIFICATIONS, LICENSES, HONORS, AWARDS, VOLUNTEER, COMMUNITY, LEADERSHIP, PUBLICATIONS, RESEARCH, INTERESTS, ACTIVITIES, HOBBIES
+
+- Group all lines under their closest preceding section title
+- Lines before any section title go into the PROFILE section
+
+## Step 4: Extract Resume Attributes using Feature Scoring
+
+Each attribute has **feature sets** (matching function + score). Run every text item through all feature sets for an attribute. The text item with the **highest total feature score** is extracted as that attribute.
+
+### Subsection Detection (for Education, Work Experience, etc.)
+
+- **Primary**: vertical line gap > typical line gap × 1.4
+- **Fallback**: text item is bolded
+
+### Feature Scoring Tables
+
+#### Name
+
+| Feature | Score |
+|---------|-------|
+| Contains only letters, spaces or periods | +3 |
+| Is bolded | +2 |
+| Contains all uppercase letters | +2 |
+| Contains @ (may be email) | -4 |
+| Contains number (may be phone) | -4 |
+| Contains , (may be address) | -4 |
+| Contains / (may be URL) | -4 |
+
+#### Email
+
+| Feature | Score |
+|---------|-------|
+| Matches email regex `\S+@\S+\.\S+` | +5 |
+| Contains @ | +2 |
+
+#### Phone
+
+| Feature | Score |
+|---------|-------|
+| Matches phone regex `\(?\d{3}\)?[\s-]?\d{3}[\s-]?\d{4}` | +5 |
+
+#### Location
+
+| Feature | Score |
+|---------|-------|
+| Matches city,state regex `[A-Z][a-zA-Z\s]+, [A-Z]{2}` | +5 |
+
+#### URL
+
+| Feature | Score |
+|---------|-------|
+| Matches URL regex `\S+\.[a-z]+\/\S+` | +5 |
+
+#### School
+
+| Feature | Score |
+|---------|-------|
+| Contains school keyword (College, University, School, Institute, Academy) | +4 |
+
+#### Degree
+
+| Feature | Score |
+|---------|-------|
+| Contains degree keyword (Associate, Bachelor, Master, Doctorate, B.S., B.A., M.S., M.A., Ph.D.) | +4 |
+
+#### GPA
+
+| Feature | Score |
+|---------|-------|
+| Matches GPA regex `[0-4]\.\d{1,2}` | +5 |
+
+## ATS Compatibility Scoring Framework
+
+| Dimension | Weight |
+|-----------|--------|
+| Name extraction | 20 pts |
+| Email extraction | 20 pts |
+| Phone extraction | 10 pts |
+| Section detection | 15 pts |
+| Education parsing | 10 pts |
+| Experience parsing | 15 pts |
+| Skills parsing | 10 pts |
+
+### Issue Severity Levels
+
+- **CRITICAL**: Name or email cannot be parsed (ATS will likely discard)
+- **HIGH**: Key sections missing, dates unparseable, phone not found
+- **MEDIUM**: Skills not extracted cleanly, formatting merge issues
+- **LOW**: Minor inconsistencies, optional fields missing