job-hunter

name job-hunter description This skill should be used when the user asks to "find jobs", "search for jobs matching my expectations", "find the best job matching my expectation", "job hunt", "search job platforms", "match jobs to my profile", "find AI engineer jobs", "find ML engineer jobs", "search for senior software engineer roles", "find jobs with visa sponsorship", or mentions job hunting, job matching, career search, or job platform scraping. version 1.2.0 Job Hunter Search job platforms (UK and France), match listings to the candidate's profile, check visa sponsorship (UKVI for UK, Talent Passport for France), calculate financial viability including commute costs, and export ranked results to an Excel workbook (.xlsx). Powered by DEB Cloud — scraping, reference data, and job caching are provided by the DEB Cloud MCP server ( mcp__deb-jobhunter__* tools). The country field in the expectations JSON drives platform selection, tax/social calculation, visa checking, and currency formatting. Supported countries: gb (default), fr . Output language : All user-facing output (progress messages, reports, summaries, Excel headers) MUST be in the language of the country field. For fr : write in French. For gb : write in English. If the user writes in a specific language, respond in that language regardless of country. CRITICAL — Follow ALL steps in order. DO NOT skip steps or improvise. The pipeline has 7 mandatory steps: Step 0 → 1 → 2 → 3 → 3.5 → 4 → 5 → 5.5 → 6. Each step depends on the previous step's output. Skipping enrichment (Step 4) degrades scoring. Skipping company checks (Step 5.5) loses ratings and visa data. Skipping commute (Step 6) loses financial viability. Do NOT write custom Python to replace process_jobs.py stages — always use the script as documented. Do NOT use scrape_jobs (legacy) — always use launch_scrape_jobs (async pipeline). Context Management — Save Tool Responses to File CRITICAL : MCP tool responses (especially scrape_jobs and scrape_url ) return large payloads that saturate the context window. You MUST save them to disk immediately and reference the file path instead of keeping the content in context. Temp directory : Create a mcp_jobhunter subdirectory under the system temp folder. Detect the OS temp path at runtime: Linux/macOS: /tmp/mcp_jobhunter/ Windows: %TEMP%\mcp_jobhunter\ (e.g., C:\Users\{user}\AppData\Local\Temp\mcp_jobhunter\ ) Use Bash to create the directory if it doesn't exist: mkdir -p /tmp/mcp_jobhunter (Unix) or equivalent. Pattern for every MCP tool call that returns content: Call the MCP tool (e.g., scrape_jobs , scrape_url , get_reputation , get_commute_results ) Immediately use the Write tool to save the full response to a JSON file in the temp directory Only retain a brief summary in your working memory: status, count, file path When you need the data later, use the Read tool to load it from the file File naming convention (inside mcp_jobhunter/ ): scrape_{platform}_{city}_{role_slug}_{YYYYMMDD_HHMMSS}.json detail_batch{N}_{YYYYMMDD_HHMMSS}.json reputation_batch{N}_{YYYYMMDD_HHMMSS}.json Example flow: # 1. Call tool result = scrape_jobs(query="AI Engineer", platforms=["reed"], location="London") # 2. Save full response to temp file immediately Write("<temp_dir>/mcp_jobhunter/scrape_reed_london_ai_engineer_20260305_143022.json", json(result)) # 3. Only keep summary in context: # "reed-london: 12 jobs scraped, saved to <temp_dir>/mcp_jobhunter/scrape_reed_london_ai_engineer_20260305_143022.json" # 4. Later, when parsing: # Read("<temp_dir>/mcp_jobhunter/scrape_reed_london_ai_engineer_20260305_143022.json") This saves large payloads to disk immediately to avoid saturating the context window. Data Persistence CRITICAL : All intermediate data MUST be saved to disk at each step. This ensures that if the conversation runs out of context, the next invocation can resume from the last checkpoint without re-scraping. Working Directory Create a session working directory in the same folder as the expectations JSON: {expectations_dir}/job-search-{YYYYMMDD_HHMMSS}/ ├── state.json # Current progress tracker ├── checkpoint-raw-combined.json # All raw results from pipeline (after Step 3) ├── checkpoint-dedup.json # After deduplication (after Step 3.5) ├── checkpoint-filtered.json # After first-layer filter (after Step 3.5) ├── checkpoint-enriched.json # After JD enrichment (after Step 4) ├── checkpoint-scored.json # After LLM agent scoring (after Step 5) ├── company-checks.json # Company reputation + UKVI + agency (Step 5.5) ├── commute-data.json # Commute costs from DEB Cloud (Step 6) ├── checkpoint-final.json # After financial calc + visa check (after Step 6) └── jobs-{YYYYMMDD_HHMMSS}.xlsx # Final Excel output (after Step 6) State File ( state.json ) Track progress so interrupted sessions can resume: { "session_id" : "20260211_143022" , "expectations_path" : "path/to/expectations.json" , "working_dir" : "path/to/job-search-20260211_143022/" , "deb_cloud_key_valid" : true , "current_step" : 3 , "step_3_batch_id" : null , "step_3_complete" : false , "step_3_5_complete" : false , "step_4_batch_id" : null , "step_4_complete" : false , "step_5_complete" : false , "step_5_5_complete" : false , "step_6_complete" : false , "started_at" : "2026-02-11T14:30:22" , "updated_at" : "2026-02-11T14:45:12" } Resume Logic At the start of the workflow, check if a working directory exists with matching expectations file: Look for job-search-* directories in the expectations folder If found with a state.json , read it to determine where to resume If Step 3 has a batch_id : poll for results, then continue from Step 3.5 If Step 3 was complete: load checkpoint-raw-combined.json , continue to Step 3.5 If Step 3.5+ complete: load the latest checkpoint, skip ahead If no working directory found: start fresh from Step 1 Execution Mode Proceed through all steps without asking for user confirmation between steps. Only pause to ask the user if: (1) DEB Cloud key is missing, (2) an error requires a decision, or (3) the search matrix exceeds 100 queries. All file writes, script executions, and MCP calls should proceed automatically. Workflow Execute these steps in order. Save intermediate data at each step. Log progress to the user after each major step. After completing each step, update state.json with the step's completion flag and updated_at timestamp. Step 0: Validate DEB Cloud API Key Read the DEB_CLOUD_API_KEY environment variable. If set, call mcp__deb-jobhunter__ping to validate: On success: store deb_cloud_key_valid: true in state. Note the plan and available platforms. On failure: warn user, store deb_cloud_key_valid: false . If not set: warn the user: "DEB Cloud API key not configured. Register at debytes.io/products/cloud to get a key. Running in degraded mode — scraping and data lookups are unavailable." In degraded mode: the user can provide their own raw job data files. Dedup, scoring, financial calc, and Excel export still work locally. Step 1: Load and Validate Inputs Read the expectations JSON file from the path provided by the user. Validate required fields: candidate , target_roles , locations , current_situation . Determine country: read country from expectations JSON (default: "gb" if absent). Determine sector: read sector from expectations JSON (default: "industry" if absent). Valid values: "industry" , "academia" . Read the shared INI config from ${PLUGIN_ROOT}/config/job-hunter.ini . Read the country-specific INI from ${PLUGIN_ROOT}/config/country-{country}.ini (overlays shared config). If sector=academia : load [platforms_academia] and [platform_urls_academia] sections instead of [platforms] . Also load [academic_salary_grades] for salary parsing. Resolve candidate document for scoring context: a. If candidate.resume_path is provided: Detect format from extension: .tex , .pdf , .md , .txt , .docx , .doc For .tex , .pdf , .md , .txt : read directly with the Read tool (plain text or native PDF support). For .docx or .doc : run the extraction utility first: python " ${PLUGIN_ROOT} /scripts/process_jobs.py" \ --stage extract-resume \ --resume "{resume_path}" \ --output-dir "{working_dir}" Then read the resulting -extracted.txt file with the Read tool. b. If candidate.profile_path is also provided AND the file exists: read it as supplementary context (backward compatible). c. If neither path is provided or files don't exist: WARN the user and proceed with skills-only matching (from candidate.skills or INI [candidate_skills] ). d. Store the resolved readable path in state.json as "candidate_document_path" . Load candidate skills from candidate.skills in the expectations JSON (fallback to INI [candidate_skills] for backward compat). Create the working directory and initialize state.json . Report to user: "Country: {country}. Sector: {sector}. Found N target roles, M locations. DEB Cloud: {connected/degraded}. Working directory: {path}. Proceeding." Step 2: Build Search Matrix and Estimate Credits For each target role, get the search_keywords array (use first keyword as primary). Translate keywords if needed — search keywords MUST be in the language of the target country. If the user provided English keywords for a non-English country (e.g. "Data Engineer" for FR), translate them (e.g. "Ingénieur Data"). Include both the translated and original as separate keywords for broader coverage. Common FR translations: internship=Stage, engineer=Ingénieur, developer=Développeur, senior=Senior (same), manager=Responsable. Combine all roles with all cities from both P1 and P2 groups. Select platforms — read [platforms] from the country INI first, then fall back to shared INI: default : priority-ordered platform list (used for paid plans). free : reduced platform list (used for free plan). If plan=free (from ping response): use the free list and only the first keyword per role ( free_max_keywords=1 ). The user can request more platforms, but warn them about credit impact and show the estimate before proceeding. All other plans: use the default list. The user can request additional platforms; show the estimate so they can decide. GB (academia) : use [platforms_academia] from country INI instead. Only include platforms that are also enabled ( =1 ) in the country INI [platforms] section. Build the search matrix as a list of {query, platforms, location, country, min_salary} entries. Read max_pages_per_platform from [general] in the shared INI (default 2). This value is passed as max_pages to both estimate_credits and launch_scrape_jobs . Users can increase this for broader results, but warn about the credit impact. Credit estimation (Gate 1): Call mcp__deb-jobhunter__estimate_credits with the search matrix and max_pages (from INI). This returns a breakdown of estimated credits (scraping, enrichment, scoring, reputation, total). Show the user the estimate and confirm before proceeding. Step 3: Scrape Job Listings (Pipeline) Requires DEB Cloud key. If degraded mode, skip this step and instruct the user to provide raw job data. Platform codes (match INI platform names — server auto-selects country-specific URLs): GB industry : linkedin , indeed , reed , totaljobs , cwjobs , cvlibrary , adzuna GB academia : use mcp__deb-jobhunter__scrape_url for jobs.ac.uk and EURAXESS with specific URLs from [platform_urls_academia] INI section FR : linkedin , indeed , apec , hellowork Launch scrape workers: IMPORTANT : Use launch_scrape_jobs (async batch tool), NOT scrape_jobs (legacy single-call tool). The scrape_jobs tool is for ad-hoc single queries only — it blocks, saturates context, and doesn't track progress. The pipeline MUST use the async launch/poll/get pattern. Call mcp__deb-jobhunter__launch_scrape_jobs with the search matrix, target_roles list, and max_pages (from INI). Returns {batch_id, worker_count, estimated_credits} . Workers run in parallel on the server — scraping, parsing, deduplication, and caching happen automatically. Wait for completion: Call mcp__deb-jobhunter__poll_jobs(batch_id=...) once. The server polls internally and streams progress via MCP progress notifications. Returns when status is COMPLETE , PARTIAL , FAILED , or after timeout. Response: {status, progress: {total, done, failed}, credits_consumed, tasks: [...]} . If timed_out=true in response, call poll_jobs again to continue waiting. Get results: Call mcp__deb-jobhunter__get_scrape_results(batch_id=...) . If response contains jobs key : use the Write tool to save the jobs array as JSON to {working_dir}/checkpoint-raw-combined.json . If response contains download_url key : download to disk via curl: curl -s --ssl-no-revoke -o "{working_dir}/checkpoint-raw-combined.json" "{download_url}" Each job includes listing_score (0-100) from the parser, used for filtering. IMPORTANT : Never try to pipe MCP tool responses through Python stdin. Use Write for inline results or curl for downloads. Report progress: "Scraping complete. {N} total listings from {platforms}. Credits used: {credits}." Step 3.5: Deduplicate and Filter Deduplicate via process_jobs.py: python " ${PLUGIN_ROOT} /scripts/process_jobs.py" \ --stage dedup \ --raw "{working_dir}/checkpoint-raw-combined.json" \ --output-dir "{working_dir}" Saves checkpoint-dedup.json . First-layer filter — drop low-relevance jobs before enrichment: python " ${PLUGIN_ROOT} /scripts/process_jobs.py" \ --stage filter \ --dedup "{working_dir}/checkpoint-dedup.json" \ --expectations "{expectations_path}" \ --filter-threshold 40 \ --output-dir "{working_dir}" Uses listing_score from the parser + salary floor heuristic. Free — no API calls. Saves checkpoint-filtered.json . Report: "After dedup: {N} unique. After filter: {M} jobs (dropped {K} low-relevance)." Step 4: JD Enrichment (Gate 2) Requires DEB Cloud key. Read [enrichment] from INI config. If enabled=0 , skip to Step 5. Prepare UUIDs for enrichment via process_jobs.py: If plan=free : use free_max_enrich from INI [enrichment] section (default 250).