Job Search MCP

JobContextMCP

个人 模型上下文协议（MCP） 服务器，为GitHub Copilot、Claude、Cursor、Windsurf、Zed和其他兼容MCP的人工智能助手提供持久、结构化的求职记忆，这样你就不必从头开始重新解释你的简历、管道状态或面试准备。

内置Python使用 FastMCP.

代理是可选的。 MCP服务器是协议驱动的能力层——任何使用该协议的客户端都可以调用它们。jobContextMCP附带了CLI(cli.py)它直接从终端调用所有55个工具，不需要人工智能客户端。自动化脚本、CI管道和计划任务可以使用与Claude或Copilot相同的工具。AI是一种类型的客户端，而不是唯一的一种。

______________________________________________________________________

输出

由平原生成 .txt 文件——没有设计工具，没有Canva，没有InDesign。模板位于 templates/ 并通过WeasyPrint进行渲染。

______________________________________________________________________

它解决的问题

每个新的AI聊天会话都是从零上下文开始的。在求职过程中，你会不断地重新解释：

• 你正在面试哪些公司，你处于哪个阶段
• 你最喜欢的简历项目符号和明星故事是什么
• 你练习过哪些问题，需要复习哪些算法模式
• 你今天的感觉如何（如果你把心理健康和生产力联系起来）

这个MCP服务器解决了这个问题，它为任何AI助手提供了一组工具，可以调用这些工具立即检索所有上下文。

______________________________________________________________________

建筑

graph TB
    AI["GitHub Copilot / Claude / Cursor / Windsurf / Zed"]

    AI -->|MCP protocol| SERVER

    subgraph SERVER["JobContextMCP  —  FastMCP server"]
        direction TB

        subgraph CTX["Context & Identity"]
            T1["get_session_context()"]
            T2["read_master_resume()"]
            T3["get_personal_context()"]
            T4["get_tone_profile() · log_tone_sample()"]
            T5["get_star_story_context()"]
        end

        subgraph PIPELINE["Application Pipeline"]
            T6["get_job_hunt_status() · update_application()"]
            T6b["log_application_event() · log_rejection() · get_rejections()"]
            T6c["update_compensation() · get_compensation_comparison()"]
            T7["assess_job_fitment() · get_customization_strategy()"]
            T8["generate_resume() · generate_cover_letter()"]
            T9["save_resume_txt() · save_cover_letter_txt() · resume_diff()"]
            T10["export_resume_pdf() · export_cover_letter_pdf()"]
        end

        subgraph INTERVIEW["Interview Prep"]
            T11["get_interview_quick_reference()"]
            T12["get_leetcode_cheatsheet()"]
            T13["generate_interview_prep_context()"]
        end

        subgraph NETWORK["Outreach & People"]
            T14["draft_outreach_message() · review_message()"]
            T15["log_person() · get_people()"]
            T19["log_linkedin_post() · update_post_metrics() · get_linkedin_posts()"]
        end

        subgraph UTIL["Utilities"]
            T16["scan_project_for_skills()"]
            T16b["get_daily_digest() · weekly_summary()"]
            T17["search_materials() · reindex_materials()"]
            T18["log_mental_health_checkin() · get_mental_health_log()"]
        end

        subgraph SETUP["Setup & Identity"]
            T20["check_workspace()"]
            T21["setup_workspace(name, email, ...)"]
            T22["run_hbdi_assessment() · get_hbdi_profile()"]
        end
    end

    subgraph FILES["Your Files  —  local, gitignored"]
        F1["Master resume .txt\nSTAR stories · tone samples\npipeline · contacts · health log"]
        F2["Generated resumes + cover letters .txt\nExported PDFs"]
        F3["LeetCode folder\nSide project folder"]
    end

    CTX --> F1
    PIPELINE --> F1
    PIPELINE --> F2
    INTERVIEW --> F3
    UTIL --> F3
    UTIL --> F1

端到端：职位描述→ 已提交申请

