# CV Writer MCP Server - Revolutionary Research-Driven System

A Model Context Protocol (MCP) server that uses **20+ years of psychological research** to intelligently generate scientifically-optimized CVs. The system leverages research on the 7.4-second attention window, cognitive psychology, cultural intelligence, and eye-tracking studies to create perfect CVs for any job.

## 🧠 Revolutionary Intelligence-Driven Architecture

This system has been completely transformed from template-based to **research-driven CV generation**:

```
📚 RESEARCH INTELLIGENCE ENGINE
├── Psychology Core: 7.4-second window optimization
├── Timing Optimization: Peak-end rule, anchoring bias
├── Cultural Intelligence: DACH, Nordic, US/UK adaptation  
├── Visual Optimization: F/Z-patterns, typography psychology
└── Cognitive Load: 4±1 sections rule, working memory limits

        ↓ Applied Dynamically ↓

🎯 SCIENTIFIC CV GENERATION
├── Job Analysis → Research-driven strategy selection
├── Cultural Adaptation → Region-specific optimization  
├── Content Intelligence → YAML ordering preserved
└── HTML-First Output → Perfect WYSIWYG rendering
```

## 📌 Complete MCP Tool Usage Guide

### 🚀 Complete Copy-Paste Usage Examples

**Copy these EXACT prompts for reliable tool triggering:**

#### **1️⃣ Primary Workflow - Job Description to CV**
```
I found this job posting:

[Paste job posting content here]

Use the smart_cv_generator tool to create a CV for this job.
```

#### **2️⃣ Save Your CV (WYSIWYG)**
```
Use the save_current_cv tool to save this CV to my output folder.
```

#### **3️⃣ Alternative CV Generation**
```
Use the smart_cv_generator tool for Senior Software Engineer at TechCorp.
```

#### **4️⃣ Experience Management**
```
Use the list_experiences tool to show my work history.
```
```
Use the search_experiences tool to find experience with cloud architecture and AWS.
```

#### **5️⃣ Job Analysis & Interview Prep**
```
Use the analyze_job_with_research tool for this Senior Developer role at Microsoft.
```
```
Use the answer_job_question tool to answer: Tell me about a time you led a challenging technical project.
```

#### **6️⃣ System Management**
```
Use the reload_knowledge_base tool to update my research intelligence.
```
```
Use the get_pdf_generation_status tool to check PDF capabilities.
```

#### **7️⃣ Quick Help**
```
Use the cv_help tool to show available tools and usage.
```

### 🌍 Real-World Usage Example: German Job Application

**Complete workflow example you can copy-paste:**

```
I found this Senior Solutions Architect role in Germany:

[Company]: Siemens AG
[Location]: Munich, Germany 
[Role]: Senior Solutions Architect - Cloud Infrastructure
[Requirements]: AWS, Kubernetes, German language preferred, 5+ years experience

Use the analyze_job_with_research tool for this Siemens Senior Solutions Architect role.
```

**Then after analysis:**
```
Use the smart_cv_generator tool to create a CV for this German Siemens position.
```

**Finally save it:**
```
Use the save_current_cv tool to save this CV.
```

**What happens automatically:**
1. ✅ Applies DACH cultural intelligence (photo section, 2-3 pages acceptable)
2. ✅ Uses 7.4-second attention window optimization  
3. ✅ Applies F-pattern layout for technical roles
4. ✅ Implements peak-end rule for achievement placement
5. ✅ Generates perfect HTML with research-based design
6. ✅ Preserves your exact YAML work experience order

### 🔧 System Commands

```bash
# Initial Setup
cd "/Users/dk/MEGA/Obsidian-Vault/CV, Jobs, work/cv-writer-MCP"
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

# Daily Use
source venv/bin/activate      # Activate environment
python server.py               # Run MCP server (if testing standalone)

# In Claude Desktop - Connection Test
"Can you list my MCP tools?"   # Test MCP connection
"Use the cv_help tool"         # Show available tools and usage
```

### ⚡ Pro Tips for Tool Auto-Triggering

1. **Use the word "tool"** in your request: "Use the smart_cv_generator tool"
2. **Be specific about which tool**: Don't just say "generate CV", say "Use the smart_cv_generator tool"  
3. **For job analysis**: Include both company and role name for better results
4. **For saving**: Always use "Use the save_current_cv tool" for WYSIWYG saving

