io.github.XJTLUmedia/ai-hr-management-toolkit
AI HR toolkit: 24 MCP tools for resume parsing, skill extraction & ATS management.
Open source Open in the app JSON README (API)
About
AI HR toolkit: 24 MCP tools for resume parsing, skill extraction & ATS management.
Details
- Kind
- MCP servers
- Topic
- No topic detected
- Publisher
- xjtlumedia
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 3.0.5
- Stars
- 1
- Forks
- 1
- Last push
- 2026-04-05T12:50:41Z
- Repository state
- ativo
- Language
- TypeScript
- License
- MIT
- Added
- 2026-08-29 03:02:20
- Updated
- 2026-08-29 03:02:20
- Origin id
io.github.XJTLUmedia/ai-hr-management-toolkit
README
# AI HR Management Toolkit
> AI-powered resume parser & full Applicant Tracking System with **21 MCP tools**. Parse PDFs, extract skills, detect patterns, score candidates, and manage a complete hiring pipeline — all from your AI assistant, no manual work required.
<img width="1889" height="781" alt="image" src="https://github.com/user-attachments/assets/572b4dd8-8fd4-469c-b71d-a4f513c4b466" />
<img width="1896" height="635" alt="image" src="https://github.com/user-attachments/assets/aa0fc7c1-6373-4a48-9faf-3b15c42871f1" />
<img width="1562" height="572" alt="image" src="https://github.com/user-attachments/assets/4a0ec218-b61f-43c8-b6b8-657219e30dab" />
**Live demo:** https://ai-hr-management-toolkit.vercel.app
[](https://www.npmjs.com/package/mcp-ai-hr-management-toolkit)
[](LICENSE)
<a href="https://glama.ai/mcp/servers/mcp-ai-hr-management-toolkit">
<img width="380" height="200" src="https://glama.ai/mcp/servers/mcp-ai-hr-management-toolkit/badge" alt="mcp-ai-hr-management-toolkit server" />
</a>
---
## What Is This?
You have 50 resumes to screen. Your AI assistant can reason about candidates — but it cannot open PDFs, extract structured data, or track pipeline stages. This toolkit bridges that gap.
**Give your AI assistant 21 tools** covering the entire hiring workflow:
- Parse PDFs, DOCX, TXT, Markdown, and URLs into structured JSON
- Extract skills, experience, keywords, and entities algorithmically
- Score and rank candidates against job descriptions
- Run a full ATS: jobs, candidates, interviews, offers, notes, and analytics
**20 of 21 tools are 100% algorithmic** — no LLM calls, no API keys required. The AI calls tools, interprets the results, and delivers analysis. You just ask questions.
---
## Quick Start (MCP Clients)
No installation needed. Point your MCP client at the package:
**Claude Desktop** — Edit `%APPDATA%\Claude\claude_desktop_config.json` (Windows) or `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS):
```json
{
"mcpServers": {
"ai-hr-management-toolkit": {
"command": "npx",
"args": ["-y", "mcp-ai-hr-management-toolkit"]
}
}
}
```
Example usage:
<img width="1101" height="556" alt="image" src="https://github.com/user-attachments/assets/34a8fd29-5f51-4f8b-9f3c-df0e31f36354" />
<img width="1094" height="314" alt="image" src="https://github.com/user-attachments/assets/fb641f07-a977-413c-903c-b67f806d75b1" />
**Cursor** — Add to `.cursor/mcp.json` in your project root:
```json
{
"mcpServers": {
"ai-hr-management-toolkit": {
"command": "npx",
"args": ["-y", "mcp-ai-hr-management-toolkit"]
}
}
}
```
**VS Code Copilot** — Create `.vscode/mcp.json` in your project root:
```json
{
"servers": {
"ai-hr-management-toolkit": {
"command": "npx",
"args": ["-y", "mcp-ai-hr-management-toolkit"]
}
}
}
```
> **VS Code users:** Run the `npx` command from a directory that contains a `package.json` (i.e. any project root). The `cwd` key in `.vscode/mcp.json` can override the working directory if needed.
**Windsurf / other MCP clients** — Use the same `npx` pattern above.
---
## Installation Options
### Option 1: NPX (Zero-install, recommended)
Works from any project directory (requires a `package.json` in the working directory):
```json
{
"mcpServers": {
"ai-hr-management-toolkit": {
"command": "npx",
"args": ["-y", "mcp-ai-hr-management-toolkit"]
}
}
}
```
### Option 2: Global install
Install once, use from any directory:
```bash
npm install -g mcp-ai-hr-management-toolkit
```
```json
{
"mcpServers": {
"ai-hr-management-toolkit": {
"command": "mcp-ai-hr-management-toolkit",
"args": []
}
}
}
```
### Option 3: Remote HTTP endpoint
Deploy the Next.js app and use the Streamable HTTP transport:
```
https://your-domain.com/api/mcp
```
Test locally:
```bash
npx @modelcontextprotocol/inspector http://localhost:3000/api/mcp
```
### Option 4: Local development (Web UI + MCP)
```bash
git clone <repo-url>
cd Resume-parser
npm install
npm run dev
```
Web UI at `http://localhost:3000`. MCP endpoint at `http://localhost:3000/api/mcp`. No `.env` needed — configure API keys in the UI or pass them per tool call.
---
## All 21 MCP Tools
All tools return structured JSON with `next_steps` hints so the AI knows what to call next.
### Resume Parsing & Ingestion
| Tool | What it does | AI? |
|------|-------------|:---:|
| `parse_resume` | Parse PDF / DOCX / TXT / MD / URL → raw text + contacts, keywords, section map | No |
| `batch_parse_resumes` | Parse up to 20 files in one call, full pipeline on each | No |
| `inspect_pipeline` | Run the 5-stage analysis pipeline → confidence scores, entity counts, data quality report | No |
### Unified Analysis
| Tool | What it does | AI? |
|------|-------------|:---:|
| `analyze_resume` | Master analysis tool with selectable aspects: `keywords` (TF-IDF + bigrams), `patterns` (date ranges, metrics, team sizes, career trajectory), `entities` (NER with 12 types + context disambiguation), `skills` (13 categories with proficiency estimation), `experience` (structured timeline), `similarity` (cosine, Jaccard, TF-IDF overlap vs. job description), or `all` | No |
> `analyze_resume` consolidates what were previously 7 separate tools (`extract_keywords`, `detect_patterns`, `classify_entities`, `extract_skills_structured`, `extract_experience_structured`, `compute_similarity`, `analyze_resume_comprehensive`) into a single entry point with aspect selection.
### Candidate Matching & Scoring
| Tool | What it does | AI? |
|------|-------------|:---:|
| `assess_candidate` | Score against up to 8 weighted criteria axes → weighted total + pass / review / reject decision | Optional |
### Export & Notifications
| Tool | What it does | AI? |
|------|-------------|:---:|
| `export_results` | Export structured parse results to JSON or CSV | No |
| `send_email` | Send results via SMTP (config passed per call — no server-side secrets stored) | No |
### ATS — Jobs
| Tool | What it does | AI? |
|------|-------------|:---:|
| `ats_manage_jobs` | Full CRUD for job postings: create, read, update, delete, list, search by title/department/status | No |
### ATS — Candidates & Pipeline
| Tool | What it does | AI? |
|------|-------------|:---:|
| `ats_manage_candidates` | CRUD + analytics: add, update, move stage, bulk-move, filter, rank, compare, recommend stage changes, summarize | No |
| `ats_analytics` | Unified dashboard + pipeline analytics: stage distribution, conversion rates, avg time-in-stage, bottleneck detection, offer acceptance rate | No |
| `ats_search` | Global full-text search across all ATS entities (candidates, jobs, interviews, offers, notes) | No |
### ATS — Interviews
| Tool | What it does | AI? |
|------|-------------|:---:|
| `ats_schedule_interview` | Create, update, and delete interviews with conflict detection and interviewer availability check | No |
| `ats_interview_feedback` | Submit structured feedback, compute consensus score, summarize feedback across all interviewers | No |
### ATS — Offers & Notes
| Tool | What it does | AI? |
|------|-------------|:---:|
| `ats_manage_offers` | Full offer lifecycle: draft → pending → approved → sent → accepted / declined / expired | No |
| `ats_manage_notes` | Add, update, search, and delete timestamped candidate notes | No |
### ATS — Enterprise HR
| Tool | What it does | AI? |
|------|-------------|:---:|
| `ats_compliance` | EEO/EEOC reporting, GDPR export/erasure, audit trail, data retention policies | No |
| `ats_talent_pool` | Passive candidate talent pools (CRM): create pools, add/remove candidates, search, analytics | No |
| `ats_scorecard` | Structured interview scorecards with weighted criteria, per-evaluator scores, aggregate rankings | No |
| `ats_onboarding` | Post-hire onboarding checklists: tasks by category, assignees, progress tracking, overdue alerts | No |
| `ats_communication` | Email templates with `{{variable}}` interpolation, send/preview, communication history, stats | No |
### Testing & Seeding
| Tool | What it does | AI? |
|------|-------------|:---:|
| `ats_generate_demo_data` | Generate a realistic sample ATS dataset (jobs, candidates, interviews, offers) for testing | No |
> **`assess_candidate`** optionally calls an LLM when you supply `provider` + `apiKey`; it falls back to fully algorithmic scoring otherwise.
---
## Example Multi-Turn Flow
```
You: "Parse this resume and tell me if they're a good fit for our Senior Engineer role"
AI → parse_resume(file)
→ raw text, contact info, section map
AI → inspect_pipeline(rawText)
→ 5-stage confidence scores, entity classification
AI → analyze_resume(text, aspects=["skills", "patterns", "similarity"], jobDescription=...)
→ 13 skill categories with proficiency levels
→ career trajectory, metrics, date ranges
→ cosine 0.74, skill match 82%, gap analysis
AI synthesizes → "Strong match. 6 of 8 required skills present.
Two gaps: Kubernetes and system design at scale.
Recommend: Technical Screen"
```
---
## Analysis Pipeline
Every resume runs through a 5-stage algorithmic pipeline:
```
┌─────────────┐ ┌──────────────┐ ┌──────────────┐ ┌────────────────┐ ┌───────────────┐
│ Ingestion │───▶│ Sanitization │───▶│ Tokenization │───▶│ Classification │───▶│ Serialization │
│ (file/URL) │ │ (noise trim) │ │ (TF-IDF) │ │ (NER + disamb) │ │ (structured) │
└─────────────┘ └──────────────┘ └──────────────┘ └────────────────┘ └───────────────┘
```
1. **Ingestion** — PDF via pdf-parse v2, DOCX via mammoth, HTML/URL via cheerio, plain text/markdown natively
2. **Sanitization** — Removes non-ASCII artifacts, normalizes whitespace, strips formatting noise
3. **Tokenization** — TF-IDF with unigrams, bigrams, and trigrams; scored by document frequency
4. **Classification** — NER with domain-aware disambiguation (e.g. "Java" as language vs. Indonesian city; "Go" as language vs. verb)
5. **Serialization** — Maps entities to typed `ResumeSchema` with confidence scores and data quality metrics
---
## Supported File Formats
| Format | Extensions | Parser |
|--------|-----------|--------|
| PDF | `.pdf` | pdf-parse v2 |
| DOCX | `.docx` | mammoth |
| Plain text | `.txt` | direct read |
| Markdown | `.md`, `.markdown` | regex-based |
| URL / HTML | any URL string | cheerio |
Max file size: **10 MB**
---
## Structured Output Schema
```
contact — name, email, phone, location, LinkedIn, GitHub, website, portfolio
summary — professional summary text
skills[] — name, category (13 types), proficiency, usage context
experience[] — company, title, start/end dates, highlights, achievements (with metrics), technologies
education[] — institution, degree, field, dates, GPA
certifications[] — name, issuer, date, credential URL
projects[] — name, description, URL, technologies, highlights
languages[] — spoken language and proficiency
```
---
## Web UI
The app ships with a full web interface:
| Tab | Description |
|-----|-------------|
| **Single Parse** | Upload one file or paste a URL. Returns structured data, pipeline visualization, and AI-enhanced analysis |
| **Batch Parse** | Upload up to 20 files. Export to JSON / CSV / PDF or email results |
| **Chat** | Conversational interface with tool access — ask questions about any parsed resume |
| **ATS** | Full pipeline board: jobs, candidates (Kanban), interviews, offers, and analytics dashboard |
Switch AI providers from the selector at the top. Supports OpenAI, Anthropic, Google, DeepSeek, GLM, Qwen, OpenRouter, and OpenCode Zen.
---
## REST API Endpoints
All endpoints accept `multipart/form-data` with optional headers:
| Header | Description |
|--------|-------------|
| `x-api-key` | Your AI provider API key |
| `x-ai-provider` | `openai` / `anthropic` / `google` / `deepseek` / `glm` / `qwen` / `openrouter` / `opencodezen` |
| `x-ai-model` | Specific model ID |
```bash
# Parse a single resume
curl -X POST http://localhost:3000/api/parse \
-H "x-api-key: sk-..." \
-F "file=@resume.pdf"
# Batch parse (up to 20 files)
curl -X POST http://localhost:3000/api/batch-parse \
-H "x-api-key: sk-..." \
-F "files=@resume1.pdf" \
-F "files=@resume2.docx"
# MCP endpoint (Streamable HTTP)
curl -X POST http://localhost:3000/api/mcp \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","method":"tools/list","id":1}'
# Export parsed data
curl -X POST http://localhost:3000/api/export \
-H "Content-Type: application/json" \
-d '{"format":"csv","results":[...]}'
```
---
## Tech Stack
| Layer | Technologies |
|-------|-------------|
| Framework | Next.js 16 (App Router, Turbopack), React 19, TypeScript |
| AI | Vercel AI SDK v6, multi-provider (OpenAI, Anthropic, Google, DeepSeek, GLM, Qwen, OpenRouter) |
| MCP | `@modelcontextprotocol/sdk` v1.29 — Streamable HTTP + stdio transports |
| Parsing | pdf-parse v2, mammoth, cheerio |
| NLP | TF-IDF, NER, cosine similarity, Jaccard index (all in-process, no external services) |
| Schema | Zod v4 |
| Export | ExcelJS (CSV/XLSX), jsPDF + jspdf-autotable |
| Email | Nodemailer |
| Styling | Tailwind CSS v4, Framer Motion |
---
## Development
```bash
npm install
# Start dev server (Web UI at :3000 + MCP at /api/mcp)
npm run dev
# Build the standalone MCP CLI (stdio transport)
npm run build:mcp
# Build the Next.js app for production
npm run build
# Test MCP with the official inspector
npx @modelcontextprotocol/inspector http://localhost:3000/api/mcp
npx @modelcontextprotocol/inspector node dist/mcp-stdio.js
# Lint
npm run lint
```
---
## Project Structure
```
src/
├── app/
│ ├── page.tsx # Main UI (tabs, provider selector, chat, ATS)
│ ├── layout.tsx # Root layout + global styles
│ └── api/
│ ├── parse/route.ts # Single resume parse
│ ├── batch-parse/route.ts
│ ├── chat/route.ts # Conversational AI with tool access
│ ├── mcp/route.ts # MCP server (Streamable HTTP)
│ ├── models/route.ts # Provider model listing
│ ├── export/route.ts # JSON / CSV / PDF export
│ └── email/route.ts # SMTP email
├── components/ # React UI components (parse, batch, chat, ATS)
│ └── ats/ # ATS-specific views (Kanban, Dashboard, Scheduler…)
└── lib/
├── ai-model.ts # Multi-provider model config (no env fallback)
├── mcp-server.ts # MCP server — registers all 21 tools
├── schemas/
│ ├── resume.ts # Zod v4 ResumeSchema
│ └── criteria.ts # Assessment criteria schema
├── analysis/
│ ├── pipeline.ts # 5-stage pipeline orchestrator
│ ├── sanitizer.ts # Text cleaning
│ ├── keyword-extractor.ts # TF-IDF
│ ├── classifier.ts # NER with context disambiguation
│ ├── pattern-matcher.ts # Regex extraction (metrics, dates, contacts)
│ └── scoring.ts # Cosine similarity, Jaccard, skill matching
├── parser/
│ ├── pdf.ts, docx.ts, text.ts, markdown.ts, url.ts
│ └── index.ts
├── ats/
│ ├── types.ts # ATS entity types
│ ├── store.ts # In-memory ATS state
│ ├── demo-data.ts # Realistic seed data generator
│ └── context.tsx # React context for ATS state
└── tools/
├── parse-resume.ts # parse_resume
├── inspect-pipeline.ts # inspect_pipeline
├── export-results.ts # export_results
├── send-email.ts # send_email
└── mcp/ # 17 MCP-specific tools
├── analyze-resume.ts # analyze_resume (unified: keywords, patterns, entities, skills, experience, similarity)
├── batch-parse.ts # batch_parse_resumes
├── assess-candidate.ts # assess_candidate
├── ats-manage-candidates.ts # ats_manage_candidates (includes rank/filter/compare/summarize)
├── ats-manage-jobs.ts
├── ats-manage-offers.ts
├── ats-manage-notes.ts
├── ats-analytics.ts # ats_analytics (unified dashboard + pipeline)
├── ats-schedule-interview.ts
├── ats-interview-feedback.ts
├── ats-search.ts
├── ats-generate-demo-data.ts
├── ats-compliance.ts # Enterprise: EEO / GDPR / audit
├── ats-talent-pool.ts # Enterprise: passive candidate CRM
├── ats-scorecard.ts # Enterprise: structured scorecards
├── ats-onboarding.ts # Enterprise: onboarding checklists
└── ats-communication.ts # Enterprise: email templates & history
```
---
## License
[MIT](LICENSE)