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.

What is MCP?

The Model Context Protocol 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 v18+ installed
• npm

Installation

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

Build

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:

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:

{
  "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):

{
  "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):

{
  "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 · Portfolio