Cv Writer MCP

简历撰写者 MCP 服务器

一个基于人工智能的模型上下文协议（MCP）服务器，能够从Markdown格式自动生成专业简历，并具备智能风格优化功能。该服务器采用OpenAI Agents SDK和FastMCP框架构建。

🚀 特点

完整的端到端流程

• Markdown → LaTeX → PDF → 风格优化 → 最终PDF
• 多变体风格生成，配备AI质量评判
• 带有重试逻辑的自动LaTeX错误修复
• 带有反馈循环的迭代质量改进
• 有组织的文件命名： iter1_var2.tex， iter1_var2_refined.pdf （迭代1，变体2，精炼版）

人工智能驱动的智能

• OpenAI 代理SDK多个用于转换、编译和样式设置的专用代理
• 质量评判员/质量评估员“基于科学评分的变体评估中的LLM作为法官模式”
• 智能默认设置成本感知配置（默认快速，按需保证质量）
• 真正的并行处理每个变体独立地经历所有步骤（生成 → 编译 → 验证 → 优化）
• 增强日志记录在法官对比中清晰识别文件

MCP 集成

• 主要工具： md_to_latex， compile_and_improve_style
• 调试工具用于测试的独立阶段工具
• 交通灵活性stdio（Claude Desktop）和HTTP支持
• 资源服务通过MCP资源获取PDF和LaTeX文件

MCPB 打包支持

• 便携式配电将服务器和依赖项打包成一个.mcpb文件
• 轻松安装在Claude Desktop中进行拖放安装
• 自给自足的；独立的所有Python依赖项都打包在lib/目录中
• 自动化构建Makefile 和 pixi 任务 uv 用于快速打包

📦 安装

先决条件

• Python 3.11及以上版本
• LaTeX发行版 (TeX Live, MiKTeX 或 MacTeX)
• OpenAI API密钥 （针对AI代理）

快速设置

# Clone repository
git clone https://github.com/francisco-perez-sorrosal/cv-writer-mcp.git
cd cv-writer-mcp

# Install with pixi (recommended)
pixi install

# Set OpenAI API key
export OPENAI_API_KEY="your-api-key-here"

# Verify installation
pixi run check-latex

📦 MCPB 扩展包安装（推荐）

为了获得最简便的安装体验：

1. 下载 cv-writer-mcp.mcpb 来自发布
2. 打开Claude桌面设置
3. 转到“MCP 服务器”选项卡
4. 点击“从文件安装”
5. 选择 cv-writer-mcp.mcpb
6. 设定；套装；一套 OPENAI_API_KEY 在环境变量中

好了！服务器已准备就绪，可以使用了。

构建你自己的软件包

需要 uv 待安装（超快速Python包管理器）：

# Install uv (if not already installed)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Build complete MCPB bundle
make build-mcpb

# Or use individual steps
pixi run python-bundle       # Build wheel with uv
pixi run update-mcpb-deps    # Export dependencies with uv
pixi run mcp-bundle          # Install to lib/ with uv
pixi run pack                # Create .mcpb file

安装LaTeX

macOS:

brew install --cask mactex

Ubuntu/Debian（注：这两个都是Linux发行版的名称，直接翻译为中文即“Ubuntu/Debian”，无需额外改动）

sudo apt-get install texlive-full

Windows： 下载 MiKTeX 或者 TeX Live

🎯 快速入门

端到端的简历生成

# FAST MODE (Default) - Quick & Cheap (~3-4 LLM calls)
pixi run generate-cv-fast

# QUALITY MODE - 2 variants, judge picks best (~6-8 LLM calls)
pixi run generate-cv-quality

# ITERATIVE MODE - Best quality with feedback loops (~15-25 LLM calls)
pixi run generate-cv-iterative

每种模式下会发生什么？

🏗️ 建筑学

完整的管道

Phase 1: Markdown → LaTeX
  └─ MD2LaTeXAgent (OpenAI agent)

