MCP 服务器

CV Writer MCP Server

A research-driven MCP server that uses 20+ years of psychological research to generate scientifically-optimized CVs tailored to any job and cultural context.

README

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:

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

🔧 System Commands

# 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

Use the word "tool" in your request: "Use the smart_cv_generator tool"
Be specific about which tool: Don't just say "generate CV", say "Use the smart_cv_generator tool"
For job analysis: Include both company and role name for better results
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

# 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

cd "/Users/dk/MEGA/Obsidian-Vault/CV, Jobs, work/cv-writer-MCP"

2️⃣ Create and Activate Virtual Environment

python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

3️⃣ Install Dependencies

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)

# 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:

# 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):

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:

{
  "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:

---
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

Check claude_desktop_config.json has correct paths
Restart Claude Desktop completely
Test: "Can you list my MCP tools?"
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

Verify research files exist at configured paths
Test: "Use the reload_knowledge_base tool"
Debug: "Use the analyze_job_with_research tool" to see if research applies

📋 YAML Order Issues

Check work_experiences list in personal_config.yaml
Verify files are listed newest-first
Test: "Use the list_experiences tool" (should show exact YAML order)
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

Add research files to intelligence_sources in personal_config.yaml
Reload intelligence: reload_knowledge_base()
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)

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)