HireAMate MCP Server

A production-ready Model Context Protocol (MCP) server for job-matching platforms. Exposes AI-callable tools for candidate ranking, job matching, and tradie search.

Features

• ✅ MCP Compliant - Follows Model Context Protocol specification
• ✅ AI-Ready Tools - Three specialized tools for job matching workflows
• ✅ Configurable Scoring - Environment-based weight configuration
• ✅ Service Layer - Easy replacement of mock data with real database/API
• ✅ Structured Logging - JSON or text logging with multiple levels
• ✅ Error Handling - Custom error classes with proper error codes
• ✅ Graceful Shutdown - Proper cleanup on SIGINT/SIGTERM
• ✅ Docker Ready - Multi-stage production Dockerfile
• ✅ TypeScript-Free - Pure JavaScript (ES Modules)
• ✅ Global Install - Available via npm

Quick Start

Global Installation (Recommended)

# Install globally
npm install -g hireamate-mcp-server

# Run from anywhere
hiremate-mcp

# Use with Claude Desktop or other MCP clients
# The command "hiremate-mcp" is now available system-wide

Local Development

# Install dependencies
npm install

# Copy environment template
cp .env.example .env

# Run the server
npm start

# Run in development mode (auto-reload)
npm run dev

# Run tests
npm test

Docker

# Build the image
docker build -t hiremate-mcp-server .

# Run interactively
docker run --rm -it hiremate-mcp-server

# Run with custom config
docker run --rm -e LOG_LEVEL=debug -e DATA_SOURCE=mock hiremate-mcp-server

Tools

1. rankCandidates

Rank and score candidates for a specific job posting.

Scoring Formula:

score = (skills_match × 0.5) + (experience × 0.3) + (location_score × 0.2)

Parameters: | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | jobId | string | Yes | - | Job ID to find candidates for | | limit | number | No | 5 | Max candidates to return (max: 10) |

Example Request:

{
  "jobId": "j001",
  "limit": 3
}

Example Response:

{
  "success": true,
  "job": {
    "id": "j001",
    "title": "Senior Full Stack Developer",
    "company": "TechCorp Australia",
    "requiredSkills": ["JavaScript", "React", "Node.js", "MongoDB"]
  },
  "totalCandidates": 5,
  "candidates": [
    {
      "id": "c001",
      "name": "Alex Thompson",
      "score": 1.0,
      "breakdown": {
        "skillsMatch": 1.0,
        "experience": 1.0,
        "location": 1.0
      },
      "matchedSkills": ["JavaScript", "React", "Node.js", "MongoDB"],
      "skills": ["JavaScript", "React", "Node.js", "MongoDB", "AWS"],
      "experience": 5,
      "location": "Sydney",
      "availability": "immediate",
      "rating": 4.8
    }
  ],
  "scoringWeights": {
    "skills": 0.5,
    "experience": 0.3,
    "location": 0.2
  }
}

2. matchJobs

Find and rank job opportunities for a user based on their skills and preferences.

Scoring Formula:

score = (skills_match × 0.4) + (location × 0.25) + (salary × 0.2) + (jobType × 0.15)

Parameters: | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | userId | string | Yes | - | User ID to find jobs for | | limit | number | No | 5 | Max jobs to return (max: 10) |

Example Request:

{
  "userId": "u001",
  "limit": 3
}

Example Response:

{
  "success": true,
  "user": {
    "id": "u001",
    "name": "John Smith",
    "skills": ["JavaScript", "React", "Node.js"],
    "preferences": {
      "location": "Sydney",
      "remote": true,
      "salaryMin": 100000,
      "jobType": ["full-time", "contract"]
    }
  },
  "totalJobs": 5,
  "jobs": [
    {
      "id": "j001",
      "title": "Senior Full Stack Developer",
      "company": "TechCorp Australia",
      "score": 0.9,
      "breakdown": {
        "skillsMatch": 0.75,
        "location": 1.0,
        "salary": 1.0,
        "jobType": 1.0
      },
      "matchedSkills": ["JavaScript", "React", "Node.js"],
      "missingSkills": ["MongoDB"],
      "matchReason": "Matches 3 required skill(s). Missing: MongoDB. Excellent match"
    }
  ]
}

3. getTradies

Search for tradies (tradespeople) by location and skill with filtering options.

Parameters: | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | location | string | Yes | - | Location to search in | | skill | string | Yes | - | Skill/trade to search for | | minRating | number | No | 4.0 | Minimum rating (0-5) | | availableOnly | boolean | No | true | Only available tradies | | maxDistance | number | No | - | Max distance in km (mock) | | maxHourlyRate | number | No | - | Maximum hourly rate | | requireLicensed | boolean | No | false | Require licensed tradies | | requireInsured | boolean | No | false | Require insured tradies | | limit | number | No | 10 | Max results (max: 20) |