### 🎯 Bulletproof System Guarantees

- ✅ **YAML Order Preserved**: Your work experience order from config file is NEVER changed
- ✅ **Zero Artificial Gaps**: Browser handles ALL spacing naturally - no forced margins, padding, or page breaks
- ✅ **Auto-Sync Artifacts**: CV files automatically update when artifact changes - always in perfect sync
- ✅ **True WYSIWYG**: Saved files match exactly what you see in Claude's artifact
- ✅ **Research-Driven**: Automatically applies 20+ years of hiring psychology research
- ✅ **Cultural Intelligence**: Adapts for DACH/Nordic/US/UK hiring practices

## 🏗️ Architecture Overview

This system follows **data-code separation** with revolutionary intelligence integration:

```
CV, Jobs, work/                           # Your career management workspace
├── cv-writer-MCP/                        # 📦 This project (versioned code)
│   ├── server.py                         # Main MCP server
│   ├── tools/                            # Intelligence & CV tools
│   │   ├── knowledge_base.py             # 🧠 Research Intelligence Engine
│   │   ├── experience_manager.py         # Work history (YAML order preserved)
│   │   └── html_renderer.py              # Research-driven HTML generation
│   ├── personal_config.yaml              # Intelligence sources configuration
│   └── requirements.txt                  # Dependencies
├── Research - *.md                       # 📊 20+ years psychological research
│   ├── The Invisible Psychology of CV Design.md
│   ├── Comprehensive CV optimization strategies.md
│   └── CV Design Research Report.md
├── Work Experience Metadata/             # 📝 Your work history (persistent data)
│   ├── 2025-current-role.md             # Experience files (newest first)
│   └── 2023-previous-role.md
└── output/                               # 📄 Generated research-optimized CVs
```

**Why This Revolutionary Design:**
- ✅ **Research-Driven**: Uses 20+ years of hiring psychology research
- ✅ **7.4-Second Window**: Optimized for recruiter attention patterns
- ✅ **Cultural Intelligence**: Adapts to DACH, Nordic, US/UK expectations
- ✅ **Pure HTML Generation**: Clean HTML output with Python-based PDF generation
- ✅ **Intelligence-Based**: Path-based research loading for precise control

## 🏗️ Code Architecture

### Core System Components

```
cv-writer-MCP/
├── server.py                               # Main MCP server with all tool endpoints
├── tools/                                  # Core functionality modules
│   ├── intelligence/
│   │   ├── knowledge_base.py              # Research intelligence engine
│   │   └── research extraction & application
│   ├── content/
│   │   ├── experience_manager.py          # Work history with YAML order preservation
│   │   ├── content_trimmer.py             # Page limits while preserving order
│   │   └── config_manager.py              # Personal info & preferences
│   ├── generation/
│   │   ├── html_renderer.py               # Pure HTML generation with research CSS
│   │   ├── pdf_generator.py               # Python-based PDF (weasyprint/xhtml2pdf)
│   │   └── job_analyzer.py                # Job posting analysis with cultural context
│   ├── qa/
│   │   └── job_qa_manager.py              # Interview question answering system
│   └── utilities/
│       ├── file_reader.py                 # File system operations
│       ├── date_utils.py                  # Date sorting & validation
│       └── error_utils.py                 # Error handling & logging
├── personal_config.yaml                   # User configuration (data-code separation)
├── requirements.txt                       # Python dependencies
└── PDF_SETUP.md                          # PDF generation setup instructions
```

### Data Flow Architecture

```
1. Job Analysis
   ├── job_analyzer.py → Cultural context detection (DACH/Nordic/US/UK)
   └── Research intelligence → Strategy selection based on context

2. Content Assembly  
   ├── experience_manager.py → Preserve EXACT YAML chronological order
   ├── content_trimmer.py → Apply limits while maintaining order
   └── Research rules → Psychology-driven content prioritization

3. HTML Generation
   ├── html_renderer.py → Research-driven CSS generation
   ├── Cultural context → Regional styling (photos, length, tone)
   └── Job context → Creative mode selection (minimal/conservative/moderate)

4. PDF Generation (Optional)
   ├── pdf_generator.py → Pure Python PDF generation
   ├── weasyprint (preferred) → Best CSS support
   ├── xhtml2pdf (fallback) → Simpler alternative
   └── Graceful failure → Always save HTML, show clear error messages
```

