MCP CV Modifier Server

An MCP (Model Context Protocol) server that intelligently modifies CVs based on job descriptions using keyword extraction and strategic enhancement.

✅ Cross-Platform Support:

Desktop/Server: Windows • macOS • Linux • Unix

Mobile: iOS (Remote) • Android (Remote + Termux)

Full installation guides for each platform are available in PLATFORM_COMPATIBILITY.md.

Note: The MCP server runs as a Node.js backend. For mobile devices (iOS/Android), access the server remotely from desktop or use tunneling services. See PLATFORM_COMPATIBILITY.md - Mobile Platforms for details.

Features

• Extract Job Descriptions: Scrape job postings from LinkedIn and other job sites to extract requirements and keywords

• Parse Multiple CV Formats: Support for PDF, DOCX, Markdown, and JSON CV formats

• Multi-Language Support: Full support for Hebrew and English with automatic language detection

• Hebrew Language Features:

  • Complete Right-to-Left (RTL) text handling

  • Hebrew character support (Unicode U+0590 to U+05FF)

  • Automatic Hebrew section header translation

  • 50+ Hebrew technical skill translations

  • Mixed Hebrew-English content support

• Keyword-Based Enhancement: Strategically enhance CVs by incorporating relevant job keywords

• Multiple Output Formats: Generate modified CVs in PDF, DOCX, and/or Markdown formats with language-aware formatting

• CV-Job Match Analysis: Analyze how well a CV matches a job description without modifications

• Natural Language Enhancement: Uses multiple modification levels (minimal, moderate, aggressive) to ensure natural-sounding enhancements

Related MCP server: CV Writer MCP Server

Architecture

src/
├── index.ts                    # MCP server entry point
├── config.ts                   # Configuration management
├── types/
│   ├── cv.types.ts            # CV data structures with language metadata
│   ├── job.types.ts           # Job description structures
│   ├── language.types.ts       # Language configuration & RTL markers
│   └── mcp.types.ts           # MCP tool definitions
├── parsers/                   # CV parsing (Phase 2)
│   ├── cv-parser.ts           # Main coordinator with language detection
│   ├── pdf-parser.ts
│   ├── docx-parser.ts
│   ├── markdown-parser.ts
│   └── json-parser.ts
├── scrapers/                  # Web scraping (Phase 3)
├── nlp/                       # NLP & keyword extraction (Phase 4)
│   ├── keyword-extractor.ts
│   ├── skill-matcher.ts
│   ├── text-analyzer.ts
│   └── hebrew-keywords.ts     # 50+ Hebrew skill translations
├── modifiers/                 # CV modification logic (Phase 5)
├── generators/                # Document generation (Phase 6)
│   ├── markdown-generator.ts
│   ├── markdown-generator-rtl.ts # Hebrew RTL support
│   ├── pdf-generator.ts
│   └── docx-generator.ts
├── tools/                     # MCP tool implementations
└── utils/
    ├── logger.ts              # Logging utility
    ├── language-detector.ts   # Language detection & analysis
    ├── rtl-formatter.ts       # RTL text formatting
    └── validators.ts          # Input validation

Installation

Prerequisites

• Node.js 18+ (Download)

• npm (comes with Node.js) or yarn

• Git (optional, for cloning the repository)

Cross-Platform Support

This MCP server runs on Windows, macOS, Linux, and Unix systems. Follow the OS-specific instructions below.

Windows Installation

1. Clone or download the project

cd c:\mcp-server-cv-modify

2. Install dependencies

npm install

3. Install Playwright browsers (for web scraping)

npx playwright install chromium

4. Create environment file

Copy-Item .env.example .env
# Edit .env with your preferred editor (Notepad, VS Code, etc.)

5. Verify installation

npm run build
npm start

macOS Installation

1. Clone or download the project

cd ~/mcp-server-cv-modify
# Or wherever you downloaded/cloned it

2. Install dependencies

npm install

3. Install Playwright browsers (for web scraping)

npx playwright install chromium

4. Create environment file

cp .env.example .env
# Edit .env with your preferred editor (nano, vim, VS Code, etc.)
nano .env  # or: open -a TextEdit .env

5. Verify installation

npm run build
npm start

Linux Installation

1. Clone or download the project