sequenceDiagram
    participant You
    participant Copilot
    participant MCP as MCP Server
    participant Files as Your Files

    You->>Copilot: Session opens
    Copilot->>MCP: get_session_context()
    MCP->>Files: master resume + awards + peer feedback
    MCP->>Files: tone samples (voice calibration)
    MCP->>Files: STAR stories + personal context
    MCP->>Files: live pipeline + contacts
    MCP-->>Copilot: Full context bundle (~70KB)
    Note over Copilot: Fully contextualized — no re-explaining

    You->>Copilot: Paste job description
    Copilot->>MCP: assess_job_fitment(company, role, jd)
    MCP-->>Copilot: Fitment score + gaps + emphasis strategy
    Copilot->>MCP: generate_resume(company, role, jd)
    MCP->>Files: Read master resume + customization strategy
    MCP->>Files: Write tailored resume .txt
    MCP->>Files: Parse .txt → render WeasyPrint PDF
    MCP-->>Copilot: resume saved + PDF exported
    Copilot->>MCP: generate_cover_letter(company, role, jd)
    MCP->>Files: Write cover letter .txt (≤400 words enforced)
    MCP->>Files: Parse .txt → render two-column sidebar PDF
    MCP-->>Copilot: cover letter saved + PDF exported
    Copilot->>MCP: update_application(company, role, "applied")
    Note over You,Files: Resume PDF + Cover Letter PDF ready to submit

______________________________________________________________________

工具

______________________________________________________________________

设置

1.克隆并安装

挑选 一 以下两种方法。Docker建议与他人共享或在服务器上运行；本地Python对于单独开发来说更简单。

选项A——本地Python

git clone https://github.com/JustLikeFrank3/jobContextMCP
cd jobContextMCP
python3 -m venv .venv
.venv/bin/pip install -r requirements.txt

选项B——Docker

需要 （或Docker引擎+作曲v2）。

git clone https://github.com/JustLikeFrank3/jobContextMCP
cd jobContextMCP

# 1. Create your config (edit paths + API key)
cp docker.config.example.json config.json

# 2. Set your local resume folder path
cp .env.example .env
# Edit .env → set RESUME_PATH=/absolute/path/to/your/resumes

# 3. Build the image
docker compose build

镜像大小约为600 MB（Debian slim+WeasyPrint运行时）。只有在以下情况下才需要重建 requirements.txt 变化。

体积映射

config.json, .env，以及下的所有文件 data/ 是gitignored-您的API密钥和个人数据永远不会离开您的机器。

隔离测试Docker构建

要在将映像连接到客户端之前对其进行验证，请克隆到一个新目录中并运行快速冒烟测试：

# Clone into a clean test directory
git clone https://github.com/JustLikeFrank3/jobContextMCP jobContextMCP-docker-test
cd jobContextMCP-docker-test

# Config and env
cp docker.config.example.json config.json
# Edit config.json:
#   "resume_folder"  → absolute path to your resumes (will mount as /workspace)
#   "data_folder"    → leave as "/app/data" (data/ is bind-mounted inside the container)
#   "openai_api_key" → your key
cp .env.example .env
# Edit .env → set RESUME_PATH to the same resume folder path

# Build
docker compose build

# Smoke test — send an initialize request over stdio and confirm the server responds
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"0"}}}' \
  | docker compose run --rm -T jobcontextmcp
# Expected: a JSON response with "result" → {"protocolVersion":...,"capabilities":...}

# Optional: test SSE mode
MCP_TRANSPORT=sse docker compose up -d
curl -s --no-buffer http://localhost:8000/sse   # should stream event: endpoint
docker compose down

常见的构建失败原因：

• config.json 缺少或具有占位符路径→ 构建前编辑
• RESUME_PATH 在 .env 指向一个不存在的目录→ 创建它或指向现有文件夹
• WeasyPrint系统deps——在图像内部处理；无需本地安装

______________________________________________________________________

2.选择你的客户

服务器使用MCP——它可以与任何兼容的客户端一起工作。你不需要人工智能客户端来使用它。选择你的：

终端（不需要AI客户端）

cli.py 是一流的客户。直接调用55个工具中的任何一个：

# List all tools
.venv/bin/python3 cli.py --list

# Call a tool
.venv/bin/python3 cli.py get_job_hunt_status
.venv/bin/python3 cli.py log_application_event '{"company": "Acme", "role": "SWE", "event_type": "phone_screen"}'

