Create, validate, and render CV PDFs from plain YAML — fully local, no accounts.
The MCP server io.github.hrtips/cvx creates, validates, and renders CV (curriculum vitae) PDFs from plain YAML. It operates fully locally and does not require accounts. The server focuses on transforming structured YAML input into PDF output, including validation steps prior to rendering.
🛠️ Key Features
Create CV PDFs from plain YAML
Validate YAML input
Render CV output as PDFs
Fully local operation (no accounts)
🚀 Use Cases
Generate CV PDFs from YAML-based data
Validate CV data before producing a final PDF
⚡ Developer Benefits
Local workflow without account setup
YAML-to-PDF pipeline with validation
⚠️ Limitations
Only supports CV PDF creation from plain YAML (no other input formats described)
CVX turns plain YAML into a professionally designed CV PDF — one command, fully local, no accounts; your data never leaves your machine. Use it two ways: edit the YAML yourself, or have any AI assistant write it for you from your existing CV — CVX validates the files and tells the assistant exactly what to fix.
🤖 AI assistants: if a user asked you to create their CV with CVX, follow the default flow in the AI guide (section "Default flow (for assistants)"). Non-negotiables even if you skip the link: never invent facts — every entry must be truthful to the user's input; linkedin.com URLs are unfetchable even when public — don't infer, ask for the profile's More → Save to PDF export or pasted text instead; ask for a square photo in your first reply (it can't be generated; the CV renders fine without one); and CVX is the only renderer — never substitute another PDF generator.
No terminal? No problem. Paste this into any AI chat (Claude, ChatGPT, Gemini, …):
text
Create my CV with https://github.com/hrtips/cvx — open that page and follow its instructions for AI assistants.
Here is my LinkedIn profile: <your profile URL> (or attach your current CV and a photo instead).
The scaffolded example CV, exactly as npx @hrtips/cvx build renders it — plus an ATS-safe single-column variant via --ats.
Create your CV in two minutes
bash
npx @hrtips/cvx init # scaffold cv-content/ with a complete example CV
npx @hrtips/cvx build # render it to a PDF
init gives you a finished, working CV — Bruce Wayne's, and yes, really. Open bruce-wayne.pdf and you're looking at a designed two-page CV: photo, sidebar, achievements, the lot.
Now make it yours. Open the cv-content/ folder, and replace Bruce's details with your own, one file at a time:
code
cv-content/
personal.yaml ← start here: your name, title, contact details
summary.yaml ← the bullet points at the top of page 1
experience.yaml ← your work history (the bulk of the CV)
education.yaml ← degrees, institutions, years
competencies.yaml ← skill pills in the sidebar
achievements.yaml ← awards and recognitions
referees.yaml ← referees, or [] for "available upon request"
images/profile.jpg ← your photo (square, 400×400px or larger)
Re-run npx @hrtips/cvx build after each file and watch the PDF update — seeing Bruce's entry next to yours makes the format self-explanatory. The output file is named after you automatically (jane-doe.pdf).
Made a typo or unsure a file is right? npx @hrtips/cvx validate checks everything at once and tells you exactly what to fix:
code
cv-content/personal.yaml
⚠ unknown key "linkdin"
↳ did you mean "linkedin"?
Every scaffolded file also carries a $schema header, so editors with YAML support (VS Code + the YAML extension, JetBrains, …) autocomplete keys and flag mistakes as you type.
Applying through a job portal? Generate the ATS-safe variant too — single column, no colours, machine-friendly:
bash
npx @hrtips/cvx build --ats
CLI reference
Command
Does
npx @hrtips/cvx init
Scaffold cv-content/ with the example CV (won't overwrite an existing one)
npx @hrtips/cvx validate
Check cv-content/ — every problem at once, with file + field paths and fixes
npx @hrtips/cvx validate --strict
Also fail on warnings (unknown keys); recommended for agents/CI
npx @hrtips/cvx build
Render cv-content/ to <your-name>.pdf
npx @hrtips/cvx build --ats
Render the ATS-safe single-column variant
npx @hrtips/cvx list
Show available themes and layouts
npx @hrtips/cvx --help / --version
Help / version
All commands accept --json for machine-readable output (one JSON object on stdout, logs on stderr) and use semantic exit codes: 0 ok, 2 validation failed, 3 render failed, 64 usage error. init is a convenience, not a prerequisite — build renders any cv-content/ folder with valid YAML (built-in themes and layouts need no extra files).
Compatibility promise: content files are versioned by schemaVersion in config.yaml (currently 1) and validated against the canonical JSON Schema. Within a schema major version, your content files never break — new keys may appear, existing ones keep working. npx @hrtips/cvx validate on today's files will still pass on every future 1.x release.
What goes in each file
These are excerpts from the scaffolded example — build it once and you can see exactly where each snippet lands on the page.
summary.yaml — the bullet list at the top of page 1:
yaml
-"Strategic operations leader with 20+ years' experience, progressing from solo field operative to Field Commander of a citywide security network."-"Co-founded the Justice League as a global response coalition, serving as chief strategist and contingency planner for existential-scale threats."
Delete what you don't need — an empty file (or []) simply drops that section from the CV. Any new .yaml file you drop into cv-content/ is auto-discovered as a content key.
The complete field-by-field schema for every file lives in docs/cv-schema.md.
Let an AI write the YAML for you
The formats are deliberately LLM-friendly, and the schema is published for machines (llms.txt, docs/cv-schema.md). The AI guide has copy-paste prompts for every route; the short version:
Coding agent (Claude Code, Cursor, …) — lowest friction: run npx @hrtips/cvx init, then ask the agent to replace the example content with your details and build. The scaffolded cv-content/README.md documents the schema, so the agent edits, runs npx @hrtips/cvx build, and fixes errors itself.
Chat assistant (Claude, ChatGPT, …) — paste your existing CV or LinkedIn profile text along with this prompt:
Read the CVX content schema at https://raw.githubusercontent.com/hrtips/cvx/main/docs/cv-schema.md then convert my CV below into CVX cv-content/ YAML files. Output each file in its own fenced code block titled with the filename. Keep every fact truthful to my input — don't invent anything.
Save the generated files into cv-content/, drop in your photo, run npx @hrtips/cvx build. No web access in your assistant? Use the self-contained prompt.
Plug it into your agent (MCP)
CVX ships an MCP server — any MCP client (Claude Desktop, Claude Code, Cursor, VS Code, …) can drive the whole loop with four tools: get_schema, init_cv, validate_cv, build_pdf. No API keys, fully offline.
Then restart the client and ask it to make your CV — it fetches the schema, scaffolds, fills in your details, validates after every edit, and renders the PDF. The config writer merges into existing files; it never clobbers other servers. There's also a ready-made Agent Skill with the same loop for skill-capable agents.
Your photo
Drop it into cv-content/images/ as profile.<ext> — jpg, jpeg, png, or webp are auto-detected (that order wins if several exist). Square crop, at least 400×400px.
Themes, layouts, and page flow
Everything visual is controlled by cv-content/config.yaml:
yaml
theme:teal# teal | coral | monolayout:two-column# two-column | single-columnpage1ExperienceCount:2# experience entries on page 1page1SplitBullets:2# split the last entry: N bullets on page 1, rest continue
Change a value, re-run npx @hrtips/cvx build, done.
Themes control colour and styling:
Theme
Accent
Description
teal
#1a6070
Professional teal (default)
coral
#c0534a
Warm coral red
mono
#000000
Black and white, ATS-optimised
Layouts control page structure:
Layout
Structure
Description
two-column
Sidebar + main column
Designed CV with photo, identity block, achievements
single-column
Full width
ATS-safe, no sidebar, no decorative elements
Pagination — experience entries are distributed across pages automatically (greedy bin-packing). Set page1ExperienceCount / page1SplitBullets to control page 1 explicitly. Example with 6 entries and the config above:
Both PDFs embed a keyword list into the standard Keywords metadata field — the field some applicant tracking systems (ATS) and AI CV parsers read. Keywords live in metadata, not as hidden text on the page.
Reality check: most mainstream ATS rank on text extracted from the CV body, and support for the PDF Keywords/XMP field is inconsistent. Treat this as a best-effort supplement to a keyword-rich body — not a substitute, and not a reliable ranking lever on its own. Keep every keyword truthful; stuffing false or irrelevant terms causes a metadata/body mismatch that gets a CV auto-rejected.
Keywords come from two sources, merged and de-duplicated (body-derived terms first):
Auto-derived from your competencies.yaml and job titles (company names are deliberately excluded as low-signal).
Curated in cv-content/keywords.yaml — a flat list, or grouped under headings:
atsKeywords:enabled:true# master switch (default: true)autoDerive:true# also derive from competencies + job titles (default: true)max:40# optional cap; body-derived terms are kept first (default: all)
For developers
Everything below is about hacking on CVX itself — custom themes, the rendering pipeline, and contributing. You don't need any of it to create a CV.
Working from a clone
bash
git clone git@github.com:hrtips/cvx.git
cd cvx
npm install
npm run dev # live browser preview at http://localhost:5173
npm run pdf # generate PDF (same pipeline as `cvx build`)
npm run pdf:ats # generate the ATS variant
npm test# unit tests
npm run build:lib # build the publishable lib/ (what the CLI runs)
The repo's cv-content/ carries the same Bruce Wayne example, so a clone builds out of the box. A photo crop helper is included: python3 scripts/crop-profile.py path/to/photo.jpg.
Custom themes
Themes ship inside the package, so custom themes currently require working from a clone — the npx CLI offers the three built-ins.
Drop a .js file in src/pdf/themes/ — it's auto-discovered, no registration needed:
Convention over registration — drop a file in the right folder and it's picked up:
What
Where to drop it
How it's found
Content
cv-content/*.yaml
Any .yaml file (except config.yaml) becomes a content key matching its filename
Themes
src/pdf/themes/*.js
Any .js file exporting an object with a name property
Layouts
cv-content/layouts/*.yaml
Any .yaml file with a template and pages structure
Profile photo
cv-content/images/profile.*
First match of .jpg, .jpeg, .png, .webp
To add a whole new content section (e.g. publications): create cv-content/publications.yaml (auto-available as content.publications), build a section component in src/pdf/sections/, register it in registry.js, then reference it from a layout.
Architecture
Three concerns, independently swappable:
code
Content (YAML) × Theme (JS) × Layout (YAML)
↓ ↓ ↓
what to say how it looks where it goes
The rendering pipeline:
code
config.yaml → resolves theme + layout
↓
cv-content/*.yaml → auto-loaded into data bag
↓
layout.js → packs experience entries across pages (using theme metrics)
↓
CVDocument → picks template (TwoColumn or SingleColumn)
↓
template → renders slots from layout config via section registry
↓
sections → read theme from React context, render content
↓
@react-pdf/renderer → PDF buffer → file
Unit tests cover the pure logic modules — keyword building, page packing, sidebar resolution, reproducibility helpers, and the profile-photo picker. Tests live next to the code they cover (src/pdf/*.test.js) plus test/ for cross-cutting checks. CI runs the suite on Linux and macOS across Node 20/22/24 (plus Windows on Node 22), then packs the tarball and exercises the installed CLI end-to-end, including a byte-identical reproducibility gate.
Reproducible builds
Set SOURCE_DATE_EPOCH (seconds since the Unix epoch) to make PDF output byte-identical run after run — useful for CI checks and for verifying that a content change is the only thing that changed:
bash
SOURCE_DATE_EPOCH=$(git log -1 --format=%ct) npx @hrtips/cvx build # or npm run pdf
This pins the PDF's CreationDate (and with it the trailer file ID), the font-subset names, and the object write order — the things that otherwise vary per run. Unset, builds behave normally and stamp the current time.
Byte-identical output is guaranteed for the same platform and Node version. Builds from different OSes or Node majors are visually identical but not byte-identical (font subsets embed in a platform-dependent order, and zlib output varies across Node versions).
