# resume-mcp

> 把「AI 简历生成 / 优化」做成一个独立的 [MCP](https://modelcontextprotocol.io)（Model Context Protocol）Server，
> 让 **Claude Code**、**OpenHands**、**Claude Desktop** 等任意 MCP 客户端直接调用。

[![Python](https://img.shields.io/badge/python-3.10%2B-blue)](#)
[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)

## 是什么

一个纯 stdio 的 MCP 工具服务，核心链路：

```
上传简历 / 粘贴背景  →  提取文本  →  LLM 优化或生成  →  渲染 .docx + .pdf
```

- 从现有简历文件（PDF / Word）出发**优化**，或从零散背景信息**从零生成**
- 内置中文简历 prompt（STAR 法则 + 量化数据 + ATS 关键词）
- 产出排版好的 `.docx`（微软雅黑）和 `.pdf`（内置中文字体），并把文件绝对路径回传给调用方
- 无鉴权、无数据库、无历史记录 —— 一个「即插即用」的独立工具

## 提供的工具

### `optimize_resume` — 优化已有简历

| 参数 | 必填 | 说明 |
|---|---|---|
| `resume_file_path` | ✅ | 本地简历文件绝对路径（`.pdf` / `.docx` / `.doc`） |
| `job_position` | ✅ | 目标岗位，如「高级前端工程师」 |
| `requirements` |  | 额外要求，如「突出项目管理经验」 |
| `output_dir` |  | 输出目录，默认写到输入文件所在目录 |

### `generate_resume` — 从背景信息生成简历

| 参数 | 必填 | 说明 |
|---|---|---|
| `background` | ✅ | 背景信息（教育 / 工作 / 项目 / 技能等自由文本） |
| `job_position` | ✅ | 目标岗位 |
| `requirements` |  | 额外要求 |
| `output_dir` |  | 输出目录，默认写到当前工作目录 |

两者都返回：优化/生成说明、结构化 JSON，以及 `.docx` / `.pdf` 的绝对路径。

## 快速开始

### 1. 安装

需要 Python 3.10+。任选其一：

```bash
# 方式 A：uv（推荐）
uv tool install git+https://github.com/xiangwang331-boop/resume-mcp.git

# 方式 B：pipx
pipx install git+https://github.com/xiangwang331-boop/resume-mcp.git

# 方式 C：本地源码 + venv
git clone https://github.com/xiangwang331-boop/resume-mcp.git
cd resume-mcp
python -m venv .venv
.venv/Scripts/python -m pip install -e .      # Windows
# .venv/bin/python -m pip install -e .         # macOS / Linux
```

安装后会得到一个 `resume-mcp` 命令行入口。

### 2. 配置 LLM

简历的实际优化/生成由一个 LLM 完成（默认 DeepSeek，兼容任意 OpenAI 风格端点）。
按优先级读取以下来源：

1. 进程环境变量 `LLM_MODEL` / `LLM_API_KEY` / `LLM_BASE_URL`
2. `RESUME_ENV_FILE` 指定的 `.env` 文件
3. 当前目录下的 `.env`
4. 源码根目录下的 `.env`（本地开发用）

未配置 `LLM_API_KEY` 时，工具会返回明确的报错提示。

### 3. 接入客户端

#### Claude Code

```bash
# 用 -e 把 LLM 配置传给 server（推荐，无需落盘 .env）
claude mcp add resume -- resume-mcp \
  -e LLM_MODEL=deepseek/deepseek-v4-pro \
  -e LLM_API_KEY=sk-xxxx \
  -e LLM_BASE_URL=https://api.deepseek.com
```

重启后 `/mcp` 应能看到 `resume` 及其两个工具，然后直接说：

> 用 generate_resume 根据这份背景生成一份「后端开发工程师」简历：……

#### OpenHands

设置 → MCP servers → 添加自定义 server → 类型选 `stdio`：

- **Command**：`resume-mcp`（或该命令的绝对路径）
- **env**：`LLM_MODEL`、`LLM_API_KEY`、`LLM_BASE_URL`

点「Test connection」应列出 `optimize_resume`、`generate_resume` 两个工具。

#### Claude Desktop / 其它 MCP 客户端

在 `claude_desktop_config.json`（或对应客户端的 `mcpServers`）里加：

```json
{
  "mcpServers": {
    "resume": {
      "command": "resume-mcp",
      "env": {
        "LLM_MODEL": "deepseek/deepseek-v4-pro",
        "LLM_API_KEY": "sk-xxxx",
        "LLM_BASE_URL": "https://api.deepseek.com"
      }
    }
  }
}
```

## 项目结构

```
resume-mcp/
├── pyproject.toml        # 依赖 + resume-mcp 命令行入口
├── resume_mcp/
│   ├── config.py         # LLM 配置加载
│   ├── engine.py         # 核心：提取文本 / LLM 调用 / 渲染 docx+pdf
│   └── server.py         # FastMCP server + 两个工具
├── .env.example
└── LICENSE
```

## 常见问题

### 报 `'Server' object has no attribute 'list_tools'`

MCP Python SDK `2.0.0` 移除了 FastMCP / `list_tools`。本项目已固定 `mcp>=1.2,<2.0`，
如你在自己的环境里遇到此问题，把 `mcp` 降到 `<2` 即可。

### 生成的简历文件在哪里？

MCP 工具运行在**客户端进程所在的那台机器**（不在沙箱 / 容器里）。文件写到
`output_dir` 指定目录（或默认目录），工具返回值里会带上绝对路径。

### 终端里中文显示乱码，但文件正常？

Windows 控制台默认 GBK 编码，`print` 输出会乱码；这不影响 `.docx` / `.pdf`
的实际内容（内置微软雅黑 / STSong-Light 中文字体）。

## 与 resume-generator 的关系

核心逻辑抽取自 `resume-generator` 后端 `backend/app/routers/resume.py`
（去掉了 FastAPI / JWT / 数据库）。`resume_mcp/engine.py` 是纯逻辑副本，
二者可能漂移；如需长期共用，可把 engine 提成独立包。

## License

[MIT](LICENSE)