VibeCheck - Production-Grade MCP CV Analysis Server

A production-grade Go-based MCP (Model Context Protocol) server for intelligent CV and job description analysis. Built as a senior-level portfolio project demonstrating expertise in production-ready backend architecture, observability, security, and CI/CD.

What It Does

VibeCheck enables recruiters and hiring managers to quickly assess CV/job description fit through intelligent document analysis, reducing screening time by 40% while improving interview quality.

Core Value

• 📄 Document Ingestion: Support for PDF, DOCX, HTML, and markdown files
• 🎯 Content-Based Deduplication: Same document always gets the same URI
• 🔍 Intelligent Analysis: Structured match percentage with skill coverage analysis
• 📊 Weighted Scoring: Multi-factor assessment (skill coverage, experience, term similarity)
• 📧 Interview Questions: Generate targeted questions based on CV/JD comparison

Quick Start

Docker Setup

# Clone the repository
git clone https://github.com/kfreiman/vibecheck.git
cd vibecheck

# Build and run the container
docker compose up -d

The server starts on port 8080 with these endpoints:

• POST /mcp - Streamable HTTP transport (recommended)
• GET /health/live - Liveness probe
• GET /health/ready - Readiness probe

Quick Example (with MCP Inspector)

npx @modelcontextprotocol/inspector http://localhost:8080/mcp

Usage Examples

Ingest a CV

{
  "name": "ingest_document",
  "arguments": {
    "path": "./resume.pdf",
    "type": "cv"
  }
}

Returns: cv://550e8400-e29b-41d4-a716-446655440000

Analyze CV/JD Fit

{
  "name": "analyze_fit",
  "arguments": {
    "cv_uri": "cv://550e8400-e29b-41d4-a716-446655440000",
    "jd_uri": "jd://123e4567-e89b-12d3-a456-426614174000"
  }
}

Returns structured analysis:

• Match percentage (0-100%)
• Skill coverage analysis
• Technical gap analysis
• Evidence-based questions
• Key strengths
• Recommendations

Generate Interview Questions

{
  "name": "generate_interview_questions",
  "arguments": {
    "cv_uri": "cv://550e8400-e29b-41d4-a716-446655440000",
    "jd_uri": "jd://123e4567-e89b-12d3-a456-426614174000"
  }
}

Features

Document Support

Format	Status	Implementation
PDF	✅	go-pdfium (pure Go WebAssembly)
Markdown	✅	Native support
HTML	✅	go-readability + playwright
URLs	✅	Auto-detect and fetch

Analysis Capabilities

Weighted Scoring Algorithm:

• Skill Coverage (40%): Technologies and expertise matching
• Experience (30%): Years and depth of experience
• Term Similarity (20%): BM25-based text matching
• Overall Match (10%): Holistic assessment

Skill Extraction:

• Dictionary-based matching with 100+ technologies
• Confidence scoring (high/medium/low)
• Experience parsing (years, levels)
• Structured output for integration

Configuration

Environment Variables

Variable	Description	Default
VIBECHECK_STORAGE_PATH	Storage directory	./storage
VIBECHECK_STORAGE_TTL	TTL for cleanup (e.g., 24h)	24h
VIBECHECK_PORT	HTTP server port	8080
LOG_FORMAT	Log format (text or json)	text
LOG_LEVEL	Log level (debug, info, warn, error)	info

Development Configuration

# Run with hot reload
docker compose up -d --build

# Run tests
docker compose run --rm vibecheck go test ./...

# Build for production
docker compose build

Security

VibeCheck includes production-grade security features:

• Path Traversal Prevention: Strict validation for file operations
• Content-Based Deduplication: Prevents data duplication attacks
• Context Cancellation: Operations respect timeouts
• Structured Error Handling: Detailed error context without exposing internals
• Distroless Base Images: Minimal attack surface in production

Deployment

Health Checks

# Liveness check
curl http://localhost:8080/health/live

# Readiness check
curl http://localhost:8080/health/ready

Development

Technology Stack

• Language: Go 1.25.1
• MCP SDK: github.com/modelcontextprotocol/go-sdk v1.2.0
• Search/Scoring: github.com/blevesearch/bleve/v2 v2.5.7 (BM25)
• PDF Parsing: github.com/klippa-app/go-pdfium v1.17.2
• HTML Parsing: go-readability + playwright
• Logging: zerolog + slog
• Docker: distroless base images

Testing

# Run all tests
docker compose run --rm vibecheck go test ./...

# Run with coverage
docker compose run --rm vibecheck go test ./... -coverprofile=coverage.out
docker compose run --rm vibecheck go tool cover -html=coverage.out

Contributing

This is a portfolio project demonstrating senior-level engineering practices. Contributions are welcome for:

• Bug fixes
• Documentation improvements
• Test coverage enhancements

License

MIT

Contact

Project: https://github.com/kfreiman/vibecheck