cd ~/mcp-server-cv-modify
# Or wherever you downloaded/cloned it

2. Install dependencies

npm install

3. Install Playwright browsers (for web scraping)

npx playwright install chromium

4. Create environment file

cp .env.example .env
# Edit .env with your preferred editor (nano, vim, VS Code, etc.)
nano .env  # or: vi .env

5. Verify installation

npm run build
npm start

Note for Linux users: Playwright may require additional system dependencies. If you encounter issues, install them with:

# Ubuntu/Debian
sudo apt-get update
sudo apt-get install -y libgbm1 libxss1 libatk1.0-0 libatk-bridge2.0-0 libcups2 libxkbcommon0 libnss3 libxcomposite1

# Fedora/RHEL
sudo dnf install libxss libxcomposite libxkbcommon

# Arch Linux
sudo pacman -S libxss libxcomposite libxkbcommon

Unix Installation

1. Clone or download the project

cd /opt/mcp-server-cv-modify
# Or wherever you want to install it

2. Install dependencies

npm install

3. Install Playwright browsers (for web scraping)

npx playwright install chromium

4. Create environment file

cp .env.example .env
# Edit .env with your preferred editor
nano .env  # or: vi .env

5. Verify installation

npm run build
npm start

Building

Build the TypeScript project:

npm run build

This compiles TypeScript to JavaScript in the dist/ directory.

Running

Development Mode

All Platforms:

npm run dev

This starts the server with auto-reload when files change.

Production Mode

All Platforms:

npm run build
npm start

Running in the Background

Windows (PowerShell):

# Start in background
Start-Process node "dist\index.js"

# Or with logging
Start-Process node "dist\index.js" -RedirectStandardOutput "logs\output.log" -RedirectStandardError "logs\error.log"

macOS/Linux/Unix (Bash):

# Start in background
nohup npm start > logs/output.log 2>&1 &

# Or using screen
screen -d -m npm start

# Or using tmux
tmux new-session -d -s mcp-server "npm start"

Windows (Command Prompt):

# Using start command
start node dist\index.js

# Or using npm with npm-run-all for persistent execution
npm start

Debugging

All Platforms: Enable debug logging by setting the environment variable:

# Linux/macOS/Unix
export LOG_LEVEL=debug
npm start

# Windows PowerShell
$env:LOG_LEVEL = "debug"
npm start

# Windows Command Prompt
set LOG_LEVEL=debug
npm start

Or edit .env and set LOG_LEVEL=debug

Mobile Support

This server can be accessed from iOS and Android devices through several methods:

• Remote Access (Same WiFi) - Easiest, ~5 minutes setup

• Tunneling Service (Ngrok, Cloudflare) - Anywhere access, ~10 minutes

• Cloud Deployment (Railway, Render, Heroku) - Always-on, ~15-30 minutes

• Termux (Android only) - Local Node.js installation, ~20-30 minutes

• Custom Mobile App - Native iOS/Android app development

Quick Start for Mobile:

1. Start server on desktop: npm start
2. Find desktop IP: ipconfig (Windows) or ifconfig (macOS/Linux)
3. Open on mobile: http://[desktop-ip]:3000

For detailed mobile setup guides, examples, and advanced options, see MOBILE_USAGE.md.

MCP Tools

1. extract_job_description

Extracts job description and keywords from a job posting URL.

Input:

• url (string, required): Job posting URL

• extractKeywords (boolean, default: true): Auto-extract and categorize keywords

Output:

• Job title, company, location

• Full description text

• Extracted keywords with scores and categories

• Categorized skills (technical, soft skills, tools)

Example:

{
  "url": "https://www.linkedin.com/jobs/view/123456",
  "extractKeywords": true
}

2. modify_cv

Modifies a CV to emphasize relevant keywords for a job.

Input:

• cvData (string, required): CV content (base64, raw text, or file path)

• cvFormat (enum, required): "pdf" | "docx" | "markdown" | "json"

• jobKeywords (array, optional): Manual keyword list

• jobUrl (string, optional): Auto-extract keywords from URL

• outputFormat (enum, default: "pdf"): "pdf" | "docx" | "markdown" | "all"

• modificationLevel (enum, default: "moderate"): "minimal" | "moderate" | "aggressive"

Output:

• Modified CV in requested format(s)

• Modification summary with before/after match scores

