Resume MCP Server

Resume MCP Server

一个用于 AI 驱动的简历定制的 Model Context Protocol（MCP）服务。此服务可根据特定职位描述自动定制简历，并生成 Markdown 和 LaTeX/PDF 版本，以便通过 ATS 系统筛选。

🚀 功能

• 简历定制：生成针对特定职位描述的定制简历
• LaTeX 支持：使用 LaTeX 模板导出为专业的 PDF 格式
• Obsidian 集成：搜索和管理 Obsidian 库中的文件
• 职业指导：获取简历反馈和职业选择建议
• MCP 协议：遵循 Model Context Protocol，实现无缝 AI 集成

📋 前置条件

• Python 3.10 或更高版本
• Docker 或 Podman（用于 LaTeX 编译服务）
• Node.js/npm（用于 MCP Inspector）
• Obsidian（可选，用于库集成）
  • 如果不使用 Obsidian，可以使用文件系统中的任意目录，只需确保在 .env 文件中设置 OBSIDIAN_VAULT 变量。

⚙️ 安装

1. 克隆仓库：

   git clone https://github.com/yourusername/resume-mcp.git
   cd resume-mcp
   

2. 安装所需的 Python 依赖项：

   pip install -r requirements.txt
   # Or using uv (recommended for better dependency resolution)
   uv pip install -e .
   

3. 启动 LaTeX 编译服务（生成 PDF 所必需）：

   # Using Docker
   cd latex-compilation-server
   docker-compose up -d
   cd ..
   
   # OR using Podman
   cd latex-compilation-server
   podman-compose up -d
   cd ..
   

   你可以通过以下命令验证服务是否正在运行：

   curl http://localhost:7474/health
   

4. 安装 MCP Inspector（用于调试/开发）：

   npm install -g @modelcontextprotocol/inspector
   

初始仓库设置

如果克隆仓库时没有使用 --recursive 标志，可能需要初始化 LaTeX 编译服务子模块：

git submodule init
git submodule update

这样可以确保 latex-compilation-server 目录中包含完整的 LaTeX 编译服务代码。

🔧 配置

在根目录中创建 .env 文件，并添加以下变量（也可以在环境中配置这些变量）：

# Server configuration
SERVER_NAME="Resume Tailoring Server"

# File paths
BASELINE_RESUME_PATH="./templates/baseline_resume.md"
PROMPT_TEMPLATE_PATH="./templates/prompt_template.md"
LATEX_TEMPLATE_PATH="./templates/latex_template.tex"
OUTPUT_DIRECTORY="./templates/tailored_resumes"

# Obsidian vault configuration (optional)
OBSIDIAN_VAULT="/path/to/your/obsidian/vault"

# LaTeX compilation server configuration
LATEX_SERVER_URL="http://localhost:7474"
LATEX_OUTPUT_DIR="./templates/latex_output"

# Logging
LOG_LEVEL="INFO"

# Anthropic API key (if using Anthropic models)
ANTHROPIC_API_KEY="your_anthropic_api_key"

🏃‍♂️ 运行服务

标准模式

要以标准模式运行服务：

python main.py

服务将以 stdio 传输模式启动，因此可以连接到任何兼容 MCP 的客户端。

使用 Inspector（开发/调试模式）

在开发和测试期间，可以使用 MCP Inspector 运行服务：

# Using the provided script
./inspect.sh

# Or manually
npx @modelcontextprotocol/inspector uv run main.py

调试问题

如果遇到服务问题，可以运行调试脚本：

python debug_server.py

该脚本会对你的设置执行各种检查，帮助找出问题。

🧠 使用 Resume MCP Server

该服务提供了多个用于定制简历的提示词和工具：

提示词

与服务交互的最简单方式是使用提供的提示词：

1. 定制简历 - 根据职位描述创建定制简历
2. 职业指导 - 获取职业建议和简历反馈

系统中必须包含这些提示词所需的模板，并通过 .env 文件进行配置。

或者，你可以修改提示词，让大模型向你询问所需的输入。你也可以使用 MCP 工具访问文件系统中的相关文件，例如基础简历或职位描述。

工具

1. 管理工具：

   • list_templates：列出可用模板
   • get_baseline_resume：获取你的基础简历

2. 验证工具：

   • validate_latex_template：检查 LaTeX 模板是否有效
   • check_latex_server：检查 LaTeX 编译服务是否可用
   • check_latex_server_status：获取 LaTeX 服务的详细状态
   • start_latex_server_help：获取启动 LaTeX 服务的说明

3. Obsidian 工具：

   • search_obsidian：搜索 Obsidian 库中的文件
   • read_obsidian_file：读取 Obsidian 文件中的内容

4. 简历工具：

   • save_tailored_cv：以 Markdown 格式保存定制后的简历
   • generate_latex_cv：使用安全的容器化 LaTeX 编译服务，将定制后的简历转换为 LaTeX/PDF

🖨️ LaTeX 编译服务

本项目包含一项容器化 LaTeX 编译服务，无需在本地系统安装 LaTeX，即可安全地从 LaTeX 文档生成 PDF 文件。该服务作为独立微服务运行在 Docker 容器中，并作为子模块包含在此代码库的 latex-compilation-server 目录中。

优势：

