# JobOK MCP

> 把「求职全流程」装进你的 AI 客户端：简历打分、按 JD 定制改写、ATS 优化、面试题库、模拟面试、投递管理、复盘规划——全部用自然语言对话完成。

[![MCP](https://img.shields.io/badge/MCP-1.x-7C3AED)](https://modelcontextprotocol.io)
[![Node](https://img.shields.io/badge/node-%3E%3D18-339933)](https://nodejs.org)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue)](./LICENSE)
[![Tools](https://img.shields.io/badge/tools-40-orange)](#-工具一览)

---

## 为什么做这个

求职不是「改一份简历」那么简单，而是一条链路：**挖优势 → 定方向 → 改简历 → 过 ATS → 拿面试 → 面完复盘 → 管理投递**。
中间还要反复回答同样的问题、维护散落在备忘录和 Excel 里的投递记录。

JobOK MCP 把这套链路做成了 **40 个 MCP 工具**，接进 Claude Desktop / Cursor / Cline 等任意 MCP 客户端后，你只需说人话：

- 「帮我挖掘个人优势」→ 把零散经历挖成一条条**可验证的优势**（证据 → 行为 → 能力 → 岗位信号）
- 「用这个 JD 给我打分」→ 拿到分维度评分、缺失关键词、投递建议
- 「按这个 JD 帮我改简历」→ 拿到改写对照表 + 完整优化稿（**只改你真实写过的经历**）
- 「开始模拟面试，你当面试官」→ 多轮问答 + 逐题点评 + 复盘报告
- 「记录投递：字节-前端，已投递」→ 本地持久化，随时看投递漏斗

### 三个核心差异点

1. **优势 = 走完四步的证据链，不是性格标签**
   挖掘出的每条优势都必须填满 `证据 → 行为 → 能力 → 岗位信号` 四步，缺一步就不算优势：`strength_save` 会逐字段校验，链条不完整、证据空泛、或把「我沟通能力强」这类性格词当结论的，一律拒绝入库。
2. **证据链护栏，不编造**
   所有生成内容都要求同样的闭环。简历里没有的数据不会被凭空造出来，缺证据的地方会被标注「待补证据」，提示你补料，而不是替你编。
3. **确定性评分，可复现**
   匹配打分先由本地脚本按「信号词 + 平方根压缩曲线」算出**基线分**，再由模型在基线上调整并给出理由（偏差 ≥ 15 分必须解释）。同一份简历 + 同一个 JD，分数稳定、可对比、可追踪。

---

## 快速开始（3 分钟）

### 1. 装好 Node.js

需要 **Node.js ≥ 18**。`node -v` 检查一下即可。

### 2. 配置你的 MCP 客户端

把下面这段贴进对应客户端的配置文件即可（`jobok-mcp` 会自动构建）。

<details open>
<summary><b>Claude Desktop</b>（macOS: <code>~/Library/Application Support/Claude/claude_desktop_config.json</code> / Windows: <code>%APPDATA%\Claude\claude_desktop_config.json</code>）</summary>

```json
{
  "mcpServers": {
    "jobok": {
      "command": "npx",
      "args": ["-y", "jobok-mcp"]
    }
  }
}
```
</details>

<details>
<summary><b>Cursor</b>（<code>~/.cursor/mcp.json</code> 或项目内 <code>.cursor/mcp.json</code>）</summary>

```json
{
  "mcpServers": {
    "jobok": {
      "command": "npx",
      "args": ["-y", "jobok-mcp"]
    }
  }
}
```
</details>

<details>
<summary><b>Cline / VS Code (Copilot / Continue)</b></summary>

```json
{
  "mcpServers": {
    "jobok": {
      "command": "npx",
      "args": ["-y", "jobok-mcp"],
      "env": {}
    }
  }
}
```
</details>

<details>
<summary><b>本地源码运行</b>（想改代码 / 没发布到 npm 时）</summary>

```bash
git clone https://github.com/your-github-name/jobok-mcp.git
cd jobok-mcp
npm install     # 会自动执行 npm run build
```

配置里改用绝对路径：

```json
{
  "mcpServers": {
    "jobok": {
      "command": "node",
      "args": ["C:/path/to/jobok-mcp/dist/index.js"]
    }
  }
}
```
</details>

> 若想用 `npx jobok-mcp`，需要先执行过 `npm publish`（把 `package.json` 里的 `your-github-name` 换成你自己的仓库地址即可）。

### 3. 开始对话

重启客户端后，先对 AI 说一句：

> **帮我上手 jobok**

它会调用 `jobok_quickstart` 返回完整的 5 步流程与示例口令。也可以直接说：

```
设置我的求职画像：方向 Web3 前端，3 年经验，目标岗位 前端工程师，意向城市 上海/远程
加载我的简历：C:\Users\me\Desktop\resume.pdf
帮我挖掘个人优势：我做过一个钱包聚合页面，主导了…（把零散经历说出来）
用这个 JD 给我打分：{把 JD 原文贴进来}
```


---

## 五分钟体验路径

| 步骤 | 你说的话 | 触发的工具 |
| --- | --- | --- |
| 1 | 设置我的求职画像：方向 Web3 前端，3 年经验… | `profile_save` |
| 2 | 加载我的简历：`C:\Users\me\Desktop\resume.pdf` | `resume_load` |
| 3 | 帮我挖掘个人优势：{把零散经历说出来} | `strength_mine` → `strength_save` |
| 4 | 用这个 JD 给我打分：{JD 原文} | `resume_score_match` |
| 5 | 按这个 JD 帮我改简历：{JD 原文} | `resume_rewrite`（自动复用优势） |
| 6 | 帮我做 ATS 关键词体检：{JD 原文} | `ats_optimize` |
| 7 | 按这个 JD 出 5 道面试题 | `interview_question_bank` |
| 8 | 开始模拟面试，你当面试官：{JD 原文} | `mock_interview_start` |
| 9 | 记录投递：字节跳动-前端工程师，已投递 | `application_add` |
| 10 | 帮我复盘最近两周的投递情况 | `job_search_review` |

不想记工具名？`examples/` 里有可直接用的示例简历与 JD：

- `examples/sample-resume.md`
- `examples/sample-jd.md`
- `examples/sample-profile.json`

---

## 🧰 工具一览（40 个）

<details open>
<summary><b>引导 / 数据（4）</b></summary>

| 工具 | 说明 |
| --- | --- |
| `jobok_quickstart` | 3 分钟上手引导 + 工具速查 + 示例口令 |
| `jobok_workflow` | 按场景（求职启动 / 冲刺岗位 / 面试准备 / 面试后复盘 / 投递管理 / 能力提升）给出工具串联步骤 |
| `data_info` | 查看数据目录、各文件条数与隐私策略 |
| `data_export` | 一键备份/导出全部求职数据 |
</details>

<details>
<summary><b>画像 / 简历（9）</b></summary>

| 工具 | 说明 |
| --- | --- |
| `profile_save` / `profile_get` | 保存 / 查看求职者画像 |
| `resume_load` / `resume_get` | 加载（**pdf · docx · md · txt**）/ 查看简历 |
| `resume_score_match` | 简历-JD 匹配打分（确定性基线 + 多维拆解 + 风险点） |
| `resume_rewrite` | 按 JD 定制改写（STAR + 量化 + 证据链 + `needs_proof` 标注） |
| `ats_optimize` | ATS 关键词覆盖度体检 |
| `cover_letter_generate` | 生成定制求职信 |
| `resume_export` | 把优化稿导出成本地文件，直接当附件投递 |
</details>

<details>
<summary><b>优势挖掘（4）</b></summary>

| 工具 | 说明 |
| --- | --- |
| `strength_mine` | 从简历 + 零散素材挖掘优势，每条强制走完**四步链条**并标注 10 类能力分类 |
| `strength_save` | 沉淀一条优势：`证据 → 行为 → 能力 → 岗位信号` **缺一即拒绝入库** |
| `strength_list` | 查看已沉淀优势与链条完整度 |
| `strength_delete` | 删除一条优势 |

**每条优势长这样（缺任一步会被 `strength_save` 拒绝）：**

```
### 优势：跨团队推动落地
- 分类：沟通协作            - 分级：fact            - 证据强度：high
- ① 证据：主导 3 人跨端项目，2 周内推动前后端+设计对齐接口，上线零回滚
- ② 行为：由我拆解任务、定接口规范，每两天同步一次风险清单并推动决策
- ③ 能力：把模糊目标拆成可执行里程碑，并推动多方按期交付
- ④ 岗位信号：需要跨职能协作、能把控交付节奏的工程/项目岗
- 待补证据：无
```

沉淀后，`resume_rewrite` / `cover_letter_generate` / `interview_question_bank` / `mock_interview` 会**自动复用**这些优势。
</details>

<details>
<summary><b>面试（6）</b></summary>

| 工具 | 说明 |
| --- | --- |
| `interview_question_bank` | 6 类面试题库（基础 / 项目深挖 / 领域专项 / 工程化 / 安全 / 软技能）+ 必背 TOP5 |
| `mock_interview_start` / `mock_interview_answer` / `mock_interview_end` | 模拟面试全流程（多轮问答 + 逐题点评 + 复盘） |
| `mock_interview_list` | 历史模拟面试会话 |
| `interview_review` | 任意真实/模拟面试记录深度复盘 |
</details>

<details>
<summary><b>投递 / 归档（9）</b></summary>

| 工具 | 说明 |
| --- | --- |
| `application_add` / `list` / `update` / `delete` | 投递记录增删改查（状态变更自动写历史） |
| `application_stats` | 投递漏斗看板（投递 → 面试 → Offer 转化率） |
| `job_archive_add` / `list` / `delete` | 岗位归档（收藏 / 长期跟踪） |
| `job_archive_to_application` | 归档岗位一键转投递记录 |
</details>

<details>
<summary><b>分析 / 规划（4）</b></summary>

| 工具 | 说明 |
| --- | --- |
| `gap_analysis` | 短板分析与能力盘点（能力雷达 + 短板 TOP5 + 可迁移优势） |
| `learning_path_generate` | 生成逐周冲刺学习路线（含实战项目与验收机制） |
| `job_search_review` | 求职整体复盘（漏斗洞察 + 瓶颈诊断 + 下阶段目标） |
| `analysis_history` | 历史分析报告与学习路线 |
</details>

<details>
<summary><b>兼容旧版（4）</b></summary>

`job_score_match`、`generate_interview_question`、`add_application_record`、`interview_summary` —— 保留旧工具名映射到新实现，升级不破坏已有配置。
</details>

---

## 🔒 数据与隐私

- 所有数据保存在本机：默认 `~/.jobok/`（Windows：`C:\Users\<你>\.jobok\`）。
- 可用环境变量 `JOBOK_DATA_DIR` 自定义数据目录。
- 写入采用「临时文件 + rename」原子写，避免中途损坏。
- JobOK MCP **不联网、不上传、不采集**任何信息；生成类工具只返回结构化提示词，由你的 AI 客户端产出内容。
- 查看数据位置：`data_info`；备份/换机：`data_export`。

```
~/.jobok/
├── profile.json            求职画像
├── resume.json             当前简历
├── applications.json       投递记录
├── job-archives.json       岗位归档
├── interview-sessions.json 模拟面试会话
├── learning-plans.json     学习路线
├── analysis-reports.json   分析报告
└── strengths.json          已沉淀的个人优势（四步链条）
```

---

## 🏗 项目结构

```
jobok-mcp/
├── src/
│   ├── index.ts            入口：McpServer + 工具注册 + 兼容层
│   ├── config.ts           数据目录 / 状态枚举 / 优势能力分类
│   ├── types.ts            领域模型
│   ├── store.ts            JSON 原子持久化
│   ├── prompts.ts          Prompt 模板库（含证据链与真实性护栏）
│   ├── scoring.ts          确定性评分（信号词 + 平方根压缩曲线）
│   ├── shims.d.ts          可选依赖的类型声明
│   └── tools/
│       ├── helpers.ts      统一 context / 错误 / 返回封装
│       ├── guide.ts        上手引导与场景工作流
│       ├── resume.ts       简历模块（多格式解析 + 打分 + 改写 + 导出）
│       ├── strength.ts     优势挖掘模块（四步链条校验）
│       ├── interview.ts    面试模块
│       ├── application.ts  投递与归档
│       ├── analysis.ts     短板分析与规划
│       └── data.ts         数据查看与备份
├── examples/               示例简历 / JD / 画像
├── dist/                   构建产物
└── package.json
```

开发：

```bash
npm run build   # 编译
npm start       # 直接以 stdio 方式启动
npm run dev     # ts-node 调试
```

---

## ❓ FAQ

**简历是 PDF，能用吗？**
能。`resume_load` 支持 `.pdf / .docx / .md / .txt`。扫描版（图片型）PDF 无法提取文字，请用文字版或直接粘贴文字。
若提示缺少依赖，安装可选依赖即可：`npm i pdf-parse mammoth`。

**会帮我编造经历吗？**
不会。生成规则内置真实性护栏：没有证据的经历不会被虚构，缺证据处会标「待补证据」提醒你补充真实素材。

**优势挖掘会不会挖出「我沟通能力强」这种空话？**
不会。每条优势必须走完 `证据 → 行为 → 能力 → 岗位信号` 四步，`strength_save` 会逐字段校验：缺字段、证据过短、行为是「参与了/协助了」这类空话、或出现性格标签，都会被拒绝入库并告诉你差在哪。

**分数每次都不一样？**
基线分由本地脚本确定性计算，同一简历 + 同一 JD 结果一致；模型只做有限调整且需说明理由，偏差过大必须给出解释。

**数据会上传吗？**
不会。全部数据留在本机 `~/.jobok/`，服务不联网。

**支持多个求职方向 / 多份简历吗？**
可用 `JOBOK_DATA_DIR` 指向不同目录来隔离不同求职线的数据。

---

## 🗺 Roadmap

- [ ] 多案例（多求职线）隔离与一键切换
- [ ] 优势挖掘：支持上传作品/链接作为「证据强度=high」的外部凭证
- [ ] 简历 → PDF 排版导出
- [ ] 投递提醒（结合自动化定时任务）
- [ ] 更多行业 / 岗位的评分词典与面试题库模板
- [ ] 英文简历 / 英文面试场景

---

## 🤝 贡献

欢迎 issue 与 PR。如果这个项目帮到了你，欢迎点一个 ⭐ Star —— 这是对作者最大的鼓励，也能让更多正在找工作的人看到它。

## 📄 License

[MIT](./LICENSE)