# AI Job Intelligence MCP

<div align="center">

**本地求职智能分析与决策 MCP 服务**
*Personal AI Career Analyst & High-Precision Job Match Intelligence Server*

[![Python](https://img.shields.io/badge/Python-3.11%20%7C%203.12%20%7C%203.13-blue.svg)](https://www.python.org/)
[![MCP Protocol](https://img.shields.io/badge/MCP-2.1.1%2B-orange.svg)](https://modelcontextprotocol.io/)
[![Tests](https://img.shields.io/badge/Tests-442%20passed-brightgreen.svg)]()
[![Code Style](https://img.shields.io/badge/Code%20Style-Ruff-000000.svg)](https://github.com/astral-sh/ruff)
[![Type Checking](https://img.shields.io/badge/Types-Mypy-blue.svg)](https://mypy-lang.org/)
[![License](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)

[中文文档](README.md) | [English Documentation](README_en.md)

</div>

---

## 当前支持范围

本项目面向**单用户、本机 stdio、单个运行进程**。设置 `JOB_INTELLIGENCE_CANDIDATE_ID` 后，CLI 仅允许访问这个身份；更换身份应重启服务。直接嵌入 `create_mcp_server()` 的调用方需自己提供可信认证，不能把它直接暴露成多租户服务。

推荐使用规则、BM25 和离线哈希特征向量，未接入外部 LLM 或学习型 embedding，也不保证“零幻觉”或招聘成功率。反馈目前只记录，不改变排序。推荐快照和任务状态不会跨重启恢复。

目前真实摄入不提取结构化必需/可选技能，文本技能命中只是匹配信号。办公方式仅存为是否完全远程，混合办公不满足“仅远程”，但尚不能精确区分混合与现场偏好；旧库中的混合岗位需重新同步。远程岗位的国家/地区资格限制仍需人工核实。申请的自定义幂等键尚不能跨重启恢复，终态后同岗位重投也尚未支持持久化场景。

数据库删除由 `GDPRComplianceService` 服务 API 提供，尚无 MCP 删除工具。删除应在暂停该用户写入时进行；外部备份、旧数据脱敏迁移和多进程缓存同步需要另外管理。新写入画像、申请备注和反馈的文本会脱敏；不会自动清洗升级前的数据库。

容器采用与本地 CLI 相同的 stdio 入口，不提供 HTTP/SSE 端口或后台定时 Worker。不要用 `up -d` 代替 MCP 客户端连接。健康状态应以客户端 `initialize` 和工具调用结果验证。

## 📖 项目简介 (Introduction)

**AI Job Intelligence MCP** 是一套遵循 [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) 标准协议构建的**本地个人求职分析师与智能职位匹配服务**。

它旨在让 Claude Desktop、Cursor、Cline (Roo Code) 等大模型客户端化身为求职者的**专属职业顾问与决策智囊**。通过原生集成 19 个本地 MCP 标准化工具，系统深度覆盖了公开招聘看板与本地连接器摄入、特征结构化、事实归因推荐、全生命周期申请追踪、异步 SQLite 持久化存储、灾备容灾与候选人记录删除。

### 🌟 核心设计理念与本地特性 (Key Highlights)

1. **AI 招聘分析师，而非海投机器人 (Career Analyst, Not a Spam Bot)**
   - 坚决杜绝无脑批量海投、自动模拟点击或伪造履历等破坏求职生态的行为。
   - 专注于帮助求职者精准剖析职位画像、提炼自身核心优势、洞察技能短板并提供清晰的事实依据。
2. **规则打分与事实归因 (Fact-Based Grounding)**
   - 所有的职位匹配与分析结论，严格基于候选人简历特征与岗位实际 JD 的客观交集进行归因计算。
   - `RecommendationItem` 返回丰富的岗位信息（标题、公司、链接、0.0~1.0 匹配分），杜绝大模型脱离文本证据凭空臆造推荐理由。
3. **单机高可靠持久化 (Async SQLite with Cold Restart Recovery)**
   - 采用统一的 SQLAlchemy 2.0 异步 ORM 引擎与 aiosqlite 驱动，实现职位库、候选人画像、投递历史、反馈及看板元数据的单机事务持久化。
   - 进程重启后 自动加载已持久化的画像、申请、反馈和看板状态，推荐快照、任务进度和健康统计目前仍为进程内状态。
4. **4 阶规范化清洗管线与 5 重安全离线判据 (Canonical Ingestion & Safe Reconciliation)**
   - 严格执行 `Adapter -> Normalizer -> JobPostingAssembler -> Repository` 4 步摄入管线，多源对齐（Greenhouse, Lever 等）。
   - 实施 5 重严格准入的离线对齐算法（HTTP 200 准入、分页完整无截断、无适配器异常、全量快照声明、非空看板保护），杜绝网络抖动导致的误删职位。
5. **开箱即用工作区默认身份与人体工学别名 (Workspace Identity & Ergonomics)**
   - 支持通过环境变量 `JOB_INTELLIGENCE_CANDIDATE_ID` 设置工作区默认身份（缺省为 `default_user`），所有 MCP 工具的 `candidate_id` 均为可选参数，开箱即用。
   - 提供 `track_application` 人体工学别名，方便 AI Agent 一键追踪投递进展。

---

## 🏛️ 系统架构 (Architecture)

```mermaid
flowchart TD
    subgraph Clients["AI 客户端层 (AI Clients)"]
        C1["Claude Desktop"]
        C2["Cursor IDE"]
        C3["Cline / Roo Code"]
    end

    subgraph MCP["MCP 协议接口层 (19 Standardized Tools)"]
        T1["只读与检索 (6)"]
        T2["状态机与反馈追踪 (6)"]
        T3["可观测与诊断 (3)"]
        T4["公开看板管理与同步 (3)"]
    end

    subgraph Security["安全沙箱与防护网 (Security Sandbox)"]
        S1["PinnedAsyncHTTPTransport<br/>(防 SSRF & DNS 劫持)"]
        S2["PromptInjectionGuard<br/>(越狱拦截与文本清洗)"]
        S3["PrivacyGuard<br/>(PII 自动脱敏 & Canary 探针)"]
        S4["GDPRComplianceService<br/>(跨 5 大服务级联物理销毁)"]
    end

    subgraph Core["领域服务与摄入核心 (Core Services)"]
        D1["SourceCatalogService<br/>(看板注册中心)"]
        D2["Greenhouse / Lever Adapters<br/>(ATS 摄入适配器)"]
        D3["JobPostingAssembler<br/>(4 阶段规范化清洗)"]
        D4["Profile & Recommendation<br/>(归因打分与重排)"]
        D5["ApplicationService<br/>(乐观锁状态机)"]
        D6["DisasterRecoveryManager<br/>(两阶段原子灾备)"]
    end

    subgraph Storage["持久化存储层 (Async Persistence)"]
        DB[("SQLAlchemy 2.0 + SQLite<br/>(SCD Type 2 职位库 & 历史版本)")]
    end

    Clients -->|stdio| MCP
    MCP --> Security
    Security --> Core
    Core --> Storage
    Core -->|公网安全绑定| ExtATS["公开招聘看板<br/>(GitLab, Cloudflare, Palantir...)"]
```

---

## 🛠️ 19 个标准化 MCP 工具全景矩阵 (Tools Matrix)

> 💡 **提示**：所有需要 `candidate_id` 的工具均设为可选参数，未显式提供时自动读取工作区默认身份（环境变量 `JOB_INTELLIGENCE_CANDIDATE_ID`，默认为 `"default_user"`）。

### 1. 只读与推荐检索工具 (Read & Search - 6 个)
| 工具名称 | 核心参数 | 功能描述 |
| :--- | :--- | :--- |
| `search_jobs` | `keyword`, `limit=20`, `cursor` | 基于关键词在职位库中进行游标确定性分页检索 |
| `recommend_jobs` | `candidate_id="default_user"`, `limit=20`, `profile_version`, `force_refresh` | 基于候选人特征执行多路召回、打分重排，返回富文本 `RecommendationItem` |
| `get_recommendation` | `run_id`, `candidate_id="default_user"`, `limit=20`, `cursor` | 分页读取当前进程内的推荐快照；岗位详情使用 `get_job_explanation` |
| `get_job_explanation` | `job_id`, `candidate_id="default_user"` | 生成严格基于事实证据的岗位解读、优劣势对比与差距分析 |
| `get_profile` | `candidate_id="default_user"` | 查询指定求职者的结构化简历画像与技能清单（Anti-IDOR 隔离） |
| `upsert_profile` | `target_roles`, `skills`, `candidate_id="default_user"` | 新建或更新候选人画像，自动实施 PII 脱敏与内容安全清洗 |

### 2. 状态机与反馈追踪工具 (State Machine & Feedback - 6 个)
| 工具名称 | 核心参数 | 功能描述 |
| :--- | :--- | :--- |
| `apply_job` | `job_id`, `candidate_id="default_user"`, `dry_run=True`, `notes` | 记录申请。默认 `dry_run=True` 预览；真实写入需 `dry_run=False`。不向招聘网站投递，允许记录外部岗位 ID |
| `track_application` | `job_id`, `candidate_id="default_user"`, `status="applied"`, `notes=""` | 一键记录/跟进求职申请记录（`apply_job` 人体工学别名，默认真实入库） |
| `update_application_status` | `application_id`, `to_status`, `expected_version`, `candidate_id="default_user"` | 带版本号乐观锁的状态流转控制，拦截并发竞争与非法跳转 |
| `get_application` | `application_id`, `candidate_id="default_user"` | 查询指定投递申请的当前状态、历史版本与时间线 |
| `list_applications` | `candidate_id="default_user"`, `limit=20`, `cursor` | 游标分页获取指定求职者的所有申请记录，支持全序排重 |
| `record_feedback` | `job_id`, `action`, `candidate_id="default_user"`, `reason` | 记录对推荐职位的正负反馈（like, dislike, mismatch），持久化保存；当前尚未接入排序评分管道 |

### 3. 可观测与取消诊断工具 (Observability & Diagnostics - 3 个)
| 工具名称 | 核心参数 | 功能描述 |
| :--- | :--- | :--- |
| `get_run_progress` | `run_id`, `candidate_id="default_user"` | 实时查看管道摄入任务执行进度、吞吐量指标及子任务事件 |
| `cancel_run` | `run_id`, `candidate_id="default_user"`, `reason` | 发送协同取消信号，安全且幂等地中止后台管道任务 |
| `get_source_health` | `source=None`, `candidate_id="default_user"` | 查看指定或全部上游招聘数据源的健康状况、网络延迟与错误率 |

### 4. 动态公开看板管理工具 (Public Board Management - 3 个)
| 工具名称 | 核心参数 | 功能描述 |
| :--- | :--- | :--- |
| `list_registered_boards` | `candidate_id="default_user"`, `active_only=False` | 查看系统预置与用户注册的所有公开招聘看板及同步状态 |
| `register_job_board` | `platform`, `board_token`, `company_name` | 动态注册合规公开看板（支持 Greenhouse / Lever，内置路径穿越校验） |
| `sync_board_jobs` | `platform`, `board_token`, `limit_pages=1`, `dry_run=False` | 分页拉取指定公开看板最新岗位，执行 4 阶清洗与 5 重安全离线对齐入库 |

---

## 💻 AI 客户端接入预设 (Client Presets)

本项目已对主流 AI 客户端进行深度适配，可直接复制以下配置快速启动。

### 1. Claude Desktop
编辑 Claude Desktop 配置文件：
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "job-intelligence": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/Job_Intelligence_Mcp",
        "run",
        "python",
        "-m",
        "job_intelligence.mcp"
      ],
      "env": {
        "PYTHONUNBUFFERED": "1"
      }
    }
  }
}
```

### 2. Cursor IDE
在项目根目录创建 `.cursor/mcp.json`，或在 Cursor 设置中添加 MCP 服务器：

```json
{
  "mcpServers": {
    "job-intelligence": {
      "command": "uv",
      "args": [
        "--directory",
        "${workspaceFolder}",
        "run",
        "python",
        "-m",
        "job_intelligence.mcp"
      ]
    }
  }
}
```

### 3. Cline / Roo Code (VSCode Extension)
在 VSCode 扩展设置中配置 `cline_mcp_settings.json`：

```json
{
  "mcpServers": {
    "job-intelligence": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/Job_Intelligence_Mcp",
        "run",
        "python",
        "-m",
        "job_intelligence.mcp"
      ],
      "disabled": false,
      "autoApprove": [
        "search_jobs",
        "recommend_jobs",
        "get_recommendation",
        "get_job_explanation",
        "list_registered_boards"
      ]
    }
  }
}
```

---

## 🚀 快速开始 (Quick Start)

### 1. 环境准备
确保本机已安装 Python 3.11+ 以及 [uv](https://github.com/astral-sh/uv) 包管理器。

```bash
# 克隆仓库
git clone https://github.com/jc3212/Job_Intelligence_Mcp.git
cd Job_Intelligence_Mcp

# 极速同步依赖（含开发与测试工具）
uv sync --extra dev
```

### 2. 一键体验真实公开看板同步
项目中内置了真实公开招聘看板端到端同步脚本，无需配置 API Key。演示使用独立临时 SQLite 数据库，结束后删除，不覆盖现有画像或填充正式数据库：

```bash
# 运行演示脚本
uv run python scripts/sync_real_board_demo.py
```

正式使用时，通过已连接的 MCP 客户端调用 `sync_board_jobs(platform="greenhouse", board_token="gitlab", dry_run=False)`，将职位同步到该服务配置的数据库，然后填写自己的画像。

### 3. 本地启动 MCP Server
```bash
# 方式 A：通过 uv 启动模块
uv run python -m job_intelligence.mcp

# 方式 B：通过包命令行直接启动
uv run job-intelligence-mcp
```

### 4. 本地容器化编排 (Docker Compose)
项目内置了本地轻量安全容器定义（基于 `python:3.13-slim`，强制非 root 用户 `UID 10001` 运行）：

```bash
# 先构建，再由 MCP 客户端启动前台 stdio 子进程
docker compose build mcp-server
docker compose run --rm --no-deps -T mcp-server
```

---

## 🛡️ 安全合规与深度防护体系 (Security Safeguards)

| 安全维度 | 防护机制 | 落地效果 |
| :--- | :--- | :--- |
| **出站网络防 SSRF** | `PinnedAsyncHTTPTransport` | 预解析公网 IP 并强绑定底层套接字，封禁回环网段、RFC1918 私网及 169.254.169.254 云元数据，强制禁用隐式重定向 |
| **提示词注入防御** | `PromptInjectionGuard` | 摄入侧与 MCP 调用双重过滤，自动剥离恶意系统指令、零宽不可见字符及虚假 Tool 调用；技术词汇（如 Prompt Engineer）零误杀 |
| **隐私脱敏与 Canary** | `PrivacyGuard` | 自动打码国内 18 位身份证、11 位手机号、SSN、邮箱等敏感隐私；内存探针实时阻断 `sk-...` 密钥流出 |
| **GDPR 级联物理销毁** | `GDPRComplianceService` | 通过服务 API 在同一事务删除画像、申请、申请事件和反馈，再清理进程内缓存并签发 Ed25519 证书；不擦除外部备份或保证存储介质不可恢复 |
| **两阶段原子灾备** | `DisasterRecoveryManager` | 基于 SHA-256 完整性清单验证；备份损坏时两阶段暂存校验立即阻断回滚，生产在用内存 100% 零污染 |
| **Anti-IDOR 隔离** | `SecurityContext` | CLI 将工具身份绑定至工作区默认用户，拒绝其他 candidate_id；不提供远程多租户认证 |

---

## 🧪 研发质量与全量门禁 (Testing & Quality Gates)

我们坚持严苛的质量基线，确保每一行进入主分支的代码均经过层层检验：

```bash
# 1. 离线单元、契约和安全测试
uv run pytest -m "not integration"

# 真实公网测试，需要能解析并访问 Greenhouse
uv run pytest -m integration

# 2. 运行静态代码风格检查（严格遵守 Ruff 规范，单行 <= 100 字符）
uv run ruff check .

# 3. 运行强类型静态分析（110+ 文件 0 类型错误）
uv run mypy src tests evals scripts

# 4. 执行灾备恢复演练验证
uv run python scripts/backup_restore_drill.py --drill
```

---

## 🤝 贡献与社区治理 (Contributing)

我们由衷欢迎社区贡献者的参与！
- 提交代码前，请通读 [CONTRIBUTING.md](CONTRIBUTING.md)。
- 报告安全漏洞，请遵循 [SECURITY.md](SECURITY.md) 的负责任披露流程。
- 参与社区讨论，请遵守 [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md)。

---

## 📄 开源协议 (License)

本项目基于 [MIT License](LICENSE) 开源协议发布。
Copyright (c) 2026 Job Intelligence Team.