resuml 1.8.3 → 1.9.0

package/README.md

@@ -301,6 +301,75 @@ console.log(`Matched keywords: ${jdResult.keywords?.matched.join(', ')}`);
 
 See the CLI and API for more details.
 
+## AI Agent Integration (MCP)
+
+Resuml includes a built-in [Model Context Protocol](https://modelcontextprotocol.io/) (MCP) server, making it the first resume tool with native AI agent support. Use it with Claude, GitHub Copilot, Cursor, or any MCP-compatible client.
+
+### Setup
+
+Add to your Claude Desktop or MCP client config:
+
+```json
+{
+  "mcpServers": {
+    "resuml": {
+      "command": "npx",
+      "args": ["resuml", "mcp"]
+    }
+  }
+}
+```
+
+Or run directly:
+
+```bash
+resuml mcp
+```
+
+### Available Tools
+
+| Tool | Purpose |
+|------|---------|
+| `resuml_init_resume` | Generate a starter YAML template |
+| `resuml_validate` | Validate resume YAML against JSON Resume schema |
+| `resuml_ats_check` | ATS analysis + job description keyword matching |
+| `resuml_render` | Render resume to HTML using a theme |
+| `resuml_list_themes` | List available themes and install status |
+| `resuml_export_pdf` | Export resume as PDF (requires Playwright) |
+
+### Resources
+
+The MCP server exposes structured data agents can read:
+
+| Resource | URI | Description |
+|----------|-----|-------------|
+| JSON Resume Schema | `resuml://schema/json-resume` | Full schema reference with all sections and field types |
+| ATS Scoring Rubric | `resuml://docs/ats-scoring` | Scoring system, checks performed, and optimization tips |
+| Theme Catalog | `resuml://themes/catalog` | Available themes with descriptions and install status |
+
+### Prompts
+
+Pre-built workflows for common tasks:
+
+| Prompt | Description |
+|--------|-------------|
+| `tailor-resume-to-jd` | Generate a tailored resume optimized for a specific job description |
+| `optimize-ats-score` | Analyze and improve an existing resume to maximize ATS score |
+| `review-resume` | Comprehensive review with ATS analysis and improvement suggestions |
+
+### Example Workflow
+
+Ask your AI assistant:
+
+> "Use the tailor-resume-to-jd prompt to create a resume for this job posting: [paste JD]. My name is Jane Smith, jane@example.com. I have 5 years of experience in TypeScript and React."
+
+The agent will:
+1. Generate tailored resume YAML matching the job description keywords
+2. Validate it against the JSON Resume schema
+3. Run ATS analysis targeting score ≥ 75
+4. Iterate until the score meets the target
+5. Render the final result with a professional theme
+
 ## Troubleshooting
 
 ### Common Issues

package/dist/index.cjs

@@ -1558,6 +1558,195 @@ function createServer() {
     name: "resuml",
     version: "1.0.0"
   });
