# MCP Job Matching Server

A lightweight **Model Context Protocol (MCP)** server built with **TypeScript** and **Node.js** that helps AI agents evaluate candidate-job fit by calculating weighted match scores.

Built using the official [`@modelcontextprotocol/sdk`](https://github.com/modelcontextprotocol/typescript-sdk).

## What is MCP?

The [Model Context Protocol](https://modelcontextprotocol.io/) is an open standard that allows AI assistants (like Claude, Gemini, etc.) to interact with external tools and data sources through a unified interface. MCP servers expose **tools** that AI agents can discover and invoke autonomously.

This server demonstrates how to build a production-style MCP server that could power recruitment workflows in the agentic web.

## Features

| Tool | Description |
|------|-------------|
| `get_mock_jobs` | Returns a list of job postings with required and preferred skills (simulates a database query) |
| `calculate_match_score` | Compares a candidate's skills against a job's requirements and returns a weighted score with detailed breakdown |

### Match Score Algorithm

The scoring engine uses a **weighted formula**:

```
Overall Score = (Required Skills Match × 0.70) + (Preferred Skills Match × 0.30)
```

The response includes:
- Overall match percentage
- Required vs preferred skills breakdown
- Matched and missed skills lists
- Hiring recommendation (`STRONG FIT`, `GOOD FIT`, or `STRETCH / LOW FIT`)

## Tech Stack

- **Runtime:** Node.js (ES2022)
- **Language:** TypeScript (strict mode)
- **Protocol:** MCP over Stdio transport (JSON-RPC 2.0)
- **SDK:** `@modelcontextprotocol/sdk`

## Getting Started

### Prerequisites

- [Node.js](https://nodejs.org/) v18+ installed
- npm

### Installation

```bash
git clone https://github.com/nourelhoudaas/mcp-job-matching-server.git
cd mcp-job-matching-server
npm install
```

### Build

```bash
npm run build
```

### Run the test client

A test script is included that spawns the server, sends a `tools/call` request via JSON-RPC, and prints the match score result:

```bash
node test-client.js
```

Expected output:

```
Starting MCP server for testing...
Server stderr log: Job Match MCP Server running on Stdio transport
Sending tools/call request to server stdin...
Received from server stdout: { ... overallMatchScore: "53%" ... }

Success: MCP Server successfully executed calculate_match_score!
```

### Use with Claude Desktop

Add this to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "job-matcher": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-job-matching-server/build/index.js"]
    }
  }
}
```

Then ask Claude: *"Use the job-matcher tool to calculate my match score for the alpic-fullstack job with skills: TypeScript, React, Node.js"*

## Project Structure

```
mcp-job-matching-server/
├── src/
│   └── index.ts          # MCP server implementation
├── build/                 # Compiled JS (generated by tsc)
├── test-client.js         # Automated verification script
├── package.json
├── tsconfig.json
└── README.md
```

## Example Request & Response

**Request** (JSON-RPC 2.0 via stdin):
```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "calculate_match_score",
    "arguments": {
      "candidateSkills": ["TypeScript", "React", "Node.js", "SQL", "REST APIs"],
      "jobId": "alpic-fullstack"
    }
  }
}
```

**Response** (via stdout):
```json
{
  "jobId": "alpic-fullstack",
  "company": "Alpic",
  "title": "Full-Stack Software Engineer",
  "overallMatchScore": "53%",
  "breakdown": {
    "requiredSkillsMatch": "3/4",
    "preferredSkillsMatch": "0/4"
  },
  "matchedRequired": ["TypeScript", "React", "Node.js"],
  "missedRequired": ["English communication"],
  "matchedPreferred": [],
  "missedPreferred": ["AWS CDK", "NestJS", "MCP", "Developer tools"],
  "recommendation": "STRETCH / LOW FIT - Tailor carefully"
}
```

## Author

**Nour EL Houda SAYAH** — [GitHub](https://github.com/nourelhoudaas) · [Portfolio](https://nourhouda.netlify.app)