Phase 2: Initial Compilation (LOOP #1: compile-fix-compile)
  └─ LaTeXExpert
      FOR attempt in 1..max_attempts:
        ├─ CompilationAgent: compile LaTeX
        ├─ If errors: CompilationErrorAgent fixes them
        └─ Retry until success or max attempts

Phase 3: Style Improvement (LOOP #2: true parallel processing)
  └─ PDFStyleCoordinator
      FOR iteration in 1..max_iterations:
        ├─ Step 1: Capture & Analyze PDF (VisualCriticAgent)
        ├─ Step 2: Generate N variants IN PARALLEL
        │   FOR each variant (parallel execution):
        │     ├─ FormattingAgent: translate critiques → LaTeX fixes
        │     ├─ LOOP #1: compile-fix-compile (nested!)
        │     ├─ Visual Validation: detect critical regressions
        │     ├─ Refinement: fix critical issues (Branch Judge)
        │     └─ Final variant ready with validation metadata
        ├─ Step 3: Main Quality Judge evaluates all completed variants
        └─ Decision: pass/needs_improvement/fail → stop or continue

智能默认设置

自动启用法官功能当 num_variants >= 2 （需要挑选最佳） 自动禁用法官当 num_variants = 1 （无可比较） 成本感知默认是1个变体，1次迭代（快速且廉价） 质量感知的轻松启用质量模式 --variants 2

关键的架构改进

🚀 真正的并行处理现在，每个变体都独立地经历其完整的生命周期：

• 生成 → 编译 → 验证 → （如需）细化
• 处理阶段之间不存在顺序瓶颈
• 最大化资源利用和速度

📁 文件命名清晰有组织、描述性的命名规范：

• iter1_var2.tex 而不是 i1v2.tex
• iter1_var2_refined.pdf 而不是 i1v2r.pdf
• 易于理解文件关系和版本

🔧 增强错误处理即使个别变体失败，也能继续处理的稳健流程：

• 优雅地处理编译失败
• 安全处理PDF路径中的空值
• 单个变异体的失败不会阻碍整个流程的进行

📚 使用方法

MCP服务器

启动Claude Desktop或其他MCP客户端的服务器：

# Start with stdio transport (default for Claude Desktop)
export TRANSPORT="stdio"
pixi run serve

# Start with HTTP transport
export TRANSPORT="streamable-http"
pixi run serve

主要的MCP工具

md_to_latex ⭐

完整的端到端流程：Markdown → LaTeX → PDF → 样式调整 → 最终PDF

参数：

• markdown_content （必填）：Markdown格式的简历内容
• output_filename （可选）：自定义输出文件名
• enable_style_improvement (默认：true)：启用样式阶段
• max_compile_attempts （默认：3）：最大编译重试次数
• max_style_iterations （默认：1）：最大样式迭代次数
• num_style_variants （默认值：1）：每次迭代的变体数量
• enable_quality_validation （默认：无）：如果变体数 >= 2，则启用判断

示例：

{
  "markdown_content": "# John Doe\n## Experience...",
  "num_style_variants": 2,
  "max_style_iterations": 3
}

compile_and_improve_style ⭐

编译现有的LaTeX并改进样式：LaTeX → PDF → 样式调整 → 最终PDF

参数：

• tex_filename （必填）：.tex 文件的名称
• output_filename （可选）：自定义输出文件名
• max_compile_attempts （默认值：3）：最大编译重试次数
• max_style_iterations （默认：1）：最大样式迭代次数
• num_style_variants （默认值：1）：变体数量
• enable_quality_validation （默认：无）：如果变体数 >= 2，则自动启用

CLI 命令

主要工作流程

# Fast mode (1 variant, 1 iteration, no judge)
pixi run generate-cv-fast

# Quality mode (2 variants, judge picks best)
pixi run generate-cv-quality

# Iterative mode (3 iterations, 2 variants, judge-driven)
pixi run generate-cv-iterative

# Compile and improve existing LaTeX
pixi run compile-and-improve

调试/测试工作流程（单个阶段）

# Check LaTeX installation
pixi run check-latex

# Phase 1: Markdown → LaTeX only
pixi run convert-markdown

# Phase 2: LaTeX → PDF only (with error fixing)
pixi run compile-latex

# Phase 3: PDF → Styled LaTeX only
pixi run fix-style

自定义命令

# Custom workflow with specific parameters
python -m cv_writer_mcp generate-cv-from-markdown input/cv.md \
  --output my_cv.pdf \
  --max-style-iter 3 \
  --variants 2 \
  --quality

# Disable style improvement (just convert and compile)
python -m cv_writer_mcp generate-cv-from-markdown input/cv.md \
  --no-enable-style

# Force quality judge on single variant
python -m cv_writer_mcp generate-cv-from-markdown input/cv.md \
  --variants 1 \
  --quality

⚙️ 配置

创建一个 .env 文件：

# Required
OPENAI_API_KEY=your-api-key-here

# Optional
TRANSPORT=stdio                  # "stdio" or "streamable-http"
HOST=localhost
PORT=8000
OUTPUT_DIR=./output
TEMP_DIR=./temp
LATEX_TIMEOUT=180
LOG_LEVEL=INFO

🧪 开发

设置

# Install development dependencies
pixi install

# Run all checks (format, lint, type-check, test)
pixi run ci

开发命令

# Format code
pixi run format

# Lint code
pixi run lint

# Type checking
pixi run type-check

# Run tests
pixi run test

# Run tests with coverage
pixi run test-cov

项目结构

cv-writer-mcp/
├── src/cv_writer_mcp/
│   ├── orchestration/         # End-to-end pipeline orchestrator
│   │   ├── pipeline_orchestrator.py
│   │   └── models.py
│   ├── compilation/            # LaTeX compilation with error fixing
│   │   ├── latex_expert.py
│   │   ├── compiler_agent.py
│   │   ├── error_agent.py
│   │   ├── tools.py
│   │   ├── models.py
│   │   └── configs/
│   │       ├── compiler_agent.yaml
│   │       └── error_agent.yaml
│   ├── conversion/             # Markdown to LaTeX conversion
│   │   ├── md2latex_agent.py
│   │   ├── models.py
│   │   └── configs/
│   │       └── md2latex_agent.yaml
│   ├── style/                  # PDF style improvement
│   │   ├── pdf_style_coordinator.py
│   │   ├── visual_critic_agent.py    # Design quality critic
│   │   ├── formatting_agent.py       # LaTeX implementation
│   │   ├── quality_agent.py          # LLM-as-a-judge
│   │   ├── pdf_computer.py           # Screenshot capture
│   │   ├── tools.py
│   │   ├── models.py
│   │   └── configs/
│   │       ├── formatting_agent.yaml
│   │       ├── quality_agent.yaml
│   │       └── visual_critic_agent.yaml
│   ├── main.py                 # MCP server and CLI entry point
│   ├── models.py               # Shared data models
│   ├── utils.py                # Utility functions
│   └── logger.py               # Logging configuration
├── context/                    # LaTeX templates
├── input/                      # Sample input files
├── output/                     # Generated files
└── tests/                      # Test suite

💡 它的工作原理

多变体风格优化

1. 截图捕获实用函数使用Playwright将PDF页面转换为PNG图像
2. 视觉批评VisualCriticAgent分析截图并识别设计质量问题

- 评估间距、一致性、可读性、布局 - 描述设计语言中的问题（而非代码问题） - 建议应改进的是什么（目标，而非实施方式）

1. 并行生成变体每个变体都独立地经历其完整的生命周期：

- 变体1保守方法（安全、最小化改动） - 变体2积极策略（采用粗体格式，优化空间） - 变体3+均衡的方法

1. 并行处理流水线每个变体同时执行：

- 格式化代理：将评论转换为LaTeX修正建议 - 编译：编译-修复-再编译循环，直至成功 - 视觉验证：检测关键回归问题 - 精细化：使用分支判断（如需）修复关键问题

1. 主裁判评估StyleQualityAgent对比所有已完成的变体，并选择最佳的一个
2. 迭代如果分数为“需改进”，则根据评委反馈重新进行

质量标准与评分

法官采用科学的评分方法来评估变体：

四个质量维度（加权）

• 设计一致性（30%）统一、有意识的设计系统
• 空间效率（25%）有效利用垂直空间
• 视觉一致性（25%）相似元素之间采用统一格式
• 可读性（20%）轻松扫描信息并导航

质量阈值

• “pass”总分≥0.75且所有指标≥0.65
• “needs_improvement”翻译成中文是“有待改进”0.55 ≤ 分数 \< 0.75 或任何指标 \< 0.65 但 ≥ 0.45
• “失败”分数 \< 0.55 或任何指标 \< 0.45

迭代控制

• 提前终止当裁判返回“通过”分数时，系统停止
• 最大迭代次数尊重 max_iterations 参数
• 法官反馈每次迭代都利用之前评估的反馈信息

文件命名系统

该系统采用了清晰、描述性的命名约定：

Base variants:     iter1_var1.tex, iter1_var2.pdf           (iteration 1, variant 1/2)
Refined variants:  iter1_var1_refined.tex, iter1_var2_refined.pdf  (iteration 1, variant 1/2, refined)
Backup files:      iter1_var1_backup_20251006_145832.tex    (organized backups with timestamps)

新命名的好处：

• 清晰的结构易于理解迭代与变体之间的关系
• 线性进度文件按时间顺序组织
• 版本跟踪精炼版与基础版有明显区别
• 备份组织带有描述性前缀的时间戳备份

增强的法官日志记录

该系统提供了对法官裁决的清晰可见性：

⚖️  MAIN JUDGE: Comparing 2 variants (Iteration 1)
📄 Original PDF: schwab_cv_iterative.pdf
📊 Variants to compare:
  📄 Variant 1 (original): iter1_var1.pdf
  📄 Variant 2 (refined): iter1_var2_refined.pdf
──────────────────────────────────────────────────────────────────────

🏆 MAIN JUDGE RESULT: Selected Variant 2 (refined)
📄 Winning file: iter1_var2_refined.pdf
📊 Score: pass
──────────────────────────────────────────────────────────────────────

🔍 故障排除

未找到 LaTeX

# Check installation
pixi run check-latex

# Verify LaTeX is in PATH
which pdflatex

# Install LaTeX (see Installation section)

编译错误

该系统通过“编译-修正-再编译”的循环自动修复大多数LaTeX错误。如果问题仍然存在：

1. 检查控制台输出中的错误日志
2. 审查生成的内容 .tex 文件存入 ./output/
3. 尝试增加 max_compile_attempts

风格改进问题

如果风格改进失败：

1. 确保已安装 Playwright 浏览器： pixi run playwright install
2. 检查第二阶段是否成功生成了PDF文件
3. 尝试使用 --variants 1 --no-quality 禁用判断

提前终止迭代

如果迭代在达到之前就停止了 max_iterations：

1. 检查裁判分数查找“✅ 质量标准已满足！停止迭代。"
2. 裁判判罚过宽质量评判员可能过于轻易地给出“通过”分数
3. 当前期刊法官在问题仍存时仍判定“通过”，导致提前终止
4. 权宜之计；变通方法使用 --variants 1 禁用裁判，或修改质量阈值

成本管理

为降低API成本：

# Use fast mode (default)
pixi run generate-cv-fast

# Disable style improvement entirely
python -m cv_writer_mcp generate-cv-from-markdown input/cv.md --no-enable-style

# Single variant, no judge
python -m cv_writer_mcp generate-cv-from-markdown input/cv.md --variants 1

📊 性能

并行处理的优势

新的并行架构带来了显著的性能提升：

速度提升

之前（顺序）变体 → 等待全部 → 验证 → 精炼 → 判定 之后（并行）每个变体：生成 → 编译 → 验证 → 优化 → 准备就绪

关键性能提升：

• 并行验证无需等待所有变体完成
• 独立细化每个变体独立优化
• 更快的迭代降低了整体管道延迟
• 资源利用率提高CPU和I/O操作并发进行

*时间仅为近似值，具体取决于CV的复杂性和API的延迟*

🤝 贡献（或“参与贡献”）

1. 为仓库创建分支（或：克隆仓库）
2. 创建一个特性分支： git checkout -b feature-name
3. 进行修改并添加测试
4. 运行检查： pixi run ci
5. 提交： git commit -m "Add feature"
6. 推送并提交拉取请求

📄 许可证

MIT 许可证 - 详情请参阅 LICENSE 文件。

👤 作者

弗朗西斯科·佩雷斯-索罗斯萨尔

• 电子邮箱：fperezsorrosal@gmail.com
• GitHub： @弗朗西斯科-佩雷斯-索罗萨尔

🙏 致谢

构建于：

• OpenAI 代理软件开发工具包（SDK）
• FastMCP
• 模型上下文协议