+  server.registerResource(
+    "json-resume-schema",
+    "resuml://schema/json-resume",
+    {
+      description: "JSON Resume schema reference with all sections, field types, and formatting rules",
+      mimeType: "text/markdown"
+    },
+    () => ({
+      contents: [{
+        uri: "resuml://schema/json-resume",
+        mimeType: "text/markdown",
+        text: JSON_RESUME_SCHEMA_REFERENCE
+      }]
+    })
+  );
+  server.registerResource(
+    "ats-scoring-rubric",
+    "resuml://docs/ats-scoring",
+    {
+      description: "ATS scoring rubric: checks performed, weight system, rating scale, and tips for improving score",
+      mimeType: "text/markdown"
+    },
+    () => ({
+      contents: [{
+        uri: "resuml://docs/ats-scoring",
+        mimeType: "text/markdown",
+        text: ATS_SCORING_RUBRIC
+      }]
+    })
+  );
+  server.registerResource(
+    "theme-catalog",
+    "resuml://themes/catalog",
+    {
+      description: "Available resume themes with descriptions and installation status",
+      mimeType: "application/json"
+    },
+    () => {
+      const themes = KNOWN_THEMES.map((t) => ({
+        name: t.name,
+        package: t.pkg,
+        description: t.description,
+        installed: isThemeInstalled(t.pkg),
+        version: getInstalledVersion(t.pkg)
+      }));
+      return {
+        contents: [{
+          uri: "resuml://themes/catalog",
+          mimeType: "application/json",
+          text: JSON.stringify({ themes, totalCount: themes.length }, null, 2)
+        }]
+      };
+    }
+  );
+  server.registerPrompt(
+    "tailor-resume-to-jd",
+    {
+      title: "Tailor Resume to Job Description",
+      description: "Generate a tailored resume YAML optimized for a specific job description",
+      argsSchema: {
+        jobDescription: import_zod.z.string().describe("The full job description text"),
+        candidateName: import_zod.z.string().optional().describe("Candidate full name"),
+        candidateEmail: import_zod.z.string().optional().describe("Candidate email address"),
+        candidateBackground: import_zod.z.string().optional().describe("Brief summary of the candidate background, skills, and experience to incorporate")
+      }
+    },
+    ({ jobDescription, candidateName, candidateEmail, candidateBackground }) => ({
+      messages: [{
+        role: "user",
+        content: {
+          type: "text",
+          text: `Create a tailored resume in YAML format optimized for the following job description.
+
+## Job Description
+${jobDescription}
+
+${candidateBackground ? `## Candidate Background
+${candidateBackground}
+` : ""}
+## Instructions
+
+1. Analyze the job description to identify required skills, technologies, experience level, and industry terms
+2. Generate a complete resume YAML following the JSON Resume schema (read the resuml://schema/json-resume resource for the full schema)
+3. Mirror exact terminology from the job description in skills and highlights
+4. Start every highlight with an action verb (Developed, Implemented, Led, Optimized, Reduced, Built, Designed)
+5. Include numbers in 50%+ of highlights (e.g., "Reduced latency by 40%", "Managed team of 8")
+6. Never use "I", "my", "me", "we"
+7. Write a 2-4 sentence summary positioning the candidate for this specific role
+8. Use ISO 8601 dates (YYYY-MM-DD or YYYY-MM)
+${candidateName ? `9. Use candidate name: ${candidateName}` : ""}
+${candidateEmail ? `10. Use candidate email: ${candidateEmail}` : ""}
+
+## Workflow
+After generating the YAML:
+1. Use \`resuml_validate\` to check schema compliance
+2. Use \`resuml_ats_check\` with the job description text. Target: score >= 75, keyword match >= 70%
+3. If ATS score is low, revise the YAML and re-check
+4. Use \`resuml_render\` with theme "even" for the final output
+
+Output the resume YAML first, then run the validation and ATS check tools.`
+        }
+      }]
+    })
+  );
+  server.registerPrompt(
+    "optimize-ats-score",
+    {
+      title: "Optimize ATS Score",
+      description: "Analyze and improve an existing resume YAML to maximize its ATS score",
+      argsSchema: {
+        resumeYaml: import_zod.z.string().describe("The current resume YAML content"),
+        jobDescription: import_zod.z.string().optional().describe("Optional job description to optimize against"),
+        targetScore: import_zod.z.string().optional().describe("Target ATS score (default: 85)")
+      }
+    },
+    ({ resumeYaml, jobDescription, targetScore }) => ({
+      messages: [{
+        role: "user",
+        content: {
+          type: "text",
+          text: `Optimize this resume YAML to maximize its ATS score${targetScore ? ` (target: ${targetScore})` : " (target: 85+)"}.
+
+## Current Resume YAML
+\`\`\`yaml
+${resumeYaml}
+\`\`\`
+
+${jobDescription ? `## Job Description
+${jobDescription}
+` : ""}
+## Instructions
+
+1. First, run \`resuml_ats_check\` on the current YAML${jobDescription ? " with the job description" : ""} to get the baseline score
+2. Read the ATS scoring rubric (resuml://docs/ats-scoring) to understand what checks are performed
+3. Review each failed or low-scoring check and fix the issues:
+   - Missing contact info \u2192 add it
+   - No summary \u2192 write a 2-4 sentence professional summary
+   - Weak highlights \u2192 rewrite with action verbs and quantified metrics
+   - Missing keywords \u2192 incorporate them naturally into skills and highlights
+   - Structural issues \u2192 ensure all essential sections are present
+4. Run \`resuml_ats_check\` again to verify improvement
+5. Repeat until the target score is reached
+
+Output the improved YAML with a summary of changes made.`
+        }
+      }]
+    })
+  );
+  server.registerPrompt(
+    "review-resume",
+    {
+      title: "Review Resume",
+      description: "Comprehensive review of a resume YAML with ATS analysis and improvement suggestions",
+      argsSchema: {
+        resumeYaml: import_zod.z.string().describe("The resume YAML content to review")
+      }
+    },
+    ({ resumeYaml }) => ({
+      messages: [{
+        role: "user",
+        content: {
+          type: "text",
+          text: `Perform a comprehensive review of this resume.
+
+## Resume YAML
+\`\`\`yaml
+${resumeYaml}
+\`\`\`
+
+## Review steps
+
+1. Run \`resuml_validate\` to check schema compliance
+2. Run \`resuml_ats_check\` for ATS analysis
+3. Review content quality:
+   - Is the summary compelling and role-specific?
+   - Do highlights use strong action verbs?
+   - Are achievements quantified with metrics?
+   - Are skills well-organized and comprehensive?
+   - Is the work history clear and impactful?
+4. Provide a structured review with:
+   - **ATS Score**: Current score and rating
+   - **Schema Issues**: Any validation errors
+   - **Strengths**: What the resume does well
+   - **Improvements**: Specific, actionable suggestions
+   - **Revised YAML**: An improved version if significant changes are recommended`
+        }
+      }]
+    })
+  );
   server.registerTool(
     "resuml_init_resume",
     {
@@ -1643,15 +1832,20 @@ function createServer() {
       description: "Render a resume to HTML using a specified theme",
       inputSchema: {
         yaml: import_zod.z.string().describe("Resume content in YAML format"),
-        theme: import_zod.z.string().default("even").describe("Theme name (e.g. even, stackoverflow, elegant, paper, kendall)")
+        theme: import_zod.z.string().default("even").describe("Theme name (e.g. even, stackoverflow, elegant, paper, kendall)"),
+        locale: import_zod.z.string().optional().describe("Locale for theme rendering (e.g. en, de)")
       }
     },
-    async ({ yaml, theme }) => {
+    async (args) => {
+      const { yaml, theme } = args;
+      const locale = args["locale"];
       suppressStdout();
       try {
         const resume = await processResumeData([yaml]);
         const themeModule = loadTheme(theme, { autoInstall: false });
-        const html = await themeModule.render(resume);
+        const renderOptions = {};
+        if (locale) renderOptions["locale"] = locale;
+        const html = await themeModule.render(resume, renderOptions);
         restoreStdout();
         return { content: [{ type: "text", text: html }] };
       } catch (e) {
@@ -1692,15 +1886,22 @@ function createServer() {
       inputSchema: {
         yaml: import_zod.z.string().describe("Resume content in YAML format"),
         theme: import_zod.z.string().default("even").describe("Theme name"),
-        format: import_zod.z.enum(["A4", "Letter"]).default("A4").describe("Paper format")
+        format: import_zod.z.enum(["A4", "Letter"]).default("A4").describe("Paper format"),
+        locale: import_zod.z.string().optional().describe("Locale for theme rendering (e.g. en, de)"),
+        margin: import_zod.z.string().optional().describe('Page margins. Single value (e.g. "10mm") for all sides, two values (e.g. "10mm,15mm") for vertical/horizontal, or four values (e.g. "10mm,15mm,10mm,15mm") for top/right/bottom/left')
       }
     },
-    async ({ yaml, theme, format }) => {
+    async (args) => {
+      const { yaml, theme, format } = args;
+      const locale = args["locale"];
+      const margin = args["margin"];
       suppressStdout();
       try {
         const resume = await processResumeData([yaml]);
         const themeModule = loadTheme(theme, { autoInstall: false });
-        const html = await themeModule.render(resume);
+        const renderOptions = {};
+        if (locale) renderOptions["locale"] = locale;
+        const html = await themeModule.render(resume, renderOptions);
         let chromium;
         try {
           const pw = await import("playwright");
@@ -1712,14 +1913,14 @@ function createServer() {
             isError: true
           };
         }
+        const parsedMargin = parseMargin2(margin);
         const browser = await chromium.launch({ headless: true });
         const page = await browser.newPage();
         await page.setContent(html, { waitUntil: "networkidle" });
-        const margin = "10mm";
         const pdfBuffer = await page.pdf({
           format,
           printBackground: true,
-          margin: { top: margin, bottom: margin, left: margin, right: margin }
+          margin: parsedMargin
         });
         await browser.close();
         restoreStdout();
@@ -1744,12 +1945,27 @@ function createServer() {
   );
   return server;
 }
+function parseMargin2(margin) {
+  const defaultMargin = { top: "10mm", right: "10mm", bottom: "10mm", left: "10mm" };
+  if (!margin) return defaultMargin;
+  const parts = margin.split(",").map((s) => s.trim());
+  if (parts.length === 1 && parts[0]) {
+    return { top: parts[0], right: parts[0], bottom: parts[0], left: parts[0] };
+  }
+  if (parts.length === 2 && parts[0] && parts[1]) {
+    return { top: parts[0], right: parts[1], bottom: parts[0], left: parts[1] };
+  }
+  if (parts.length === 4 && parts[0] && parts[1] && parts[2] && parts[3]) {
+    return { top: parts[0], right: parts[1], bottom: parts[2], left: parts[3] };
+  }
+  return defaultMargin;
+}
 async function startMcpServer() {
   const server = createServer();
   const transport = new import_stdio.StdioServerTransport();
   await server.connect(transport);
 }
-var import_mcp, import_stdio, import_zod, originalLog, originalWarn;
+var import_mcp, import_stdio, import_zod, originalLog, originalWarn, JSON_RESUME_SCHEMA_REFERENCE, ATS_SCORING_RUBRIC;
 var init_server = __esm({
   "src/mcp/server.ts"() {
     "use strict";
@@ -1764,6 +1980,179 @@ var init_server = __esm({
     init_themeInfo();
     originalLog = console.log;
     originalWarn = console.warn;
+    JSON_RESUME_SCHEMA_REFERENCE = `# JSON Resume Schema Reference
+
+The JSON Resume schema defines the structure for resume data. resuml uses YAML as the input format.
+
+## Top-level sections
+
+| Section | Required | Description |
+|---------|----------|-------------|
+| basics | Yes | Name, label, email, phone, url, summary, location, profiles |
+| work | Recommended | Work experience entries |
+| education | Recommended | Education entries |
+| skills | Recommended | Skill categories with keywords |
+| projects | Optional | Project entries |
+| volunteer | Optional | Volunteer experience |
+| awards | Optional | Awards and honors |
+| certificates | Optional | Professional certifications |
+| publications | Optional | Published works |
+| languages | Optional | Language proficiencies |
+| interests | Optional | Personal interests |
+| references | Optional | Professional references |
+
+## Section schemas
+
+### basics
+\`\`\`yaml
+basics:
+  name: "Full Name"           # required
+  label: "Professional Title"
+  email: "email@example.com"
+  phone: "+1-555-123-4567"
+  url: "https://website.com"
+  summary: "2-4 sentence professional summary"
+  location:
+    city: "City"
+    countryCode: "US"
+    region: "State"
+  profiles:
+    - network: "LinkedIn"
+      username: "username"
+      url: "https://linkedin.com/in/username"
+\`\`\`
+
+### work
+\`\`\`yaml
+work:
+  - name: "Company Name"
+    position: "Job Title"
+    url: "https://company.com"
+    startDate: "2020-01-01"    # ISO 8601
+    endDate: "2023-12-31"      # omit for current position
+    summary: "Role description"
+    highlights:
+      - "Achievement with measurable result"
+\`\`\`
+
+### education
+\`\`\`yaml
+education:
+  - institution: "University"
+    area: "Field of Study"
+    studyType: "Degree Type"   # e.g. Bachelor, Master, PhD
+    startDate: "2014-09-01"
+    endDate: "2018-06-01"
+\`\`\`
+
+### skills
+\`\`\`yaml
+skills:
+  - name: "Category"
+    level: "Expert"            # Master, Expert, Advanced, Intermediate, Beginner
+    keywords: ["Skill1", "Skill2"]
+\`\`\`
+
+### projects
+\`\`\`yaml
+projects:
+  - name: "Project Name"
+    description: "What it does"
+    highlights: ["Key achievement"]
+    keywords: ["Tech1", "Tech2"]
+    startDate: "2023-01-01"
+    url: "https://github.com/..."
+\`\`\`
+
+### certificates
+\`\`\`yaml
+certificates:
+  - name: "Certificate Name"
+    date: "2023-01-01"
+    issuer: "Issuing Organization"
+    url: "https://credential-url.com"
+\`\`\`
+
+### languages
+\`\`\`yaml
+languages:
+  - language: "English"
+    fluency: "Native speaker"  # Native speaker, Fluent, Advanced, Intermediate, Elementary
+\`\`\`
+
+## Formatting rules
+- Dates: ISO 8601 format (YYYY-MM-DD or YYYY-MM)
+- Start highlights with action verbs: Developed, Implemented, Led, Optimized, Reduced, Built, Designed
+- Include numbers in 50%+ of highlights (e.g., "Reduced latency by 40%")
+- Never use first person (I, my, me, we)
+- Summary: 2-4 sentences positioning the candidate for the specific role
+`;
+    ATS_SCORING_RUBRIC = `# ATS Scoring Rubric
+
+resuml performs deterministic, offline ATS (Applicant Tracking System) analysis.
+
+## Scoring system
+
+### Rating scale
+| Score | Rating | Description |
+|-------|--------|-------------|
+| 90-100 | Excellent | Resume is well-optimized for ATS |
+| 75-89 | Good | Resume passes most ATS checks |
+| 60-74 | Needs Work | Several improvements recommended |
+| 0-59 | Poor | Significant issues found |
+
+### Weight system
+Each check has a weight that affects the final score:
+- **High weight (3x)**: Critical checks that significantly impact ATS parsing
+- **Medium weight (2x)**: Important but not critical checks
+- **Low weight (1x)**: Nice-to-have improvements
+
+### Combined scoring (with job description)
+When a job description is provided:
+- Generic checks: 60% of final score
+- Keyword match: 40% of final score
+
+## Checks performed
+
+### Contact Information (category: contact)
+| Check | Weight | What it verifies |
+|-------|--------|-----------------|
+| contact-complete | High | Name, email, phone, and city are all present |
+| has-linkedin | Medium | LinkedIn profile exists in profiles section |
+
+### Content Quality (category: content)
+| Check | Weight | What it verifies |
+|-------|--------|-----------------|
+| has-summary | High | Professional summary exists (15-100 words) |
+| work-highlights | High | Each work entry has at least 2 highlights |
+| action-verbs | Medium | Highlights start with action verbs |
+| quantified-impact | Medium | 50%+ of highlights include numbers/metrics |
+| no-first-person | Low | No first-person pronouns (I, my, me, we) |
+
+### Resume Structure (category: structure)
+| Check | Weight | What it verifies |
+|-------|--------|-----------------|
+| date-consistency | Medium | All dates are valid ISO 8601 format |
+| skills-populated | Medium | At least 3 skill categories defined |
+| education-complete | Medium | Education section has institution and area |
+| essential-sections | High | Work, education, and skills sections present |
+
+## Job description matching
+When a job description is provided, resuml extracts keywords using TF-based extraction
+and matches them against the resume using stem matching. Results include:
+- **matched**: Keywords found in the resume
+- **missing**: Keywords not found (add these to improve score)
+- **matchPercentage**: Percentage of JD keywords found in resume
+
+## Tips for improving ATS score
+1. Include all contact information (name, email, phone, city)
+2. Add a LinkedIn profile URL
+3. Write a 2-4 sentence professional summary
+4. Use action verbs to start each highlight
+5. Quantify achievements with numbers (%, $, time saved, team size)
+6. Include at least 3 skill categories with relevant keywords
+7. When targeting a job, mirror exact terminology from the job description
+`;
   }
 });