# Read args from a file (v0.6+)
.venv/bin/python3 cli.py add_person @/path/to/args.json

这意味着自动化脚本、cron作业和CI管道可以使用与任何AI客户端相同的工具——确定性、可观察性、不需要代理。

AI客户端

VS代码+GitHub副本 *（推荐--无额外配置）*

.vscode/mcp.json 已提交并使用 ${workspaceFolder} 相对路径。一旦 .venv 当您在VS Code中打开此文件夹时，服务器会自动启动，无需额外配置。

⚠️ 不要通过VS Code UI添加服务器 （插头图标→ “添加MCP服务器”流程）。这会在您的全局中写入一个损坏的条目 ~/Library/Application Support/Code/User/mcp.json 使用 python 而不是 python3 没有 cwd --它默默地与工作区配置冲突，并导致间歇性工具故障。如果工具表现不稳定，请打开该全局文件并删除任何重复项 jobContextMCP 进入。

多根工作区： 删除以下内容的副本 .vscode/mcp.json 进入任何其他工作区根目录（例如您的简历文件夹），VS Code会自动从任一窗口启动。

克劳德桌面版

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json （macOS）或 %APPDATA%\Claude\claude_desktop_config.json （Windows）：

{
  "mcpServers": {
    "jobContextMCP": {
      "command": "/absolute/path/to/jobContextMCP/.venv/bin/python3",
      "args": ["/absolute/path/to/jobContextMCP/server.py"],
      "cwd": "/absolute/path/to/jobContextMCP"
    }
  }
}

保存后重新启动Claude Desktop。

光标

添加 .cursor/mcp.json 在此文件夹中（项目范围内）或通过 设置→ MCP （全球）：

{
  "mcpServers": {
    "jobContextMCP": {
      "command": "/absolute/path/to/.venv/bin/python3",
      "args": ["server.py"],
      "cwd": "/absolute/path/to/jobContextMCP"
    }
  }
}

光标还读取 .cursorrules --使用 copilot-instructions.example.md 作为起始模板。

帆板运动

编辑 ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "jobContextMCP": {
      "command": "/absolute/path/to/.venv/bin/python3",
      "args": ["server.py"],
      "cwd": "/absolute/path/to/jobContextMCP"
    }
  }
}

Windsurf也读到 .windsurfrules --同样的 copilot-instructions.example.md 模板适用。

泽德

添加 ~/.config/zed/settings.json 在...之下 "context_servers":

{
  "context_servers": {
    "jobContextMCP": {
      "command": {
        "path": "/absolute/path/to/.venv/bin/python3",
        "args": ["server.py"],
        "env": {}
      },
      "settings": {}
    }
  }
}

Docker--stdio（克劳德桌面）

如果您使用Docker构建，请将Claude Desktop指向容器，而不是本地Python进程。 编辑 ~/Library/Application Support/Claude/claude_desktop_config.json （macOS）或 %APPDATA%\Claude\claude_desktop_config.json （Windows）：

{
  "mcpServers": {
    "jobContextMCP": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-v", "/absolute/path/to/jobContextMCP/config.json:/app/config.json:ro",
        "-v", "/absolute/path/to/jobContextMCP/data:/app/data:rw",
        "-v", "/absolute/path/to/your/resumes:/workspace:rw",
        "-e", "MCP_TRANSPORT=stdio",
        "jobcontextmcp:latest"
      ]
    }
  }
}

替换三个 /absolute/path/to/... 用你的真实路径进入。保存后重新启动Claude Desktop。

Docker——SSE/流式http（网络客户端）

对于基于浏览器或远程客户端，请在服务器模式下运行容器：

# SSE
MCP_TRANSPORT=sse docker compose up

# or streamable-http
MCP_TRANSPORT=streamable-http docker compose up

然后连接到 http://localhost:8000/sse （苏格兰和南方交易所）或 http://localhost:8000/mcp （可流式传输的http）。 通过以下方式控制端口 MCP_PORT 在 .env.

______________________________________________________________________

3.通过聊天设置首次会话

服务器运行后，与您的AI助手打开聊天，然后拨打：

check_workspace()

此扫描用于 config.json，所有数据文件、工作区目录和报告都需要创建。在一个新的克隆上，你会看到所有东西都列为缺失。

