JobMatch MCP 🚀

An enterprise-grade, AI-powered multi-user job-search and resume-matching platform engineered to master the Model Context Protocol (MCP) end-to-end.

🌟 Overview & Highlights

• Native Local MongoDB Integration: High-performance async database connectivity using Motor + PyMongo with automatic index creation on startup. Zero Docker requirement for local execution.

• FastAPI Modular Backend: Fully typed Pydantic v2 schemas, strict JWT Bearer authentication, tenant isolation, and centralized error handling.

• Strict 100% Required Skill Matching: Multi-dimensional weighted scoring engine that guarantees 100% required match is earned ONLY when all mandatory skills are satisfied.

• Deterministic Resume Parser: Ingests PDF and DOCX files to extract technical taxonomies, languages, tools, and experience years.

• Configurable Per-User Preferences: Custom target roles, locations, salary thresholds, recency filtering, and natural-language search instructions.

• Model Context Protocol Boundary: Explicit client interface ready for incremental attachment of real MCP servers in future phases (Job Search, Excel Export, Email Dispatch).

• Modern React 18 + Vite Frontend: Responsive dashboard with metrics, job cards, deep matching telemetry, and clean vanilla CSS design system.

Related MCP server: PROTEUS MCP Server

📁 Repository Structure

/opt/JOB-MCP/
├── backend/
│   ├── app/
│   │   ├── main.py              # FastAPI application, lifespan & middleware
│   │   ├── core/                # Config, security, logging, dependencies
│   │   ├── api/                 # Versioned API routes (auth, jobs, matches, etc.)
│   │   ├── models/              # MongoDB document definitions
│   │   ├── schemas/             # Pydantic v2 request/response models
│   │   ├── services/            # Matching engine, parser, job providers, storage
│   │   ├── db/                  # Motor MongoDB client and index initializers
│   │   ├── ai/                  # LLM provider abstraction (Groq, Gemini, Ollama, Local)
│   │   └── mcp/                 # MCP client contract and tool registry boundary
│   ├── tests/                   # Pytest suite (Auth, Resumes, Prefs, Jobs, Matching, Security)
│   ├── requirements.txt
│   └── Dockerfile
├── frontend/
│   ├── src/
│   │   ├── components/          # Navbar, Sidebar, MatchBadge, ProtectedRoute
│   │   ├── pages/               # Login, Register, Dashboard, Resume, Preferences, Jobs, etc.
│   │   ├── services/            # Axios API client modules
│   │   ├── context/             # AuthContext session provider
│   │   ├── types/               # TypeScript interfaces
│   │   ├── App.tsx              # React router definitions
│   │   └── index.css            # Modern dashboard design system
│   ├── vite.config.ts           # Proxy to backend port 8000
│   ├── package.json
│   └── Dockerfile
├── docs/                        # Deep-dive architecture, API, matching, and MCP docs
├── storage/resumes/             # Isolated local resume storage
├── docker-compose.yml           # Optional container orchestration
├── .env.example                 # Config template
└── README.md

⚙️ Quickstart (Native Local Run)

1. Prerequisites

• Python 3.11+

• Node.js 20+ & npm

• MongoDB running on localhost:27017

2. Backend Setup & Startup

cd /opt/JOB-MCP/backend
python3 -m uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload

Interactive OpenAPI Swagger Docs: http://localhost:8000/docs

3. Frontend Setup & Startup

cd /opt/JOB-MCP/frontend
npm run dev -- --host 0.0.0.0 --port 5173

Access the Dashboard: http://localhost:5173

⚡ Model Context Protocol (MCP) Tools & Diagnostics

1. Run the MCP Diagnostic Scripts

• Job Search MCP Test (Phase 3):

  python3 scripts/test_job_mcp.py

• Excel Report MCP Test (Phase 4):

  python3 scripts/test_excel_mcp.py

• Email Report MCP Test (Phase 5):

  python3 scripts/test_email_mcp.py

• Autonomous AI Agent Orchestration Test (Phase 6):

  python3 scripts/test_agent.py

• Scheduled Automation & Free Operation Test (Phase 7):

  python3 scripts/test_automation.py

2. Run MCP Servers Directly over stdio

• Job Search MCP Server:

  python3 mcp/job_search_server/server.py

• Excel Report MCP Server:

  python3 mcp/excel_server/server.py

• Email Report MCP Server:

  python3 mcp/email_server/server.py

🧪 Running Automated Tests

Run the full pytest suite (69 unit, integration, security, and MCP tests across all 7 phases):

cd /opt/JOB-MCP
python3 -m pytest -v backend/tests

📋 Technology Stack

• Backend: Python 3.11, FastAPI, Pydantic v2, Motor, PyMongo, PyJWT, bcrypt, pypdf, python-docx, openpyxl, smtplib, pytest, pytest-asyncio

• Official MCP SDK: mcp v2.2.0 (MCPServer, stdio_client, ClientSession)

• Database: MongoDB 7.0+ (Native host service, database jobmatch_mcp)

• Frontend: React 18, TypeScript, Vite, React Router v6, Axios, Vanilla CSS

• Semantic AI Provider: Groq Official Python SDK (openai/gpt-oss-120b, optional openai/gpt-oss-20b)

• Semantic Caching: MongoDB SHA-256 Job Analysis Cache (job_analysis_cache) & Canonical Skill Normalization Cache (skill_normalization_cache)

• Autonomous AI Agent: app.agent.orchestrator.AgentOrchestrator coordinating multi-step search, deterministic evaluation, Excel generation, and verified-recipient email dispatch

• Scheduled Automation: Wake-on-demand background automation triggered by external schedulers (GitHub Actions cron, OS cron) with constant-time HMAC secret authentication (POST /api/v1/automation/run)

• Idempotent Matching: Persistent reported-job deduplication (user_reported_jobs) enforcing strict "No new matches = No email" policy

• Safety Policy: MAX_AGENT_STEPS = 12 step limit clamp, verified-recipient human-safe email enforcement, prompt-injection boundary wrappers (<<<UNTRUSTED_JOB_DATA>>>)

• Job Search MCP Tools: search_jobs, fetch_job, extract_job_details, normalize_job

• Job Search MCP Resources & Prompts: job-search://sources, job-search://configuration, job_search_strategy

• Excel Report MCP Tools: create_job_report, export_excel, append_job_match

• Excel Report MCP Resources & Prompts: excel://configuration, excel://schema, job_report_summary

• Email Report MCP Tools: send_email, send_job_report, send_test_email

• Email Report MCP Resources & Prompts: email://configuration, job_report_email