Sprint 2.4-2.6 + QA: skill, registry metadata, MCP docs, CI handshake gate

- skills/cvx/SKILL.md (agentskills.io format): the full CVX loop for
  skill-capable agents — MCP tools when connected, CLI otherwise, schema
  summary, truthfulness rules; ships in the tarball; docsSync tripwire
  now covers it (every content file, all four tools, frontmatter limits)
- registry prep: mcpName io.github.hrtips/cvx in package.json, mcp/
  model-context-protocol keywords, server.json for mcp-publisher (stable
  1.4.0 — submit after the stable release), GitHub topics set
- docs: README "Plug it into your agent (MCP)" section; ai-guide Route E
  (MCP) with per-client one-liners
- CI packaged E2E: MCP smoke — spawns the packed tarball's server via
  node (Windows-safe), completes the initialize handshake, asserts the
  four-tool inventory
- 112 tests; tarball 326 kB (guardrail <500 kB)

Author: ramith

.github/workflows/ci.yml

@@ -60,6 +60,35 @@ jobs:
           set -e
           test "$CODE" -eq 64
 
+          # MCP: initialize handshake + tools/list against the packed tarball
+          cat > mcp-smoke.cjs <<'SMOKE'
+          const { spawn } = require("child_process");
+          const p = spawn(process.execPath, ["node_modules/@hrtips/cvx/bin/cvx.js", "mcp"], { stdio: ["pipe", "pipe", "inherit"] });
+          let buf = ""; const msgs = [];
+          const send = (o) => p.stdin.write(JSON.stringify(o) + "\n");
+          p.stdout.on("data", (d) => {
+            buf += d;
+            let i; while ((i = buf.indexOf("\n")) !== -1) {
+              const line = buf.slice(0, i).trim(); buf = buf.slice(i + 1);
+              if (line) { msgs.push(JSON.parse(line)); step(); }
+            }
+          });
+          function step() {
+            if (msgs.length === 1) {
+              if (msgs[0].result.serverInfo.name !== "cvx") { console.error("bad serverInfo"); process.exit(1); }
+              send({ jsonrpc: "2.0", method: "notifications/initialized" });
+              send({ jsonrpc: "2.0", id: 2, method: "tools/list" });
+            } else if (msgs.length === 2) {
+              const tools = msgs[1].result.tools.map((t) => t.name).sort().join(",");
+              if (tools !== "build_pdf,get_schema,init_cv,validate_cv") { console.error("bad tools:", tools); process.exit(1); }
+              console.log("mcp smoke ok:", tools); p.kill(); process.exit(0);
+            }
+          }
+          send({ jsonrpc: "2.0", id: 1, method: "initialize", params: { protocolVersion: "2025-06-18", capabilities: {}, clientInfo: { name: "ci", version: "0" } } });
+          setTimeout(() => { console.error("mcp handshake timeout"); process.exit(1); }, 30000);
+          SMOKE
+          node mcp-smoke.cjs
+
           npx cvx build
           npx cvx build --ats
           test -f bruce-wayne.pdf && test -f bruce-wayne-ats.pdf

README.md

@@ -171,6 +171,19 @@ The formats are deliberately LLM-friendly, and the schema is published for machi
 
 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](docs/ai-guide.md#route-c--chat-assistant-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.
+
+```bash
+npx @hrtips/cvx mcp init --client claude          # Claude Code (.mcp.json, project)
+npx @hrtips/cvx mcp init --client claude-desktop  # Claude Desktop (global config)
+npx @hrtips/cvx mcp init --client cursor          # Cursor (.cursor/mcp.json)
+npx @hrtips/cvx mcp init --client vscode          # VS Code (.vscode/mcp.json)
+```
+
+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](skills/cvx/SKILL.md) 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.

docs/ai-guide.md

