# 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

```text
/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
```bash
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](http://localhost:8000/docs)

### 3. Frontend Setup & Startup
```bash
cd /opt/JOB-MCP/frontend
npm run dev -- --host 0.0.0.0 --port 5173
```
Access the Dashboard: [http://localhost:5173](http://localhost:5173)

---

## ⚡ Model Context Protocol (MCP) Tools & Diagnostics

### 1. Run the MCP Diagnostic Scripts
- **Job Search MCP Test (Phase 3):**
  ```bash
  python3 scripts/test_job_mcp.py
  ```
- **Excel Report MCP Test (Phase 4):**
  ```bash
  python3 scripts/test_excel_mcp.py
  ```
- **Email Report MCP Test (Phase 5):**
  ```bash
  python3 scripts/test_email_mcp.py
  ```
- **Autonomous AI Agent Orchestration Test (Phase 6):**
  ```bash
  python3 scripts/test_agent.py
  ```
- **Scheduled Automation & Free Operation Test (Phase 7):**
  ```bash
  python3 scripts/test_automation.py
  ```

### 2. Run MCP Servers Directly over stdio
- **Job Search MCP Server:**
  ```bash
  python3 mcp/job_search_server/server.py
  ```
- **Excel Report MCP Server:**
  ```bash
  python3 mcp/excel_server/server.py
  ```
- **Email Report MCP Server:**
  ```bash
  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):
```bash
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`