• List of changes and keywords added

• Improvement suggestions

Example:

{
  "cvData": "base64_encoded_pdf",
  "cvFormat": "pdf",
  "jobUrl": "https://www.linkedin.com/jobs/view/123456",
  "outputFormat": "pdf",
  "modificationLevel": "moderate"
}

3. analyze_cv_job_match

Analyzes how well a CV matches a job description without modifying it.

Input:

• cvData (string, required): CV content

• cvFormat (enum, required): Format type

• jobUrl (string, required): Job posting URL

Output:

• Overall match score (0-100%)

• Missing keywords and skills

• Section-by-section analysis

• Specific improvement recommendations

Example:

{
  "cvData": "markdown_cv_content",
  "cvFormat": "markdown",
  "jobUrl": "https://www.linkedin.com/jobs/view/123456"
}

Hebrew Language Support

This MCP server includes full support for Hebrew language with complete Right-to-Left (RTL) text handling. See HEBREW_SUPPORT.md for comprehensive documentation.

Features:

• Automatic Language Detection: Detects Hebrew vs English content automatically

• Full RTL Formatting: Proper right-to-left text direction and indentation

• Hebrew Section Headers: All CV section headers automatically translated to Hebrew

• 50+ Hebrew Skill Translations: Common technical and soft skills translated to Hebrew

• Mixed Language Support: Handles mixed Hebrew-English content with proper Unicode markers

• Hebrew Unicode Support: Full support for Hebrew characters (U+0590 to U+05FF)

Example - Hebrew CV Input:

{
  "cvData": "שם: דוד כהן\nאימייל: david@example.com\n\nניסיון:\nמפתח תוכנה בTech Corp",
  "cvFormat": "markdown",
  "jobUrl": "https://example.com/hebrew-job"
}

Output automatically includes:

• RTL text direction

• Hebrew section headers

• Proper indentation and spacing

• Mixed language directional markers where needed

For complete Hebrew language documentation, examples, and usage, see HEBREW_SUPPORT.md.

Configuration

Edit .env to configure the server:

# Node environment
NODE_ENV=production

# Rate limiting (to avoid scraping detection)
SCRAPER_MIN_DELAY_MS=5000
SCRAPER_MAX_CONCURRENT=1

# Caching
CACHE_ENABLED=true
CACHE_TTL_HOURS=24

# Browser
PLAYWRIGHT_HEADLESS=true
BROWSER_TIMEOUT_MS=30000

# NLP
NLP_MIN_KEYWORD_SCORE=0.3
NLP_MAX_KEYWORDS=50

# CV Modification
CV_MODIFICATION_CONFIDENCE_THRESHOLD=0.6
CV_MAX_KEYWORDS_PER_BULLET=2

# Language & Localization
DETECT_LANGUAGE=true
EMBED_RTL_MARKERS=true
NORMALIZE_HEBREW_SPACING=true
USE_HEBREW_CHARACTER_WIDTHS=true

Integration with Claude Desktop

To use this MCP server with Claude Desktop, add it to your MCP servers configuration. The configuration file location varies by operating system.

Windows

1. Open or create %APPDATA%\Claude\claude_desktop_config.json

   • Full path: C:\Users\[YourUsername]\AppData\Roaming\Claude\claude_desktop_config.json

   • You can quickly open AppData with: Win+R, type %appdata%, press Enter

2. Add this configuration:

{
  "mcpServers": {
    "cv-modifier": {
      "command": "node",
      "args": ["C:\\path\\to\\mcp-server-cv-modify\\dist\\index.js"],
      "env": {
        "NODE_ENV": "production"
      }
    }
  }
}

3. Replace C:\path\to\mcp-server-cv-modify with your actual installation path

4. Restart Claude Desktop

macOS

1. Open or create ~/Library/Application Support/Claude/claude_desktop_config.json

   nano ~/Library/Application\ Support/Claude/claude_desktop_config.json

2. Add this configuration:

{
  "mcpServers": {
    "cv-modifier": {
      "command": "node",
      "args": ["/path/to/mcp-server-cv-modify/dist/index.js"],
      "env": {
        "NODE_ENV": "production"
      }
    }
  }
}

3. Replace /path/to/mcp-server-cv-modify with your actual installation path (e.g., ~/mcp-server-cv-modify or /Users/username/Documents/mcp-server-cv-modify)