然后运行 setup_workspace() 您的详细信息：

setup_workspace(
  name="Your Name",
  email="you@example.com",
  phone="555-867-5309",
  linkedin="www.linkedin.com/in/yourhandle",
  city_state="Your City, ST 00000",
  location="Your Metro Area, ST",
  master_resume_content="
",
  leet_language="Python"
)

这一通电话：

• 创造 config.json 包含您的联系信息和OpenAI密钥槽
• 初始化所有7个数据文件(status.json, personal_context.json, tone_samples.json, rejections.json, mental_health_log.json, linkedin_posts.json, people.json)
• 创建所有8个简历子目录(01-Current-Optimized 通过 08-Interview-Prep-Docs)里面 workspace/resumes/
• 保存您的主简历 .txt 并在中创建了一个LeetCode实践脚手架 workspace/leetcode/

setup_workspace() 是幂等的——如果添加新字段或需要重新创建已删除的文件，可以安全地重新运行。

config.json 以及下的所有文件 data/ 是gitignored-您的联系信息、API密钥、管道数据和个人故事永远不会离开您的机器。

______________________________________________________________________

4.（可选）运行HBDI认知风格评估

HBDI（Herrmann Brain Dominance Instrument）是内置于服务器中的认知风格分析器。它将您的主象限配置文件保存到 personal_context.json 并根据你的自然思维和沟通方式生成面试框架建议。

run_hbdi_assessment(
  q1_no_spec_project="",
  q2_critical_feedback="",
  q3_tedious_finish="",
  q4_senior_disagreement="",
  score_a=3,   # Analytical / logical  (1–4)
  score_b=2,   # Sequential / detail   (1–4)
  score_c=3,   # Interpersonal         (1–4)
  score_d=4    # Creative / big-picture (1–4)
)

跑 get_hbdi_profile() 随时检索合成报告和框架建议。

______________________________________________________________________

5.（可选）启用AI生成和RAG搜索

将您的OpenAI API密钥添加到 config.json （由创建 setup_workspace()):

"openai_api_key": "sk-...",
"openai_model": "gpt-4o-mini"

然后构建RAG指数：

.venv/bin/python rag.py

这将使用以下方式嵌入您的所有材料 text-embedding-3-small完整指数的成本通常低于0.10美元。一旦建成， search_materials() 本地运行，无需进一步调用API。

______________________________________________________________________

工作区结构

此服务器设计为在多根VS Code工作区内运行，该工作区包括您的简历文件夹、副项目和面试准备，以及服务器本身。Copilot需要直接访问所有内容才能使用。

为什么副项目在工作区中

服务器可以扫描你正在积极构建的任何项目，并显示你可能还没有想过要写的简历项目符号。

scan_project_for_skills() *（v4）* --迭代中列出的所有文件夹 side_project_folders 在你的 config.json，读取每个代码库，并返回每个项目所使用的技术、应用的模式和值得在简历上提及的指标的细分。循环会自动结束：你构建了一些东西，服务器会注意到你使用了什么，并在面试前向你展示要添加到主简历中的内容。

示例：构建了一个具有伺服HAT控制、Azure Blob存储和systemd服务管理的物联网摄像头。扫描仪捕捉到了这三份简历中值得补充的内容，但都没有被纳入原始简历草稿。

要添加新项目，请执行以下操作：

"side_project_folders": [
  "/path/to/your/primary-project",
  "/path/to/another-project"
]

这 .github/copilot-instructions.md 在每个文件夹中，告诉Copilot呼叫 get_session_context() 第一。随着 mcp.json 自动启动服务器，该指令立即可操作——工具在第一条消息之前就已启动。

服务器在运行时读取的数据文件（均相对于 resume_folder 在 config.json):

• 01-Current-Optimized/ --主源简历+所有定制版本
• 02-Cover-Letters/ --求职信 .txt 文件
• 03-Resume-PDFs/ --导出的PDF文件在此处
• 06-Reference-Materials/ --简历模板、奖项引用、同行反馈、技能变体

______________________________________________________________________

系统的好坏取决于你给它喂食的东西