• 安全性：在 Docker 容器中隔离 LaTeX 编译，防止潜在的系统命令利用
• 一致性：在所有平台（macOS、Windows、Linux）上的运行方式都相同
• 简化设置：无需在本地安装 LaTeX 及其依赖项

工作原理：

1. MCP 服务将 LaTeX 内容发送到容器化 HTTP 服务
2. 服务在隔离环境中编译文档
3. 编译后的 PDF 返回给 MCP 服务
4. PDF 保存到你指定的输出目录

如需了解详细架构信息，请参阅 LaTeX 服务架构

管理：

使用 Docker 启动/停止服务：

cd latex-compilation-server
docker-compose up -d    # Start server
docker-compose down     # Stop server
docker-compose logs -f  # View logs

或使用 Podman：

cd latex-compilation-server
podman-compose up -d    # Start server
podman-compose down     # Stop server
podman-compose logs -f  # View logs

🛡️ 安全注意事项

LaTeX 编译安全

出于多项安全原因，本项目使用容器化 LaTeX 编译服务，而非直接调用系统命令：

1. 隔离：LaTeX 编译进程在 Docker 容器中运行，与宿主系统隔离
2. 不执行 Shell 命令：MCP 服务不会直接执行 Shell 命令，从而防止潜在的命令注入
3. 沙箱环境：LaTeX 代码在权限受限的受控环境中运行
4. 基于 API 的交互：所有通信都通过定义明确的 HTTP API 进行，而非执行 Shell 命令
5. 无状态处理：编译完成后，文件不会在容器中留存

这种架构可确保即使提交了恶意 LaTeX 文档，也无法访问或影响你的宿主系统。

📄 模板文件

基准简历

你的起始简历采用 Markdown 格式，后续定制版本由此创建。本项目包含一份示例基准简历，你可以修改其中的信息。

LaTeX 模板

用于生成专业 PDF 的 LaTeX 模板。模板必须包含必需的占位符（例如 $name、$profile、$technical_skills 等），这些占位符将替换为定制简历中的相应内容。

📚 示例工作流

1. 在 templates/baseline_resume.md 中设置基准简历
2. 在 templates/latex_template.tex 中配置 LaTeX 模板
3. 启动 LaTeX 编译服务：

   cd latex-compilation-server
   docker-compose up -d
   cd ..
   

4. 运行 MCP 服务：python main.py
5. 使用 MCP 客户端（例如集成式大模型）进行连接
6. 向“定制简历”提示词提交职位描述
7. 使用简历工具生成 LaTeX/PDF 版本
8. 检查并使用你的定制简历！

🔍 故障排除

常见问题与解决方案

LaTeX 模板问题

如果看到有关 LaTeX 模板缺少占位符的警告，请检查模板是否包含所有必需字段，例如 $name、$profile、$technical_skills 等。

初始化问题

如果遇到 RuntimeError: Received request before initialization was complete：

1. 导入组件后稍作等待
2. 检查 resume_mcp/mcp/__init__.py 中的导入结构，确保所有组件都已正确导入
3. 尝试使用调试服务运行，以定位具体问题：

   python debug_server.py
   

MCP 连接问题

如果客户端无法连接到服务：

1. 检查 stdio 传输是否正常工作
2. 确认所有必需组件都已导入
3. 使用检查器运行以查看详细日志：

   ./inspect.sh
   

Obsidian 集成问题

如果 Obsidian 集成无法正常工作：

1. 检查 .env 文件中的 OBSIDIAN_VAULT 路径
2. 检查 Obsidian 库目录的文件权限
3. 通过调试服务测试基本的 Obsidian 操作

LaTeX 编译服务问题

如果 PDF 生成失败：

1. 检查 LaTeX 服务是否正在运行：

   curl http://localhost:7474/health
   

2. 如果未运行，请启动服务：

   cd latex-compilation-server
   docker-compose up -d
   

3. 如果遇到问题，请检查服务日志：

   docker-compose logs latex-server
   

4. 如果需要重启服务：

   docker-compose restart latex-server
   

5. 确认 .env 文件中的服务 URL 正确：

   LATEX_SERVER_URL="http://localhost:7474"
   

高级调试

如需进行更详细的调试：

1. 在 .env 文件中设置 LOG_LEVEL="DEBUG"
2. 使用检查器运行服务，以获取详细日志
3. 检查 inspect.log 中的错误消息和执行流程
4. 使用 debug_server.py 脚本验证组件初始化情况

🧩 扩展服务

添加新提示词

在 resume_mcp/mcp/prompts 目录中创建新的提示词文件：

from resume_mcp.mcp.base import mcp

@mcp.prompt(name="My Custom Prompt")
def my_custom_prompt():
    return {
        "description": "Description of what this prompt does",
        "prompt": "Your prompt template here"
    }

添加新工具

在 resume_mcp/mcp/tools 目录中创建新的工具文件：

from resume_mcp.mcp.base import mcp

@mcp.tool()
def my_custom_tool(param1, param2=None):
    """Documentation for the tool.

    Args:
        param1: Description of param1
        param2: Description of param2
    """
    # Tool implementation
    return {"result": "Tool output"}

自定义模板

你可以在 templates/ 目录中创建自定义 LaTeX 模板。请确保：

1. 包含所有必需的占位符
2. 使用验证工具进行测试
3. 更新 .env 配置以使用新模板

📜 许可证

本项目采用 MIT 许可证授权，详情请参阅 LICENSE 文件。