Israeli Multi-Source Tech Job FastMCP Server (TechJobMCP)

An enterprise-grade, privacy-first FastMCP server providing intelligent, multi-source tech job aggregation, smart deduplication, dynamic CV skill & target role extraction, requirement coverage scoring, zero-guesswork Universal DOM form automation, and autonomous job scouting workflows across HireMeTech, Comeet ATS, Workday Enterprise, Eightfold.ai, DirectTech (Google, Apple, Amazon, IBM), and LinkedIn.

📖 Documentation Guides

• 🚀 Setup & Candidate Profile Configuration Guide — Dynamic CV extraction, target roles, environment config, Docker & Python local run.

• 🌐 Cloudflare Tunnel & Port Export Guide — Exposing port 8000 via cloudflared for remote AI clients.

• 🤖 AI Client Integrations Guide — Complete setup for Gemini Spark (autonomous scheduled scout), Claude Desktop / CoWork, ChatGPT / Codex, and Cursor / Antigravity.

• 🛠️ Spark Prompts & Skills — System prompt and skill instructions for autonomous scouting agents.

Related MCP server: JobHound

🏛️ Architecture Overview

graph TD
    Client([MCP Client: Gemini Spark / Claude / Cursor / ChatGPT]) --> Tools[FastMCP Server Layer]
    Tools --> Aggregator[JobAggregator]
    Aggregator --> Registry[SourceRegistry]

    subgraph Parallel Pluggable Sources Layer
        Registry --> S1[HireMeTechSource<br/>Direct REST API + DOM Fallback]
        Registry --> S2[ComeetSource<br/>Direct ATS API + Concurrency Semaphore]
        Registry --> S3[WorkdaySource<br/>Enterprise Workday CXS Direct API]
        Registry --> S4[EightfoldSource<br/>PCSX Search API]
        Registry --> S5[DirectTechSource<br/>Google, Apple, Amazon, IBM Feeds]
        Registry --> S6[LinkedInSource<br/>Job Guest Search API]
    end

    subgraph Processing & Normalization Engine
        S1 --> Dedup[Deduplication & Entity Merger]
        S2 --> Dedup
        S3 --> Dedup
        S4 --> Dedup
        S5 --> Dedup
        S6 --> Dedup
        
        Dedup --> NormKey["Key = slug(title) + '@' + slug(company)"]
        NormKey --> Merge[Metadata & Links Merger]
        Merge --> Scorer[Unified CV / Skill Matcher]
    end

    subgraph Dynamic Candidate Engine
        CV["Candidate CV (.pdf / .docx / .txt)"] --> Extractor[Dynamic CV & Profile Extractor]
        Extractor --> Skills["Extracted Skills (40+ tokens)"]
        Extractor --> Stack["Primary Tech Stack (Top Skills)"]
        Extractor --> Seniority["Inferred Seniority & Exclusions"]
        Extractor --> Roles["Dynamic Target Roles"]
        Skills --> Scorer
        Stack --> Scorer
        Seniority --> Scorer
        Roles --> Scorer
    end

    subgraph Autonomous Application Engine
        Tools --> Dispatcher["HybridApplicationDispatcher"]
        Dispatcher --> Guardrails{"Safety Guardrails<br/>Cap / Dups / Score / IL"}
        Guardrails --> StrategyRouter["Strategy Selector"]
        StrategyRouter --> BrowserStrategy["BrowserPlaywrightStrategy"]
        StrategyRouter --> ApiStrategy["ApiPostStrategy"]
        StrategyRouter --> EasyApply["EasyApplyStrategy"]
        
        BrowserStrategy --> DOMInspector["Universal DOMInspector<br/>Recursive Frames & Zero-Guesswork"]
        BrowserStrategy --> FormMapper["SemanticFormMapper<br/>Regex + Free-Tier LLM Gateway"]
        Dispatcher --> Ledger[("ApplicationLedger (SQLite)")]
    end

    Scorer --> Cache[Unified JobCache - 2h TTL]
    Cache --> Tools

🌟 Key Features

1. Dynamic Candidate Extraction:

   • Ingests .pdf, .docx, and .txt resumes for any engineering specialty (Java, Python, Frontend, DevOps, AI, Web3).

   • Automatically derives candidate primary_stack and target_roles without hardcoded assumptions.

   • Detects seniority level (Student, Junior, Mid, Senior, Lead) and generates tailored negative keywords.

2. Calibrated Match Scoring (0–100):

   • Primary Stack Affinity: Heavily weights candidate's core technologies (+35 pts).

   • Skill Volume Scaling: Scales with absolute count of matched core competencies (4+ skills = 30 pts; 1 generic skill = 8 pts max).

   • Target Role Semantic Fit: Awards +15 pts for developer titles matching target roles; caps non-engineering/administrative positions at 65 pts.

   • Commute & Location Normalization: Normalizes country codes (", IL", Israel, ישראל) and handles peripheral on-site roles.

3. Universal Dynamic DOM Form Solver:

   • Zero-Guesswork DOM Inspection: In-browser JS evaluation traverses main documents and recursive iframes (e.g., Comeet embedded forms, Workday modal overlays).

   • 11-Tier Contextual Label Resolution: Matches labels using aria-label, <label for>, preceding text, fieldsets, and placeholders.

   • Deterministic & AI-Assisted Submission: Deterministic keyword scoring (+65 to +100 for submit buttons, -100 for negative/cancel actions) with LLM disambiguation fallback.

4. Resilient Free-Tier LLM Gateway & Caching:

   • Multi-provider fallback chain (Gemini Flash Lite -> OpenRouter -> Ollama -> Heuristic Mock).

   • Token-bucket rate limiting (15 RPM) and jittered exponential backoff retries.

   • Zero-cost SQLite semantic caching (llm_cache.db) for questionnaire answers.

5. Safety Guardrails & Application Ledger:

   • Audit log in SQLite (application_ledger.db).

   • Duplicate prevention (is_applied check).

   • Fail-closed master switch (AUTO_APPLY_ENABLED=false).

   • Israel/Remote location enforcement and daily run caps (MAX_DAILY_APPLICATIONS).

🛠️ Tool Reference (15 Tools)

⚡ Quick Start

1. Clone & Configure

git clone https://github.com/zvieli/TechJobMCP.git
cd TechJobMCP

# Copy your CV and setup environment
cp /path/to/your/resume.pdf ./cv.pdf
cp .env.example .env

2. Run with Docker Compose

docker compose up -d
docker compose logs -f techjob-mcp

3. Export Public HTTPS Port for AI Clients

curl -L --output cloudflared https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-amd64
chmod +x cloudflared
./cloudflared tunnel --url http://localhost:8000

Connect the generated https://<tunnel-id>.trycloudflare.com/mcp URL to your AI client. See AI Client Integrations Guide for full setup instructions.

🧪 Running Tests

Run the full automated test suite (654 unit and integration tests):

.venv/bin/pytest

📄 License

This project is licensed under the MIT License.