4. Restart Claude Desktop

Linux

1. Open or create ~/.config/Claude/claude_desktop_config.json

   nano ~/.config/Claude/claude_desktop_config.json

2. Add this configuration:

{
  "mcpServers": {
    "cv-modifier": {
      "command": "node",
      "args": ["/path/to/mcp-server-cv-modify/dist/index.js"],
      "env": {
        "NODE_ENV": "production"
      }
    }
  }
}

3. Replace /path/to/mcp-server-cv-modify with your actual installation path

4. Restart Claude Desktop

Unix

1. Open or create ~/.config/Claude/claude_desktop_config.json (or /etc/claude/claude_desktop_config.json for system-wide installation)

   nano ~/.config/Claude/claude_desktop_config.json

2. Add this configuration:

{
  "mcpServers": {
    "cv-modifier": {
      "command": "node",
      "args": ["/path/to/mcp-server-cv-modify/dist/index.js"],
      "env": {
        "NODE_ENV": "production"
      }
    }
  }
}

3. Replace /path/to/mcp-server-cv-modify with your actual installation path

4. Restart Claude Desktop

Finding Your Installation Path

Windows:

# Command Prompt or PowerShell
cd c:\mcp-server-cv-modify
echo %cd%
# Or simply: echo C:\path\to\mcp-server-cv-modify

macOS/Linux/Unix:

pwd  # Shows current directory
# If in mcp-server-cv-modify folder, shows the full path
# Or use: realpath .

Verify Installation

After adding the configuration and restarting Claude Desktop:

1. In Claude, you should see the CV Modifier tools available

2. Try using one of the tools: extract_job_description, modify_cv, or analyze_cv_job_match

3. If tools don't appear, check the Claude Desktop logs (Settings > Logs)

Development

Project Structure

• src/index.ts - MCP server entry point

• src/types/ - TypeScript type definitions

• src/parsers/ - CV parsing implementations

• src/scrapers/ - Web scraping implementations

• src/nlp/ - NLP and keyword extraction

• src/modifiers/ - CV modification logic

• src/generators/ - Document generation

• src/tools/ - MCP tool handlers

• src/utils/ - Utility functions

• tests/ - Test files

Running Tests

npm test

Run specific test categories:

npm run test:unit      # Unit tests only
npm run test:integration # Integration tests only

Implementation Phases

✅ Phase 1: Foundation & MCP Server Setup

• TypeScript configuration

• MCP server setup with three tools

• Type definitions

• Basic error handling and logging

📋 Phase 2: CV Parsing

• PDF parsing (pdf-parse)

• DOCX parsing (mammoth)

• Markdown parsing (marked)

• JSON/structured data parsing

• Unified CV data structure extraction

📋 Phase 3: Web Scraping

• LinkedIn job scraping with Playwright

• Generic job site scraping

• Rate limiting and caching

• Ethical scraping practices

📋 Phase 4: NLP & Keywords

• Keyword extraction using wink-nlp and retext

• Skill dictionary and categorization

• Keyword scoring and relevance ranking

• CV-job skill matching

📋 Phase 5: CV Modification

• Rule-based modification system

• Keywords section enhancement

• Bullet point enhancement

• Summary rewriting

• Multiple modification levels

📋 Phase 6: Document Generation

• PDF generation with pdf-lib

• DOCX generation with docx library

• Markdown generation

• Professional formatting

📋 Phase 7: Integration & Tools

• Wire all components into MCP tools

• Comprehensive error handling

• Input validation with Zod

📋 Phase 8: Testing, Documentation & Hebrew Support

• Unit tests for all components

• Integration tests

• Complete documentation

• Full Hebrew language support with RTL formatting

• Hebrew keyword dictionary (50+ translations)

• Language detection and metadata

• RTL-aware document generators

Ethics & Legal

This tool is designed for ethical use only:

• ✅ Only scrapes publicly accessible job postings

• ✅ Respects robots.txt and rate limiting

• ✅ Uses realistic delays to avoid detection

• ✅ Caches results to minimize scraping requests

• ✅ Does not persist user data

• ✅ All processing is local

Troubleshooting

General Issues

Issue: "Cannot find module" errors

Solution: Make sure dependencies are installed:

npm install
npx playwright install chromium

If you still get errors on Linux, you may need to install additional system libraries:

# Ubuntu/Debian
sudo apt-get update
sudo apt-get install -y python3 build-essential

# Fedora
sudo dnf install python3 gcc-c++

# macOS (using Homebrew)
brew install python3

Issue: Browser timeout errors

Solution: Increase BROWSER_TIMEOUT_MS in .env:

All Platforms:

BROWSER_TIMEOUT_MS=60000  # 60 seconds

On Windows, you can also increase the timeout temporarily:

$env:BROWSER_TIMEOUT_MS = "60000"
npm start

Issue: Rate limiting / scraping detection

Solution: Increase delay between requests:

All Platforms:

SCRAPER_MIN_DELAY_MS=10000  # 10 seconds

Issue: Port already in use (if running as service)

Solution: Check what's using the port and either stop that process or change the port:

Windows:

# Find process using port (requires admin)
netstat -ano | findstr :9000
# Kill the process
taskkill /PID <PID> /F

macOS/Linux/Unix:

# Find process using port
lsof -i :9000
# Kill the process
kill -9 <PID>

Issue: Permission denied errors

Solution:

Windows: Run Command Prompt or PowerShell as Administrator

macOS/Linux/Unix:

# Make scripts executable
chmod +x node_modules/.bin/*

# Or use sudo for npm install if needed
sudo npm install

Issue: Node.js command not found

Solution:

Ensure Node.js is installed and in your PATH:

Windows:

• Download from https://nodejs.org/

• Run the installer and ensure "Add to PATH" is checked

• Restart your terminal

macOS:

# Using Homebrew
brew install node

Linux (Ubuntu/Debian):

sudo apt-get update
sudo apt-get install nodejs npm

Linux (Fedora):

sudo dnf install nodejs npm

Verify installation:

node --version
npm --version

Hebrew Language Issues

Issue: Hebrew characters appear as squares or garbled

Solution:

• Ensure UTF-8 encoding in viewing application

• Update system fonts to include Hebrew font support

• Use modern applications that support Unicode (Word, modern browsers)

• Check document's HTML meta tags have proper lang="he" and dir="rtl"

Issue: RTL text still displays left-to-right

Solution:

• Verify application respects HTML dir attribute

• Check document metadata includes proper RTL markers

• Enable EMBED_RTL_MARKERS=true in .env configuration

• Review output in application that supports RTL content (Word, modern browsers)

Issue: Mixed Hebrew-English text malformed

Solution:

• Ensure EMBED_RTL_MARKERS=true in configuration

• Verify text encoding is UTF-8

• Check that text contains proper Unicode directional markers

• Enable debug logging: LOG_LEVEL=debug to diagnose issues

Issue: Hebrew keywords not detected

Solution:

• Check exact spelling of Hebrew words

• Verify text is properly encoded as UTF-8

• Review HEBREW_SUPPORT.md for list of supported keywords

• Enable debug logging to see detected language and composition

Performance

Expected performance metrics:

• CV parsing: < 5 seconds

• Job scraping: < 30 seconds

• Full modification pipeline: < 45 seconds

• CV parsing accuracy: > 95%

Future Enhancements

• AI-powered CV rewriting using Claude API

• Cover letter generation

• Additional language support (Arabic, French, Spanish, etc.)

• ATS optimization analysis

• Batch processing multiple CVs

• Analytics dashboard

• Hebrew date formatting and name parsing

• BiDi (Bidirectional) algorithm refinement

Documentation

This project includes comprehensive documentation:

• README.md - Quick start guide and basic usage (this file)

• PLATFORM_COMPATIBILITY.md - Detailed OS-specific setup for Windows, macOS, Linux, Unix, iOS, and Android

• MOBILE_USAGE.md - Complete guide to using the server from iOS and Android devices (remote access, tunneling, Termux, cloud deployment)

• HEBREW_SUPPORT.md - Complete Hebrew language feature documentation

• CLAUDE.md - Comprehensive feature reference and API documentation

Support

For issues or questions:

1. Mobile Usage (iOS/Android): See MOBILE_USAGE.md for setup guides and examples

2. OS-Specific Help: See PLATFORM_COMPATIBILITY.md for your operating system

3. Hebrew Language Help: See HEBREW_SUPPORT.md

4. Feature Documentation: Review CLAUDE.md

5. General Help: Check the GitHub Issues

6. Debugging: Enable debug logging with LOG_LEVEL=debug in .env

System Requirements by Operating System

Windows (10/11)

• Minimum RAM: 2 GB (4 GB recommended)

• Minimum Disk Space: 500 MB

• Node.js: 18.0.0 or later

• Required Components:

  • Build Tools for Visual Studio (optional, for native modules)

  • .NET Framework 4.5+ (for some system libraries)

• Supported Shells: PowerShell, Command Prompt, Windows Terminal

• Notes:

  • Uses backslashes for paths (e.g., C:\path\to\file)

  • Environment variables set differently in different shells

  • Run as Administrator may be needed for some operations

macOS

• Minimum Version: macOS 10.13 (High Sierra)

• Minimum RAM: 2 GB (4 GB recommended)

• Minimum Disk Space: 500 MB

• Node.js: 18.0.0 or later

• Required Components:

  • Xcode Command Line Tools: xcode-select --install

  • Homebrew (optional but recommended)

• Supported Shells: zsh (default), bash

• Notes:

  • Uses forward slashes for paths

  • Configuration files in ~/Library/Application Support/

  • May need to allow apps from "unidentified developers" in System Preferences

Linux

• Minimum RAM: 1 GB (2 GB recommended)

• Minimum Disk Space: 500 MB

• Node.js: 18.0.0 or later

• Required Components:

  • Build tools: gcc, g++, make, python3

  • Libraries for Playwright: libxss1, libxcomposite1, etc.

• Supported Distributions:

  • Ubuntu/Debian 18.04+

  • Fedora 30+

  • CentOS 7+

  • Arch Linux

  • openSUSE

• Notes:

  • Uses forward slashes for paths

  • May need to install additional system libraries

  • Often runs as non-root user

  • Configuration files in ~/.config/

Unix (FreeBSD, OpenBSD, etc.)

• Minimum RAM: 1 GB (2 GB recommended)

• Minimum Disk Space: 500 MB

• Node.js: 18.0.0 or later (available via ports/packages)

• Required Components:

  • Build tools: gcc, gmake, python3

  • Webkit libraries for Playwright

• Notes:

  • Uses forward slashes for paths

  • Requires ports/packages system to be updated

  • Some dependencies may need to be built from source

  • Sandbox restrictions may apply (OpenBSD)

Performance Considerations

Hardware Optimization

Low-Spec Machines (1-2 GB RAM):

• Reduce SCRAPER_MAX_CONCURRENT to 1

• Disable CACHE_ENABLED if storage is limited

• Use modificationLevel: "minimal" for CV modifications

Standard Machines (4-8 GB RAM):

• Default configuration works well

• Can run multiple concurrent jobs

High-End Machines (16+ GB RAM):

• Can increase SCRAPER_MAX_CONCURRENT to 2-3

• Cache will improve performance significantly

Expected Performance by OS

Performance depends on:

• Network speed (for web scraping)

• Disk speed (SSD vs HDD)

• System load

• Browser capabilities (Playwright)

License

MIT License - See LICENSE file for details

Changelog

v1.1.0 - Hebrew Language Support (Current)

Added:

• ✅ Full Hebrew language detection and support

• ✅ Right-to-Left (RTL) text formatting with proper indentation

• ✅ 50+ Hebrew skill dictionary with technical and soft skill translations

• ✅ Hebrew section header translations (Experience, Education, Skills, etc.)

• ✅ Mixed Hebrew-English content support with Unicode directional markers

• ✅ Hebrew-aware CV parsers and document generators

• ✅ RTL-aware Markdown generator

• ✅ Language detection as standard feature in CV parsing

• ✅ Comprehensive Hebrew support documentation

Improved:

• Enhanced CV metadata with language tracking

• Better text composition analysis for language detection

• Improved character encoding handling

v1.0.0 - Initial Release

• Phase 1-7: Complete MCP server implementation

• Three core MCP tools: extract_job_description, modify_cv, analyze_cv_job_match

• Support for PDF, DOCX, Markdown, and JSON CV formats

• Web scraping from LinkedIn and other job posting sites

• Keyword extraction and CV modification logic

• Multiple document output formats