get_session_context() 每次会话加载四件事：你的主简历、你的语气配置文件、你的个人背景库和你的直播管道。就是这样 不 阅读个人简历或求职信——所以只有在你明确提取并记录下来之前，人工智能才能看到那些只存在于这些文件中的有意义的东西。

这是人工智能产生通用输出的最常见原因。 RAG索引可以通过以下方式访问您的求职信和简历 search_materials()，但这是被动的——只有当人工智能知道要请求时，它才会显示内容。个人上下文库和音调配置文件是活动的——它们会自动加载并通知每个草稿、每个装修、每个外展信息。

在依赖该系统之前要摄入什么

1.扫描你现有的求职信和简历，寻找语气样本

如果你以前写过求职信，运行：

scan_materials_for_tone(category="cover_letters", limit=100)
scan_materials_for_tone(category="resumes", limit=100)

这会对你现有的写作进行索引，这样人工智能就可以镜像你的声音。设置后执行一次，然后在添加一批新材料时再次执行。

2.明确记录个人故事

求职信积累了在背景下写的故事，然后被遗忘了——家族史、非线性职业道路、激励经历、你关心一家特定公司的原因。这些不会将自己索引到个人上下文库中。通读你最好的求职信并致电 log_personal_story() 为了任何值得保留的东西。非数字来源也是如此：告别卡、奖项引用、绩效评估、同行反馈表。

log_personal_story(
    story="Full narrative in your own words...",
    tags=["family", "engineering_philosophy", "ford"],
    title="Short memorable title"
)

3.吸收同行反馈和认可奖励

正式的反馈周期和表彰奖项包含来自同行、经理归因的语言，这些语言在面试中比你写的任何关于自己的东西都更可信。逐字记录引文及其来源和日期。有用标签： peer_feedback, manager_recognition, attribution.

4.添加新文件后重建RAG索引

每当您在简历文件夹中添加新简历、求职信或参考资料时，请运行：

reindex_materials()

RAG索引不会自动更新。如果你跳过这个， search_materials() 不会知道自上次索引构建以来添加的任何内容。

5.在任何冲刺后扫描你的副项目

scan_project_for_skills()

在求职过程中获得的技能（新框架、云服务、语言）不会出现在你的简历上，直到你运行此程序并手动将建议的项目符号添加到你的主简历中。

摄入回路

我们的目标是建立一个库，人工智能可以在其中回答“弗兰克对X能说的最诚实、最具体、最人性化的话是什么？”而无需重新解释。故事、引语、语气示例和同行反馈都是原始材料。你输入的越多，输出就越不通用。

有疑问时：如果某件事让你感到骄傲，让同事感到惊讶，出现在一张卡片上，或者获得了认可——记录下来。

______________________________________________________________________

人工智能简历和求职信生成

generate_resume() 和 generate_cover_letter() 是端到端的工具：一个调用产生一个 已保存 .txt +导出PDF。他们加载主简历、语气简介和工作适应 策略自动执行——无需手动进行上下文组装。

使用OpenAI密钥（全自动）

添加 openai_api_key （以及可选 openai_model)to config.json:

"openai_api_key": "sk-...",
"openai_model": "gpt-4o-mini"

然后从Copilot内部拨打电话：

