AI Job Intelligence MCP

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

中文文档 | English Documentation

当前支持范围

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

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

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

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

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

Related MCP server: job-search-mcp

📖 项目简介 (Introduction)

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

它旨在让 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)

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 个)

2. 状态机与反馈追踪工具 (State Machine & Feedback - 6 个)

3. 可观测与取消诊断工具 (Observability & Diagnostics - 3 个)

4. 动态公开看板管理工具 (Public Board Management - 3 个)

💻 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

{
  "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 服务器：

{
  "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：

{
  "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 包管理器。

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

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

2. 一键体验真实公开看板同步

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

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

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

3. 本地启动 MCP Server

# 方式 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 运行）：

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

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

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

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

# 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。

• 报告安全漏洞，请遵循 SECURITY.md 的负责任披露流程。

• 参与社区讨论，请遵守 CODE_OF_CONDUCT.md。

📄 开源协议 (License)

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