Example Request:

{
  "location": "Sydney",
  "skill": "Electrical",
  "minRating": 4.5,
  "availableOnly": true,
  "limit": 5
}

Project Structure

mcp-server/
├── src/
│   ├── index.js              # Main MCP server entry point
│   ├── config/
│   │   └── index.js          # Configuration management
│   ├── services/
│   │   └── dataService.js    # Data access layer (mock/DB/API)
│   ├── tools/
│   │   ├── rankCandidates.js # Candidate ranking tool
│   │   ├── matchJobs.js      # Job matching tool
│   │   └── getTradies.js     # Tradies search tool
│   ├── utils/
│   │   ├── errors.js         # Custom error classes
│   │   ├── logger.js         # Structured logging
│   │   └── scoring.js        # Scoring utilities
│   └── data/
│       └── mockData.js       # Mock data for testing
├── examples/
│   └── client-example.js     # MCP client usage example
├── test.js                   # Comprehensive test suite
├── package.json
├── Dockerfile
├── .env.example
└── README.md

Environment Variables

Server Configuration

| Variable | Default | Description | |----------|---------|-------------| | MCP_SERVER_NAME | hiremate-mcp | Server name | | MCP_SERVER_VERSION | 1.0.0 | Server version |

Logging

| Variable | Default | Description | |----------|---------|-------------| | LOG_LEVEL | info | debug, info, warn, error | | LOG_FORMAT | text | text, json |

Data Source

| Variable | Default | Description | |----------|---------|-------------| | DATA_SOURCE | mock | mock, database, api | | DATABASE_URL | - | PostgreSQL connection string | | API_BASE_URL | - | REST API base URL |

Scoring Weights (Candidate Ranking)

| Variable | Default | |----------|---------| | CANDIDATE_SKILLS_WEIGHT | 0.5 | | CANDIDATE_EXPERIENCE_WEIGHT | 0.3 | | CANDIDATE_LOCATION_WEIGHT | 0.2 |

Scoring Weights (Job Matching)

| Variable | Default | |----------|---------| | JOB_SKILLS_WEIGHT | 0.4 | | JOB_LOCATION_WEIGHT | 0.25 | | JOB_SALARY_WEIGHT | 0.2 | | JOB_TYPE_WEIGHT | 0.15 |

MCP Integration

Using with an MCP Client

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";

const transport = new StdioClientTransport({
  command: "hiremate-mcp"  // Works with global install!
});

const client = new Client({ name: "my-app", version: "1.0.0" });
await client.connect(transport);

// Call a tool
const result = await client.callTool({
  name: "rankCandidates",
  arguments: { jobId: "j001", limit: 5 }
});

console.log(JSON.parse(result.content[0].text));

Using with Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "hiremate": {
      "command": "hiremate-mcp",
      "env": {
        "LOG_LEVEL": "info"
      }
    }
  }
}

Using with Local Development

{
  "mcpServers": {
    "hiremate": {
      "command": "node",
      "args": ["/path/to/mcp-server/src/index.js"],
      "env": {
        "LOG_LEVEL": "info"
      }
    }
  }
}

Testing

# Run all tests
npm test

# Test output example:
# ╔══════════════════════════════════════════════════════════╗
# ║       HireAMate MCP Server - Comprehensive Tests         ║
# ╚══════════════════════════════════════════════════════════╝
# 
# [TEST SUITE] rankCandidates
#   ✓ Returns success: true
#   ✓ Returns job information
#   ...
# 
# [TEST RESULTS]
#   Passed: 67
#   Failed: 0
#   Total:  67
#   Time:   298ms

Production Deployment

Switching to Real Database

1. Update .env:

DATA_SOURCE=database
DATABASE_URL=postgresql://user:pass@host:5432/hireamate

2. Implement DatabaseDataService in src/services/dataService.js:

class DatabaseDataService {
  async getCandidates() {
    const result = await this.pool.query('SELECT * FROM candidates');
    return result.rows;
  }
  // ... implement other methods
}

Kubernetes Deployment

apiVersion: v1
kind: Pod
metadata:
  name: hiremate-mcp
spec:
  containers:
  - name: mcp-server
    image: hiremate-mcp-server:latest
    env:
    - name: LOG_LEVEL
      value: "info"
    - name: DATA_SOURCE
      value: "database"
    - name: DATABASE_URL
      valueFrom:
        secretKeyRef:
          name: db-secret
          key: url

Publishing to npm

# Login to npm
npm login

# Run tests
npm test

# Publish
npm publish

# Publish globally accessible package
npm publish --access public

License

MIT