generate_resume("Stripe", "Senior Software Engineer", "
")
generate_cover_letter("Stripe", "Senior Software Engineer", "
")

生成内容，保存 .txt，并一次性导出PDF。 成本：每份文件约0.002美元 gpt-4o-mini 定价。

没有OpenAI密钥（Copilot辅助）

如果没有配置密钥，每个工具都会返回一个完整的上下文包——主简历、音调 配置文件、定制策略和格式说明——由Copilot编写内容 然后呼叫 save_resume_txt / export_resume_pdf.

系统约束（在提示中强制执行）

简历

• 所有的指标和成就都必须原封不动地来自你的主简历，而不是发明。
• 节标题必须全部大写： PROFESSIONAL EXPERIENCE, CORE TECHNICAL SKILLS, EDUCATION, LEADERSHIP & COMMUNITY.
• 作业标题格式： Title | Company, Location | Month YYYY - Month YYYY （三个管道分隔部分）。
• 子弹必须使用 • （Unicode U+2022）--不是 - 或 *.
• 联系人栏使用标记字段： phone:, email:, linkedin: （小写，冒号后缀）。
• 目标长度：650-800字（Courier New 9.2pt中的一页）。

求职信

• 硬最大值： 325字 在信的正文中。
• 确实 4段 --第1段：挂钩+角色+公司；第2段：技术成果+指标；第3段：第二个区别因素；第4段：简短的近距（1-2句）。
• 正文中没有日期，没有地址块，没有回复行，没有公司名称。
• 问候语： Dear Hiring Manager, --没有变化。
• 没有子弹，没有粗体，正文中没有标题——只有散文。

这些约束被烘焙到提示中。偏差会导致PDF呈现错误，因为 模板具有固定的尺寸。如果添加自己的生成逻辑，请复制格式规范 从 tools/generate.py (_RESUME_FORMAT_SPEC, _COVER_LETTER_FORMAT_SPEC).

______________________________________________________________________

PDF模板演示

该仓库包含两个假身份演示文件，因此您可以在不使用真实数据的情况下预览PDF输出：

# Generate the demo PDFs after setup:
python -c "
from tools.export import export_resume_pdf, export_cover_letter_pdf
export_resume_pdf('Nobody MacFakename Resume - Demo Software Engineer.txt')
export_cover_letter_pdf('Nobody MacFakename Cover Letter - Demo Software Engineer.txt')
"

PDF登陆 03-Resume-PDFs/ 在你的 resume_folder.来源 .txt 文件在 01-Current-Optimized/ 和 02-Cover-Letters/ 分别。

______________________________________________________________________

数据隐私

config.json 以及下的所有文件 data/ --包括 status.json, mental_health_log.json, personal_context.json, tone_samples.json, rejections.json, people.json，以及 linkedin_posts.json --被忽视了。您的真实应用程序数据、个人故事、联系人姓名、拒绝历史和健康条目永远不会离开您的机器。

______________________________________________________________________

路线图

v0.6 *（已发货）*

• setup_workspace() --会话引导程序：创建 config.json，全部7个数据文件， workspace/resumes/ 子目录 01–08，以及来自单个聊天的LeetCode脚手架；零手动JSON编辑
• check_workspace() --诊断扫描：报告存在、缺失或配置错误的内容；在文件丢失时运行
• run_hbdi_assessment() --HBDI认知风格分析器：根据个人背景保存主要/次要象限档案+面试框架建议
• get_hbdi_profile() --使用象限综合检索存储的HBDI配置文件

计划--v0.7

• get_github_stats(username) --将公开提交/回购活动拉到简历项目符号和求职信谈话要点中
• get_upcoming_interviews(days?) --筛选未来N天内安排面试的申请
• get_referral_chains(company) --可以向你推荐目标公司的表面联系人
• draft_reply(company, role, message_type) --使用存储的应用程序上下文和音调配置文件起草后续、感谢或还价回复

______________________________________________________________________

调整侧投影扫描仪

scan_project_for_skills() 扫描项目文件夹中使用的技术，并建议新的简历项目符号。点 side_project_folder 在 config.json 无论你目前正在建造什么。

______________________________________________________________________

副驾驶说明模板

包括a .github/copilot-instructions.md 在您的工作区中指向此MCP服务器，以便Copilot知道调用其工具。看 copilot-instructions.example.md 作为起始模板。

______________________________________________________________________

更新依赖关系

.venv/bin/pip install -U "mcp[cli]" "openai" "numpy"

数据文件和设置

所有运行时数据文件都存储在 data/ 目录。您的真实数据文件（例如。， status.json, people.json等）被视为隐私。为每种数据类型提供了示例文件：

• status.example.json
• tone_samples.example.json
• personal_context.example.json
• rejections.example.json
• mental_health_log.example.json
• linkedin_posts.example.json
• people.example.json
• rag_index.example.json
• scan_index.example.json

设置：

1. 复制每个 *.example.json 文件到其相应的真实数据文件（例如。， cp data/people.example.json data/people.json).
2. 使用您自己的信息编辑真实的数据文件。
3. 所有真实的数据文件都是gitignored的，不会被提交。

注：

• 如果没有这些数据文件，服务器和工具将无法正常运行。
• 示例文件为每种数据类型提供了所需的结构和示例条目。