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.

📁 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