# resume-repo-sync

基于 **官方 Python MCP SDK（FastMCP）** 的本地 MCP Server：  
根据 GitHub 仓库的**客观信号**自动生成简历「项目经历」bullet，合并进已有 PDF 简历的结构化数据，并用 HTML 模板 + WeasyPrint 导出新 PDF。

> **设计原则**  
> 1. 工具逻辑与 MCP 协议层分离（核心函数可脱离 MCP 单测）  
> 2. 依赖自包含：直接 `requests` 调 GitHub REST，不套第三方 GitHub MCP  
> 3. 只写可验证事实，禁止虚构「性能提升 50%」类指标  
> 4. 不持久化用户简历 / token；临时文件可过期清理  

---

## 功能一览

| # | Tool | 说明 |
|---|------|------|
| 1 | `parse_resume` | PDF → 结构化 `ResumeData` |
| 2 | `fetch_repo_info` | GitHub REST → `RepoInfo`（含 `topics`、`contributor_stats`） |
| 3 | `analyze_repo_for_resume` | 客观技术要点 + `contribution_level` + `absolute_contribution_signal` |
| 4 | `generate_bullet_points` | 按贡献级别 / 绝对提交量收敛措辞；negligible 可跳过整段项目 |
| 5 | `merge_into_resume` | 插入/覆盖项目（冲突 → `project_already_exists`） |
| 6 | `diff_resume_versions` | 项目粒度人类可读 diff |
| 7 | `render_pdf` | Jinja2 模板 + WeasyPrint → PDF（`modern` / `compact`） |

推荐调用顺序：

```
parse_resume
  → fetch_repo_info(github_username?)
  → analyze_repo_for_resume(github_username?, target_role?)
  → generate_bullet_points          # 若 skip_project_entry 则不要 merge
  → merge_into_resume
  → diff_resume_versions
  → render_pdf(template=modern|compact)
```

---

## 架构

```text
                    ┌─────────────────────────────────────┐
                    │  MCP Client (Claude Desktop /        │
                    │  Inspector / 其他 LLM Host)          │
                    └─────────────────┬───────────────────┘
                                      │ stdio
                    ┌─────────────────▼───────────────────┐
                    │  server.py  (FastMCP Tool 注册)      │
                    │  仅做参数校验 + envelope 序列化         │
                    └─────────────────┬───────────────────┘
                                      │ 调用纯 Python 函数
        ┌──────────────┬──────────────┼──────────────┬──────────────┐
        ▼              ▼              ▼              ▼              ▼
   resume/         github/      generation/      cleanup.py     config.py
   parser          fetcher      bullet_writer    TTL / rmtree   GITHUB_TOKEN
   merge           analyzer
   diff
   renderer ──► templates/{modern,compact}.html ──► WeasyPrint PDF
```

**分层收益**：业务模块无 `mcp` import → `pytest` 直接测；换 transport（未来 HTTP）不必动分析/渲染逻辑。

---

## 项目结构

```
resume-repo-sync/
├── src/resume_repo_sync/
│   ├── server.py                 # FastMCP + Tool 注册（stdio）
│   ├── config.py                 # 环境变量 / TTL
│   ├── cleanup.py                # 临时文件清理
│   ├── resume/
│   │   ├── schema.py             # Pydantic 模型 + ToolErrorCode
│   │   ├── parser.py             # pdfplumber 解析
│   │   ├── merge.py / diff.py
│   │   └── renderer.py           # Jinja2 + WeasyPrint
│   ├── github/
│   │   ├── fetcher.py            # REST：meta / languages / README /
│   │   │                         # commits / contributors / deps
│   │   └── analyzer.py           # 客观分析 + 贡献分级
│   └── generation/
│       └── bullet_writer.py      # bullet 措辞（含 negligible 跳过）
├── templates/
│   ├── modern.html               # 单栏宽松
│   └── compact.html              # 双栏紧凑
├── scripts/e2e_demo.py
├── tests/
├── pyproject.toml
├── .env.example
└── README.md
```

---

## 快速开始

### 1. 安装