### MCP Tool Architecture

**Core CV Generation:**
- `generate_cv_html()` - Main HTML generation with research intelligence
- `generate_cv_html_artifact()` - Claude artifact display version
- `generate_complete_cv()` - Full pipeline with job analysis

**Experience Management:**
- `list_experiences()` - YAML order preserved
- `search_experiences()` - Keyword matching with relevance scoring
- `get_tiered_experiences()` - Detailed vs brief assignment

**Intelligence System:**
- `reload_knowledge_base()` - Dynamic research file reloading
- `preview_research_intelligence()` - Show applied research rules
- `get_pdf_generation_status()` - Check PDF capabilities

**Job Analysis:**
- `analyze_job_posting()` - Cultural context + requirements extraction
- `answer_job_question()` - STAR format answers from experience data

### Research Intelligence Integration

```python
# Path-based intelligence loading (personal_config.yaml) - ABSOLUTE paths required
intelligence_sources:
  psychology_core: "/Users/yourname/Documents/CV-Data/Research - Psychology.md"
  cultural_patterns: "/Users/yourname/Documents/CV-Data/Research - Cultural.md"

# Dynamic rule extraction and application
knowledge_base.py:
├── ResearchRuleExtractor → Parse research files for actionable rules
├── IntelligenceEngine → Apply rules based on job/cultural context
└── Rule categories: timing, cognitive, visual, cultural, psychology
```

## Features

- 🧠 **Research Intelligence Engine**: Applies 20+ years of psychological research automatically
- ⏱️ **7.4-Second Optimization**: CVs optimized for recruiter attention window
- 🎯 **Job-Specific CV Generation**: Analyzes job postings with cultural intelligence
- 📁 **Experience Management**: Preserves exact YAML ordering (newest first)
- 🎨 **Pure HTML Rendering**: Research-driven design with Python-based PDF generation
- 🌍 **Cultural Adaptation**: DACH photos, Nordic minimalism, US/UK standards
- 🔍 **Smart Experience Matching**: Psychology-driven content prioritization
- 📊 **F/Z-Pattern Layouts**: Eye-tracking optimized visual hierarchy
- 🧠 **4±1 Sections Rule**: Cognitive load optimization for working memory
- 🏆 **Peak-End Effect**: Strategic placement of best achievements
- ⚡ **Instant Intelligence Reload**: Dynamic research file updates

## 🚀 Complete Setup Guide (Start to Finish)

### Prerequisites
- Python 3.8+ installed
- Claude Desktop app installed

### Step-by-Step Setup

**1️⃣ Clone/Download and Navigate to Project**
```bash
cd "/Users/dk/MEGA/Obsidian-Vault/CV, Jobs, work/cv-writer-MCP"
```

**2️⃣ Create and Activate Virtual Environment**
```bash
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
```

**3️⃣ Install Dependencies**
```bash
pip install -r requirements.txt

# This installs:
# - MCP framework (FastMCP)
# - Research intelligence tools (YAML, markdown)
# - Python-based PDF generation (weasyprint, xhtml2pdf)
# - No external tools or LaTeX dependencies needed!
```

**4️⃣ Configure Personal Information**

⚠️ **CRITICAL: ABSOLUTE PATHS ONLY**

The system **requires ABSOLUTE paths** for all file and directory references:
- ✅ `/Users/username/Documents/CV-Data/output`
- ✅ `C:/Users/username/Documents/CV-Data/output`
- ❌ `../output` (relative paths NOT supported)
- ❌ `output` (relative paths NOT supported)

```bash
# 1. Copy example config:
cp example_personal_config.yaml personal_config.yaml

# 2. Edit personal_config.yaml with ABSOLUTE paths:
# - Personal info (name, email, education, certifications)
# - Work experience file paths (ABSOLUTE, in EXACT YAML order)
# - Intelligence sources (ABSOLUTE research file paths)
# - Output directories (ABSOLUTE paths)
```

⚠️ **IMPORTANT: Path Configuration**

All paths in your configuration **MUST be absolute paths**:

```yaml
# In personal_config.yaml - ABSOLUTE PATHS REQUIRED
paths:
  work_experience_base: /Users/yourname/Documents/CV-Data
  output: /Users/yourname/Documents/CV-Data/output
  research_base: /Users/yourname/Documents/CV-Data

intelligence_sources:
  psychology_core: "/Users/yourname/Documents/CV-Data/Research - Psychology.md"
  timing_optimization: "/Users/yourname/Documents/CV-Data/Research - Optimization.md"
  cultural_patterns: "/Users/yourname/Documents/CV-Data/Research - Cultural.md"

work_experiences:
  - company: "Company Name"
    title: "Job Title"
    start_date: "Jan 2023"
    end_date: "Present"
    content_file: "/Users/yourname/Documents/CV-Data/experiences/2023-job.md"

preferences:
  job_qa_file: "/Users/yourname/Documents/CV-Data/Job Application QA.md"

intelligence_config:
  enable_psychology_optimization: true    # 7.4-second window, peak-end rule
  enable_cultural_intelligence: true      # DACH, Nordic, US/UK adaptation
  enable_timing_optimization: true        # Attention span, cognitive load
  enable_visual_optimization: true        # F/Z-patterns, typography psychology
```

**5️⃣ Work Experience Files (YAML Order Preserved)**
List your experience files with **ABSOLUTE paths** in **exact chronological order** (newest first):
```yaml
work_experiences:
  - content_file: "/Users/yourname/Documents/CV-Data/2025 - Current Role.md"
  - content_file: "/Users/yourname/Documents/CV-Data/2023 - Previous Role.md"
  # EXACT order from YAML - NO automatic sorting!
  # ALL paths MUST be ABSOLUTE
```

**6️⃣ Configure Claude Desktop**
Create/edit `~/Library/Application Support/Claude/claude_desktop_config.json`:
```json
{
  "mcpServers": {
    "cv-writer": {
      "command": "/full/path/to/your/project/venv/bin/python3",
      "args": ["/full/path/to/your/project/server.py"],
      "env": {}
    }
  }
}
```

**7️⃣ Restart Claude Desktop**
Quit and reopen Claude Desktop completely

**8️⃣ Test the Research Intelligence**
In Claude Desktop, ask: "Can you preview my research intelligence?"

## 🧠 Research Intelligence Features

### 🎯 Available MCP Tools (8 Essential Tools)

**Successfully consolidated from 30 tools to 8 focused, essential tools! (73% reduction)**

#### Core CV Generation (2 tools)
- `generate_cv_html()` - Main research-driven CV generation with job analysis
- `generate_cv_html_artifact()` - Claude artifact display version

#### Experience Management (2 tools)
- `list_experiences()` - View work history in EXACT YAML order
- `search_experiences(keywords)` - Find relevant experience by skills/keywords

#### Job Analysis & Q&A (2 tools)
- `answer_job_question()` - Generate STAR-format answers from experience data
- `analyze_job_with_research()` - Job analysis + research intelligence (enhanced)

#### System Tools (2 tools)
- `reload_knowledge_base()` - Reload research files for latest psychology insights
- `get_pdf_generation_status()` - Check PDF generation capabilities

### Essential Commands (Consolidated Toolset)

**For reliable tool triggering, use the specific tool names:**

- `"Use the smart_cv_generator tool for [job title] at [company]"` - Main CV generation with research
- `"Use the save_current_cv tool"` - Save current CV artifact (WYSIWYG)
- `"Use the list_experiences tool"` - Shows work history in exact YAML order
- `"Use the search_experiences tool for [keywords]"` - Finds relevant experience
- `"Use the analyze_job_with_research tool for [company] [role]"` - Enhanced job analysis with psychology
- `"Use the answer_job_question tool to answer: [question]"` - Generate STAR-format answers
- `"Use the reload_knowledge_base tool"` - Update research intelligence
- `"Use the get_pdf_generation_status tool"` - Verify PDF capabilities

**Why specify tool names?** MCP tools need explicit invocation for reliable triggering. Just saying "generate CV" might not always activate the tool automatically.

## 🎯 Revolutionary System Benefits

### Before (Legacy System):
- ❌ **30 confusing tools** (too many choices)
- ❌ Static template files
- ❌ Manual design decisions
- ❌ Generic one-size-fits-all approach
- ❌ No psychological optimization
- ❌ Cultural guesswork
- ❌ Complex external dependencies