@@ -10,6 +10,7 @@ Pick the route that matches the tool you have:
 | A chat assistant with web access | [Route B](#route-b--chat-assistant-with-web-access) | One paste in, files out |
 | A chat assistant without web access | [Route C](#route-c--chat-assistant-self-contained-prompt) | Same, using a self-contained prompt |
 | An agent-mode assistant that can run commands (ChatGPT agent mode, …) | [Route D](#route-d--agent-mode-assistant-zero-local-setup) | Zero local setup — the assistant runs CVX in its own workspace |
+| An MCP client (Claude Desktop, Claude Code, Cursor, VS Code, …) | [Route E](#route-e--mcp-any-client-native-tools) | One-time config — the client gets native CVX tools |
 
 Whichever route you take, the same two rules apply:
 
@@ -144,6 +145,21 @@ The zip matters: agent workspaces are ephemeral, and your `cv-content/` folder i
 
 ---
 
+## Route E — MCP: any client, native tools
+
+CVX ships an MCP stdio server with four tools — `get_schema`, `init_cv`, `validate_cv`, `build_pdf` — thin wrappers over the same engine as the CLI. No API keys, fully offline; the server's instructions teach the model the loop and the truthfulness rules.
+
+One-time setup (writes/merges the client's config, never clobbers other servers):
+
+```bash
+npx @hrtips/cvx mcp init --client claude          # Claude Code
+npx @hrtips/cvx mcp init --client claude-desktop  # Claude Desktop
+npx @hrtips/cvx mcp init --client cursor          # Cursor
+npx @hrtips/cvx mcp init --client vscode          # VS Code
+```
+
+Restart the client, then ask for your CV — e.g. *"Make me a CV from the LinkedIn text below. Use the CVX tools: fetch the schema, scaffold, fill in my real details, validate after every edit, and build both variants."* The assistant passes your workspace folder as `dir` on each call; the YAML lands in `cv-content/`, the PDFs next to it.
+
 ## Iterating with the assistant
 
 Useful follow-up prompts once the first PDF renders:

package.json

@@ -1,7 +1,8 @@
 {
   "name": "@hrtips/cvx",
   "version": "1.3.0",
-  "description": "CVX — structured input, professional output. YAML content in, pixel-perfect CV PDFs out; swappable themes and layouts, no headless browser. Formerly makecv.",
+  "description": "CVX — structured input, professional output. YAML content in, pixel-perfect CV PDFs out; swappable themes and layouts, no headless browser. MCP server included. Formerly makecv.",
+  "mcpName": "io.github.hrtips/cvx",
   "bin": {
     "cvx": "bin/cvx.js"
   },
@@ -17,7 +18,10 @@
     "yaml",
     "cli",
     "ats",
-    "react-pdf"
+    "react-pdf",
+    "mcp",
+    "mcp-server",
+    "model-context-protocol"
   ],
   "scripts": {
     "dev": "vite",
@@ -38,7 +42,8 @@
     "lib",
     "bin",
     "template",
-    "schema"
+    "schema",
+    "skills"
   ],
   "devDependencies": {
     "@rollup/plugin-yaml": "^5.0.0",

server.json

@@ -0,0 +1,20 @@
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
+  "name": "io.github.hrtips/cvx",
+  "description": "Create, validate, and render professional CV PDFs from plain YAML — fully local, no accounts. Tools: get_schema, init_cv, validate_cv, build_pdf.",
+  "repository": {
+    "url": "https://github.com/hrtips/cvx",
+    "source": "github"
+  },
+  "version": "1.4.0",
+  "packages": [
+    {
+      "registryType": "npm",
+      "identifier": "@hrtips/cvx",
+      "version": "1.4.0",
+      "transport": {
+        "type": "stdio"
+      }
+    }
+  ]
+}

skills/cvx/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: cvx
+description: Create, validate, and render professional CV/resume PDFs from plain YAML using CVX — fully local, no accounts. Use when the user wants to write a CV or resume, convert an existing CV to a maintained format, tailor a CV for a job application, or produce an ATS-safe variant. Covers the cv-content/ YAML schema, the edit→validate→build loop, themes, layouts, and ATS keywords.
+license: Apache-2.0
+compatibility: Requires Node.js 20+ (runs via npx, no install). MCP server available via `npx @hrtips/cvx mcp`.
+metadata:
+  author: hrtips
+  homepage: https://github.com/hrtips/cvx
+---
+
+# CVX — structured input, professional output
+
+CVX renders a folder of plain YAML files (`cv-content/`) into a pixel-perfect CV PDF. Everything runs locally: no accounts, no network calls, and the user's data never leaves their machine. The YAML is the durable asset — the user keeps and re-edits it for every future application.
+
+## The loop
+
+If the CVX MCP server is connected, use its tools: `get_schema` → `init_cv` → edit YAML → `validate_cv` → `build_pdf` (pass the workspace folder as `dir`, absolute path). Otherwise use the CLI:
+
+```bash
+npx @hrtips/cvx init                      # scaffold cv-content/ with a complete example CV
+npx @hrtips/cvx validate --strict --json  # every problem at once: file + field paths + fixes
+npx @hrtips/cvx build --json              # writes <name>.pdf; add --ats for the ATS-safe variant
+npx @hrtips/cvx list --json               # available themes and layouts
+```
+
+Exit codes: `0` ok · `2` validation failed · `3` render failed · `64` usage error. With `--json`, stdout is exactly one JSON object; logs go to stderr.
+
+Always validate after every edit and before every build. Findings include the file, the field path, and a suggested fix — apply the fix and re-validate.
+
+## Rules that are not optional
+
+1. **Never invent facts.** Every entry must be truthful to the user's real history. This matters most for `keywords.yaml`: ATS parsers cross-check keywords against the CV body, and stuffing false terms gets CVs auto-rejected.
+2. **Don't rename the YAML files.** Sections are discovered by filename: `personal.yaml`, `summary.yaml`, `experience.yaml`, `education.yaml`, `competencies.yaml`, `achievements.yaml`, `referees.yaml`, `keywords.yaml`, `config.yaml`.
+3. **Quote strings containing colons** (`"Director: Operations"`). Date ranges are free text (`2019 – Present`).
+4. The photo goes at `cv-content/images/profile.jpg` (or `.jpeg`/`.png`/`.webp`) — ask the user for it; it cannot be generated.
+
+## Content files (summary — the schema is authoritative)
+
+Every scaffolded file carries a `$schema` header; the canonical JSON Schema lives at `schema/v1/` in the repo and is returned by the MCP `get_schema` tool.
+
+- `personal.yaml` (object): `name` (required — drives the output filename), `title`, `company`, `phone`+`phoneHref`, `email`, `linkedin`+`linkedinHref`, `facebook`+`facebookHref`, `location`.
+- `summary.yaml`: list of 3–6 single-sentence bullets. A bullet may also be `{text, link: {href, label}, suffix}` to embed a clickable link (same form works in experience bullets).
+- `experience.yaml`: list of roles, most recent first — `role` (required), `company`, `period`, `location`, `description`, `progression` (list of `{title, period}`), `bullets` (verb-first, quantified, truthful).
+- `education.yaml`: list of `{degree, institution, period}`.
+- `competencies.yaml`: 6–12 short skill strings.
+- `achievements.yaml`: list of `{year, text}` — `year` is the bold headline (often the award name), `text` the attribution.
+- `referees.yaml`: list of `{name, title, company, email, phone}`, or `[]` for "available upon request".
+- `keywords.yaml` (optional): extra truthful ATS keywords not already covered by competencies/titles; embedded in PDF metadata, never printed.
+- `config.yaml`: `schemaVersion: 1`, `theme` (`teal`|`coral`|`mono`), `layout` (`two-column`|`single-column`|custom filename); pagination keys only if page 1 overflows.
+
+## Variants
+
+- Designed CV: `build` → two-column, photo sidebar, theme colours.
+- Job-portal upload: `build --ats` (or `build_pdf` with `ats: true`) → single column, no colours, machine-friendly, `<name>-ats.pdf`.
+
+## When validation fails
+
+Report the findings to the user in plain language, apply the suggested fixes to the YAML, and re-validate. Unknown keys are typos more often than not — the findings include a "did you mean" suggestion. Do not build until validation passes.

test/docsSync.test.js

@@ -12,6 +12,7 @@ const schema = JSON.parse(readFileSync(path.join(ROOT, 'schema', 'v1', 'cvx.sche
 const cvSchemaDoc = readFileSync(path.join(ROOT, 'docs', 'cv-schema.md'), 'utf8')
 const scaffoldReadme = readFileSync(path.join(ROOT, 'template', 'cv-content', 'README.md'), 'utf8')
 const aiGuide = readFileSync(path.join(ROOT, 'docs', 'ai-guide.md'), 'utf8')
+const skillMd = readFileSync(path.join(ROOT, 'skills', 'cvx', 'SKILL.md'), 'utf8')
 
 const CONTENT_DEFS = ['personal', 'summary', 'experience', 'education', 'competencies', 'achievements', 'referees', 'keywords', 'config']
 
@@ -56,4 +57,17 @@ describe('scaffold README and AI guide stay aligned', () => {
     expect(aiGuide).toContain('validate')
     expect(aiGuide).toContain('schemaVersion')
   })
+
+  it('SKILL.md covers every content file, the MCP tools, and the truthfulness rule', () => {
+    for (const def of CONTENT_DEFS) {
+      expect(skillMd, `SKILL.md missing ${def}.yaml`).toContain(`${def}.yaml`)
+    }
+    for (const tool of ['get_schema', 'init_cv', 'validate_cv', 'build_pdf']) {
+      expect(skillMd, `SKILL.md missing tool ${tool}`).toContain(tool)
+    }
+    expect(skillMd).toMatch(/[Nn]ever invent facts/)
+    const [, frontmatter] = skillMd.split('---')
+    expect(frontmatter).toContain('name: cvx')
+    expect(frontmatter.length).toBeLessThan(1500)
+  })
 })