需要 Python ≥ 3.11，推荐 [uv](https://github.com/astral-sh/uv)：

```bash
cd resume-repo-sync
uv sync --extra dev
```

#### WeasyPrint（Windows）

```bash
winget install --id tschoonj.GTKForWindows --accept-package-agreements
# bin 通常在: C:\Program Files\GTK3-Runtime Win64\bin
# renderer 会自动探测；也可设 WEASYPRINT_GTK_BIN
```

中文字体栈（两套模板共用）：`Microsoft YaHei` / `Noto Sans SC` / `SimSun`。  
本机验证：PDF 嵌入 **Microsoft YaHei**，`pdfplumber` 可提取「张三」「清华大学」等中文。

### 2. 配置

```bash
cp .env.example .env
```

| 变量 | 说明 |
|------|------|
| `GITHUB_TOKEN` | 私有仓 / 提高 API 限额（可选） |
| `RESUME_TMP_DIR` | managed 临时 PDF 根目录 |
| `PDF_TMP_TTL_HOURS` | managed PDF 过期小时数（默认 24；`0`=每次清空） |
| `WEASYPRINT_GTK_BIN` | Windows GTK `bin` 覆盖 |
| `LOG_LEVEL` | 默认 `INFO`（仅操作状态，无简历正文/token） |

### 3. 测试 / 演示 / 启动

```bash
uv run pytest -q

# 端到端（内置样例简历 + 真实公开仓）
uv run python scripts/e2e_demo.py

# MCP stdio
uv run resume-repo-sync

# Inspector
uv run mcp dev src/resume_repo_sync/server.py
```

### 4. Claude Desktop（可选）

`%APPDATA%\Claude\claude_desktop_config.json`：

```json
{
  "mcpServers": {
    "resume-repo-sync": {
      "command": "uv",
      "args": [
        "--directory",
        "C:\\Users\\admin\\Desktop\\resume-repo-sync",
        "run",
        "resume-repo-sync"
      ],
      "env": { "GITHUB_TOKEN": "ghp_xxxxxxxx" }
    }
  }
}
```

---

## PDF 模板对比

两套模板都是 **Jinja2 + 中文字体栈**，通过 `render_pdf(..., template="...")` 切换；  
未知名称返回 **`template_not_found`**（列出可用模板），**不会**静默回退默认模板。

| 维度 | `modern`（默认） | `compact` |
|------|------------------|-----------|
| 布局 | **单栏**纵向流式 | **双栏**：左轨（联系/技能/教育）+ 右主栏（工作/项目） |
| 页边距 | 约 1.6–1.8cm，留白较多 | 约 1.0–1.1cm，信息密度更高 |
| 字号层级 | 姓名 ~20pt，章节 ~12pt，正文 ~10.5pt | 姓名 ~16pt，章节小写标题 ~8.5pt，正文 ~8.5–9pt |
| 章节样式 | 粗下划线 `h2` 分区 | 大写细线 `block-title`，条目更紧 |
| 项目展示 | 每条 bullet 间距宽松，技术栈单独一行 | `ul.dense` 紧凑列表，技术栈斜体一行塞入 |
| 适合场景 | 一页内项目不多、希望阅读舒适 | 内容多、希望压到一页 / ATS 友好密集版 |

调用示例：

```text
render_pdf(resume_data, template="modern")
render_pdf(resume_data, template="compact")
render_pdf(resume_data, template="nope")  → error_code=template_not_found
```

在 `templates/` 下新增 `*.html` 即可扩展；`list_templates()` / 错误详情会自动发现。

---

## 端到端示例

```text
1) parse_resume(pdf_path)
2) fetch_repo_info(repo_url, github_username?)
3) analyze_repo_for_resume(repo_info, github_username?, target_role?)
     → contribution_level + absolute_contribution_signal
4) generate_bullet_points(analysis)
     → 若 skip_project_entry=true：不要 merge，按 recommendation 处理
5) merge_into_resume(...)
6) diff_resume_versions(old, new)   # 人工确认
7) render_pdf(..., template="compact")  # 或 modern
```

实测（样例简历 + `modelcontextprotocol/python-sdk`）会在 diff 中看到类似：

```text
+ 新增项目 [0] python-sdk
    • 参与… / 使用 Python… / 项目获得 N GitHub Stars
```

---

## 贡献分级（简历诚信）

**占比** → `contribution_level`：

| level | 条件 |
|-------|------|
| `primary` | ≥ 50% listed contributions |
| `contributor` | 20% – <50% |
| `minor` | < 20% |
| `unknown` | 无数据 |

**绝对次数** → `absolute_contribution_signal`（用于细分 **minor** 措辞）：

| signal | 绝对 listed contributions | minor 时 bullet |
|--------|---------------------------|-----------------|
| `negligible` | < 3 | **不生成**完整项目条；`skip_project_entry` + recommendation |
| `moderate` | 3–19 | 「参与贡献 / 协助」 |
| `substantial` | ≥ 20 | 写明具体提交次数；仍禁止「主导/独立完成」 |
| `unknown` | 无数据 | 中性措辞 |

大仓里「占比低但提交多」与「几乎没贡献」不再混为一谈。

---

## 隐私与数据保留

| 数据 | 落盘？ | 保留 |
|------|--------|------|
| 用户简历 PDF | 只读，不复制 | 用户自管 |
| 解析 workdir | 系统 temp 私有目录 | **返回前必删**（含异常 `finally`） |
| `ResumeData` / `RepoInfo` | 仅内存 / MCP 响应 | 进程结束即消失 |
| `render_pdf` 默认输出 | `{system_temp}/resume-repo-sync/resume-*.pdf` | TTL（默认 24h）自动删 |
| 显式 `output_path` | 调用方路径 | **永不自动删** |
| `GITHUB_TOKEN` | 环境变量 / `.env` | 不写日志 |

日志只记 ok/fail、basename、计数——**不**记简历正文、bullet、token。  
`.gitignore` 已屏蔽 `.env`、`*.pdf`、`uploads/`、`output/`、`tmp/` 等。

---

## 设计决策（展示 / 面试）

1. **自包含 GitHub REST，而不是嵌一层 GitHub MCP**  
   错误语义可控（私有仓 / 限流 / 404 → 稳定 `ToolErrorCode`），部署少一个进程。
2. **业务不写在 `@mcp.tool` 里**  
   普通函数可 `pytest`；MCP 层只做 IO envelope。
3. **解析用启发式，不调 LLM**  
   行为可预测、零额外 API 成本；极端版式用 `parse_warnings` / `raw_text` 交给上层模型兜底。
4. **WeasyPrint + Jinja2**  
   排版与逻辑分离；加模板 = 加 HTML 文件，无需改 Python 分支。
5. **贡献分级驱动措辞**  
   避免把「大仓里提过几个 PR」写成「独立主导」，保证可验证与诚信。

---

## MCP Inspector 速查

```bash
uv run mcp dev src/resume_repo_sync/server.py
```

- **模板切换**：`render_pdf` 的 `template` 分别试 `modern`、`compact`；再试 `does-not-exist` → `template_not_found`。  
- **negligible**：公开大仓 + 不存在的 `github_username` → `skip_project_entry=true`。  
- **冲突**：`merge_into_resume` 同名且 `overwrite=false` → `project_already_exists`。

---

## License

MIT