### After (Consolidated & Research-Driven):
- ✅ **8 focused tools** (73% reduction for clarity)
- ✅ **20+ years of research** automatically applied
- ✅ **7.4-second attention window** optimization  
- ✅ **Cultural intelligence** for regions (DACH/Nordic/US/UK)
- ✅ **Psychology techniques**: Peak-end, halo effect, anchoring
- ✅ **F/Z-pattern layouts** based on eye-tracking studies
- ✅ **4±1 sections rule** for cognitive load optimization
- ✅ **Perfect HTML rendering** with WYSIWYG control
- ✅ **YAML order preservation** for exact control
- ✅ **Streamlined UX** - Easy tool selection for Claude

## Creating Experience Files

Experience files use markdown with metadata:

```markdown
---
title: Senior Solutions Architect
company: University of Innsbruck  
location: Innsbruck, Austria
duration: Jan 2023 - Dec 2023
start_date: "2023-01"
end_date: "2023-12"
---

## Overview
Led cloud infrastructure transformation...

## Key Achievements
- Reduced infrastructure costs by 40% through AWS optimization
- Designed multi-region architecture serving 50,000+ users
- Led team of 8 engineers across 3 countries

## Technologies
AWS, Kubernetes, Terraform, Python, Docker, PostgreSQL

## Projects
### Cloud Migration Initiative
Architected and executed complete data center to cloud migration...
```

## Troubleshooting

### 🔧 MCP Connection Issues
1. Check `claude_desktop_config.json` has correct paths
2. Restart Claude Desktop completely
3. Test: `"Can you list my MCP tools?"`
4. Test: `"Use the cv_help tool"` for quick tool reference

### 🧠 Tools Not Auto-Triggering
**Most common issue: Not using explicit tool names**

❌ **These might not work reliably:**
- "Generate a CV for this job"
- "Create a CV" 
- "Make a resume"

✅ **These work consistently:**
- `"Use the smart_cv_generator tool for this job"`
- `"Use the save_current_cv tool"`
- `"Use the list_experiences tool"`

### 🧠 Intelligence System Issues
1. Verify research files exist at configured paths
2. Test: `"Use the reload_knowledge_base tool"`
3. Debug: `"Use the analyze_job_with_research tool"` to see if research applies

### 📋 YAML Order Issues
1. Check `work_experiences` list in `personal_config.yaml`
2. Verify files are listed newest-first
3. Test: `"Use the list_experiences tool"` (should show exact YAML order)
4. **System guarantee**: Order is NEVER changed automatically

### 💾 WYSIWYG Saving Issues
- **Remember**: Files only save when you explicitly request it
- Use: `"Use the save_current_cv tool"` 
- **System guarantee**: Saves exactly what you see in the artifact

## Development

### Adding New Research Sources
1. Add research files to intelligence_sources in `personal_config.yaml`
2. Reload intelligence: `reload_knowledge_base()`
3. Test extraction: `preview_research_intelligence()`

### Intelligence Source Types
- **psychology_core**: Core hiring psychology (always applied)
- **timing_optimization**: 7.4-second window, attention span
- **cultural_patterns**: Regional adaptation rules
- **visual_optimization**: F/Z-patterns, typography psychology

## Technical Details: Research Intelligence Engine

### Rule Extraction System
The system automatically extracts actionable rules from research markdown files:
- **Timing Rules**: 7.4-second window, evaluation patterns
- **Cognitive Rules**: 4±1 sections, working memory limits
- **Visual Rules**: F-pattern, Z-pattern, eye-tracking insights  
- **Cultural Rules**: DACH photos, Nordic minimalism, US/UK standards
- **Psychology Rules**: Peak-end effect, halo effect, anchoring bias

### Path-Based Intelligence Loading (ABSOLUTE paths required)
```yaml
intelligence_sources:
  psychology_core: "/Users/yourname/Documents/CV-Data/Research - Psychology File.md"
  cultural_patterns: "/Users/yourname/Documents/CV-Data/Research - Cultural Intelligence.md"
  timing_optimization: "/Users/yourname/Documents/CV-Data/Research - Timing Research.md"
```

### Dynamic Intelligence Application
The system applies different research based on:
- **Job analysis context** (technical vs sales vs management)
- **Target region** (DACH vs Nordic vs US/UK)  
- **Role seniority** (entry-level vs senior vs executive)
- **Industry type** (tech vs finance vs healthcare)

## License

MIT License - See LICENSE file for details

---

🧠 Built with Revolutionary Research Intelligence using the Model Context Protocol (MCP)