Resume Onepage Autofit Mcp

AI 简历自动适配系统

🌐 中文 | English

🤖 厌倦了在 AI 和 Word 之间复制内容、调整格式、反复修改以适配一页吗？如果 AI 能替你完成这一反馈循环呢？这个 MCP 让 AI 渲染 PDF，并自动调整内容，使其完美适配一页且格式整洁。

🎯 工作原理

User: Please generate a single-page resume from my experience

AI Agent:
1. 📝 Write the resume to resume.md
2. 🔍 Call render_resume_pdf with its path
3. ⚠️ Failed: overflows by 6% (about 4 body lines); the bullet on line 58 ends with a 6-character line
4. 🔧 Edit only those lines in resume.md
5. ✅ Success! PDF generated

🚀 快速开始

1. 安装 MCP 服务

# Enter MCP Server directory and install dependencies
cd mcp_server
pip install -r requirements.txt
# ⚡ Or using uv (recommended): uv pip install -r requirements.txt

# Install Chromium browser (first time only, ~150MB)
playwright install chromium

2. 配置 Claude Desktop

编辑 %APPDATA%\Claude\claude_desktop_config.json：

{
  "mcpServers": {
    "resume-onepage-autofit-mcp": {
      "command": "python",
      "args": ["<your-path>/myresumebuilder/mcp_server/mcp_server.py"]
    }
  }
}

将 <your-path> 替换为你的实际项目路径。

⚡ 如果你更喜欢使用 uv：

"resume-onepage-autofit-mcp": {
  "command": "uv",
  "args": [
    "run",
    "--directory",
    "<your-path>/myresumebuilder",
    "mcp_server/mcp_server.py"
  ]
}

3. 准备简历内容

将简历内容写入 myexperience.md（格式请参考 example_resume.md）。

4. 开始使用

重启 Claude Desktop，然后只需告诉 AI：“请根据我的经历生成一页简历。”

Agent 会将简历写入 .md 文件，并将该文件的绝对路径（markdown_path）传给工具；Linux/macOS 路径示例：/home/you/resume.md，Windows 路径示例：C:\Users\you\resume.md。每次渲染之间，Agent 会直接编辑文件，而不是重新发送整份简历。详情请参阅 mcp_server/README.md。

PDF 会与 Markdown 文件保存在同一目录下，且文件名相同（resume.md → resume.pdf）。渲染器还会在每个 PDF 旁边（例如 resume.pdf）生成 resume.structured.json：将摘要、技能、经历和项目拆分为各个字段（公司、职位、地点、开始和结束月份）。工具结果会在“格式警告”下列出所有不符合简历规范格式的行，并提供每行的改写形式。

💡 自定义输出路径：传入绝对路径 output_path，即可将 PDF 保存到其他位置。

---

✨ 核心功能

• 🎯 智能适配：自动调整内容，使简历完美适配一张 A4 纸
• 🔍 精确检测：基于 Playwright 进行像素级精度的页面高度检测
• 📏 逐行反馈：报告每个部分和项目符号占用的行数、最后一行的字符数，以及溢出的行数。工具只陈述事实；由 Agent 决定删减哪些内容
• 🔄 反馈循环：Agent 直接编辑 Markdown 文件并重新渲染
• 🚀 MCP 集成：支持 Claude Desktop 和其他 AI 客户端直接调用

📸 工作流

User provides experience → AI generates Markdown resume
                                    ↓
                        MCP Server renders & validates
                                    ↓
                    ┌─────── Detect page height ───────┐
                    │                                  │
                  Success                           Failure
               (within one page)                 (overflow X%)
                    │                                  │
              Generate PDF                Return per-block line counts
                    │                                  ↓
                    │                       AI edits the lines it chooses
                    │                                  │
                    └──────────── Re-render ←──────────┘

🧭 Agent 提示词

工具只报告布局事实，不会建议删减内容。可以给 Agent 提供如下提示词（根据你的工作流进行调整）：

You build a one-page resume with the render_resume_pdf tool.

1. Write the resume to a Markdown file, e.g. /home/you/resumes/acme/resume.md, in the
   canonical forms described in the tool's markdown_path parameter. Write the file once.
2. Call render_resume_pdf with the file's absolute path.
3. After each render, change only the lines that need it with your edit tool and render
   again with the same path. Never rewrite the whole file or paste the resume into the call.
   - Start with the paragraph under pdf_path: it says whether the render succeeded, why not,
     and what the next render must achieve.
   - overflow: "Page fit" gives overflow_percent and overflow_body_lines. The table "Space by
     section and entry" shows how many lines each section, job, project and school takes. Its
     "wrapped items" column lists items that wrap, as "source line: characters on last line";
     "58: 6" means 6 characters on line 58 cost a whole line, so trimming them saves it. Cut
     what is least relevant to the target job first.
   - success with a large empty_space_percent: there is room; add relevant detail or stop.
   - layout_error: each line under "Layout warnings" is an entry header that wrapped. It must
     fit on one line.
   - Format warnings: in the same edit, rewrite each listed line to its expected form. If a
     month is missing, ask the user; never invent one.
4. Stop when status is success and there are no format warnings. If it still does not fit
   after 5 renders, tell the user what you would cut and ask.

Never change facts (numbers, dates, company names, titles) to make the page fit.

🔧 视觉预览（可选）

若要手动调整默认样式参数，请使用控制面板（纯前端，无需 Python）：

# Use VS Code Live Server extension (recommended)
# Right-click control_panel.html -> "Open with Live Server"

# Or Python simple server
python -m http.server 8080
# Visit http://localhost:8080/control_panel.html

💡 控制面板主要用于手动调试样式限制（例如字体大小范围、行间距）。日常使用时，请依靠 AI Agent；它会根据内容，在最佳范围内自动调整布局。技术详情请参阅 DEVELOPMENT.md。

📚 文档

• DEVELOPMENT.md：技术架构与开发指南
• mcp_server/README.md：MCP 服务 API 文档

🐛 已知限制

1. 浏览器依赖：需要 Chromium（首次安装约 150MB）
2. 内容长度：很长的简历（10 页以上）可能需要多轮渲染
3. 特殊字符：部分 emoji 可能影响布局

🔄 开发路线图

v0.2.0（计划中）

• 自定义模板

🤝 贡献

欢迎提交问题和拉取请求！

开发环境设置

# Clone repository
git clone https://github.com/seriserendipia/resume-onepage-autofit-mcp.git
cd resume-onepage-autofit-mcp

# Create virtual environment
conda create -n agent_env python=3.10
conda activate agent_env

# Install dependencies
pip install -r mcp_server/requirements.txt
playwright install chromium

提交规范

• feat: 新功能
• fix: 修复错误
• docs: 更新文档
• test: 与测试相关

📄 许可证

MIT 许可证 - 参见 LICENSE

🙏 致谢

• Playwright - 强大的浏览器自动化工具
• Source Sans 3 - 随附的正文字体（SIL OFL 1.1，参见 fonts/OFL.txt）
• MCP - 统一的 AI 工具协议
• Markdown-it - 可靠的 Markdown 解析器
• Paged.js - 在浏览器中分页生成 PDF

📧 联系方式

• 🐛 问题反馈：GitHub Issues
• 💬 讨论：GitHub Discussions

---

⭐ 如果这个项目对你有帮助，请给它一个 Star！

⭐ 如果这个项目对你有帮助，请给一个 Star！