resume-parser-ats 1.2.0 → 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,177 +1,383 @@
-# 📄 Resume Parser — Agent Skill
+<div align="center">
 
-<p align="center">
-  <strong>Deep resume parsing • ATS compatibility scoring • Actionable improvement insights</strong>
-</p>
+# 📄 Resume Parser
 
-<p align="center">
-  Made with ❤️ by <strong>Dhanush Kandhan</strong>
-</p>
+**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**
+
+[![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)
 
-An **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
-- **🤖 Agent Skill** — Install via `npx skills add` and use directly in your agent
-- **🛠️ 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
 
-## 📦 Installation
+---
 
-### As an Agent Skill (recommended)
+## 🚀 Quick Start
 
-```bash
-npx skills add dhanushk-offl/resume-parser-skill
-```
+Choose how you want to use Resume Parser:
 
-After installing, the skill is automatically available to your agent. When the agent encounters a resume-related task, it will load the skill and use it.
+| 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 |
 
-### Manual Setup
+---
 
-```bash
-# Clone the repo
-git clone https://github.com/dhanushk-offl/resume-parser-skill.git
-cd resume-parser-skill
+## 🤖 1. Agent Skill
 
-# Install dependencies
-npm install
+Install as an agent skill for automatic activation in AI coding assistants:
 
-# Build
-npm run build
+```bash
+npx skills add dhanushk-offl/resume-parser-skill
 ```
 
-## 🚀 Usage
-
-### As an Agent Skill
-
-Once installed via `npx skills add`, the agent will automatically use this skill when you:
+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
 
-The agent can invoke three tools:
+**Works with:** pi, Claude Code, OpenAI Codex, Gemini CLI, Cursor, Continue, and all [Agent Skills](https://agentskills.io) compatible tools.
+
+### What the Agent Gets
 
 | Tool | Description |
 |------|-------------|
-| `parse_resume` | Parse a resume PDF or raw text → structured data |
+| `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 |
 
-### From the CLI (after manual setup)
+### 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:
+
+```bash
+npm install -g resume-parser-ats
+```
 
 ```bash
 # Parse a resume and output structured data
-node resume-parser-ats/scripts/parse.mjs resume.pdf
+resume-parser-ats parse resume.pdf
 
 # Parse + analyze ATS compatibility
-node resume-parser-ats/scripts/analyze.mjs resume.pdf
+resume-parser-ats analyze resume.pdf
+
+# Full pipeline: parse + analyze + suggestions
+resume-parser-ats insights resume.pdf
 
-# Full pipeline: parse + analyze + actionable suggestions
-node resume-parser-ats/scripts/insights.mjs resume.pdf --strictness strict --focus ats,formatting
+# 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:
+
+```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:
+
+```typescript
+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.
+
+### 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`
+
+```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"
+```
+
+### ChatGPT / Codex (OpenAI)
+
+Add to your OpenAI MCP configuration:
+
+```json
+{
+  "mcpServers": {
+    "resume-parser": {
+      "command": "npx",
+      "args": ["-y", "resume-parser-ats", "--mcp"]
+    }
+  }
+}
+```
+
+### Cursor
+
+Add to `~/.cursor/mcp.json`:
+
+```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:
+
+```json
+{
+  "mcpServers": {
+    "resume-parser": {
+      "command": "npx",
+      "args": ["-y", "resume-parser-ats", "--mcp"]
+    }
+  }
+}
+```
+
+If you have `resume-parser-ats` installed globally:
+
+```json
+{
+  "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 follows the **OpenResume algorithm**, a proven methodology used by real ATS systems:
+The parser implements the **OpenResume algorithm**, the same methodology used by real ATS systems:
 
-### Step 1 — Read Text Items
+### Step 1 — Read Text Items from PDF
 
-Extracts all text items from the resume, including:
-- Text content
-- X/Y positions (relative to bottom-left origin)
-- Bold metadata
-- Newline markers
+Extract every text item with position, bold, and newline metadata:
 
-### Step 2 — Group Into Lines
+```typescript
+{ text: "John Doe", x1: 72, x2: 144, y: 720, bold: true, newLine: true }
+```
+
+### Step 2 — Group Text Items into Lines
 
-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.
+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 Into Sections
+### Step 3 — Group Lines into Sections
 
-Detects section titles using two heuristics:
+Detect 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.)
+2. **Fallback**: Keyword match (EDUCATION, EXPERIENCE, SKILLS, etc.)
 
 ### Step 4 — Extract Attributes via Feature Scoring
 
-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:
+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)
 
-| 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 | — | — |
+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
 
-### 1. 🎯 Job Seeker — ATS Optimization
+### 🎯 Job Seeker — ATS Optimization
 
-> *Before applying to jobs, run your resume through the parser to see what an ATS actually extracts.*
+Before applying, see what an ATS actually extracts:
 
 ```bash
-node resume-parser-ats/scripts/insights.mjs my-resume.pdf --strictness strict
+resume-parser-ats insights my-resume.pdf --strictness strict --json
 ```
 
-Identify critical issues like a missing email, unparseable name, or sections an ATS can't detect — and fix them *before* you apply.
-
-### 2. 🏢 Recruiter — Bulk Resume Screening
-
-> *Programmatically parse and score hundreds of resumes to rank candidates by ATS readability.*
+### 🏢 Recruiter — Bulk Resume Screening
 
 ```typescript
 import { parseResume, analyzeResume } from "resume-parser-ats";
@@ -180,110 +386,106 @@ import fs from "fs";
 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})`);
+  const analysis = analyzeResume({ parsedResume: parsed.data, strictness: "moderate" });
+  console.log(`${file}: ${analysis.data.atsScore}/100 (${analysis.data.atsGrade})`);
 }
 ```
 
-### 3. 🤖 Agent Integration — AI-Powered Resume Coach
+### 📈 Career Platform — Resume Health Dashboard
 
-> *Embed the skill into an AI agent that reviews resumes and gives personalized coaching.*
-
-```typescript
-import { fullPipeline } from "resume-parser-ats";
-
-const result = fullPipeline({ rawText: resumeText, strictness: "strict" });
-
-// 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.`;
-```
+Parse on upload → store ATS score → visualize → suggest improvements → track progress.
 
-### 4. 📈 Career Platform — Resume Health Dashboard
+### 🎓 University Career Center — Student Reviews
 
-> *Show users a "resume health score" on your career platform dashboard.*
+Batch-parse resumes, flag common issues, generate improvement templates.
 
-- 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
-
-### 5. 🎓 University Career Center — Student Resume Reviews
-
-> *Automate initial resume screening for career centers at scale.*
-
-- Batch-parse student resumes and generate summary reports
-- Flag common issues (missing dates, non-standard section headers)
-- Provide standardized improvement templates
+---
 
 ## 🏗️ Architecture
 
 ```
 resume-parser-skill/
-├── resume-parser-ats/           # Agent skill directory
+├── resume-parser-ats/           # Agent skill (npx skills add)
 │   ├── SKILL.md                # Skill manifest & instructions
-│   ├── scripts/                # Executable scripts for agent use
-│   │   ├── parse.mjs           # Parse a resume → JSON
-│   │   ├── analyze.mjs         # Parse + ATS scoring → JSON
-│   │   └── insights.mjs        # Full pipeline → JSON
-│   └── references/             # Detailed docs loaded on-demand
+│   └── references/
 │       └── algorithm.md        # Full algorithm specification
 ├── src/                        # TypeScript source
-│   ├── index.ts                # Main entry point + fullPipeline()
+│   ├── index.ts                # Exports + fullPipeline()
 │   ├── tools/
-│   │   ├── parse-resume.ts
-│   │   ├── analyze-resume.ts
-│   │   └── suggest-improvements.ts
+│   │   ├── parse-resume.ts    # Step 1-4 parsing engine
+│   │   ├── analyze-resume.ts  # ATS scoring & analysis
+│   │   └── suggest-improvements.ts  # Suggestion generator
 │   └── prompts/
-│       ├── parser-prompt.ts
-│       └── insights-prompt.ts
+│       ├── parser-prompt.ts    # Parsing prompt templates
+│       └── insights-prompt.ts  # Insights prompt templates
 ├── bin/
-│   └── cli.js                  # CLI entry point
+│   └── cli.js                 # CLI entry point
 ├── mcp-server/
-│   └── server.ts               # MCP server implementation
-├── test/
-│   └── evals/                  # Evaluation test suites
-├── AGENTS.md                   # Agent configuration
+│   └── server.ts              # MCP server implementation
+├── test/evals/                # Test suites (86 tests)
+├── AGENTS.md                  # Agent configuration
+├── CONTRIBUTING.md            # Contributing guide
 ├── package.json
-└── README.md
+└── tsconfig.json
 ```
 
+---
+
 ## 🧪 Testing
 
 ```bash
-# Run all tests
+# Run all 86 tests
 npm test
-```
 
-86 tests covering parsing, analysis, and suggestion generation across all strictness levels.
+# 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
 
 | Workflow | Trigger | What it does |
 |----------|---------|-------------|
-| **Build & Test** | Push/PR to `master` | Lint, build, and test across Node 18/20/22 |
+| **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:
+
+```bash
+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.2.0",
+  "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",
@@ -20,7 +20,8 @@
     "bin/",
     "resume-parser-ats/",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "CONTRIBUTING.md"
   ],
   "keywords": [
     "resume",

package/resume-parser-ats/SKILL.md

@@ -193,11 +193,26 @@ Always provide results in this structured format:
 
 ## Programmatic Access
 
-For batch processing or integration, install the npm package:
+### As an npm Library
 
 ```bash
 npm install resume-parser-ats
-npx resume-parser-ats parse resume.pdf
-npx resume-parser-ats analyze resume.pdf --strictness strict
-npx resume-parser-ats insights resume.pdf --focus ats,formatting --json
-```
+```
+
+```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.