HR Solx Server

A Model Context Protocol (MCP) server that exposes HR API endpoints as AI-accessible tools. Built with Express.js and the official MCP SDK.

What It Does

This server acts as a bridge between AI models (Claude, GPT, etc.) and the HR Solx REST API. AI clients can discover and invoke tools through the MCP protocol, enabling natural language interactions with HR data like users, countries, skills, roles, and more.

Features

• 12 MCP Tools — Health checks, geographic data, reference data, and user management
• Streamable HTTP Transport — Stateless JSON-RPC 2.0 communication
• TypeScript — Full type safety with Zod validation
• Modular Architecture — Organized codebase with separated concerns
• Authentication — API key protection for MCP endpoint
• Rate Limiting — IP-based request throttling
• Error Handling — Typed errors with contextual messages

System Architecture

graph LR
    AI["AI Client\n(Claude, GPT)"] -->|"POST /mcp\nJSON-RPC 2.0"| Express["Express Server\n(MCP Protocol)"]
    Express -->|"fetch"| API["HR API\napi.hr-solx-mobile.com"]
    API -->|"JSON Response"| Express
    Express -->|"SSE Stream"| AI

    subgraph Middleware
        Express
    end

    classDef ai fill:#e1f5fe,stroke:#01579b
    classDef server fill:#fff3e0,stroke:#e65100
    classDef api fill:#e8f5e9,stroke:#2e7d32
    class AI ai
    class Express server
    class API api

Quick Start

npm install
npm run dev

Server runs at http://localhost:4000/mcp

Environment Variables

Variable	Default	Description
MCP_SERVER_PORT	4000	Server listening port
MCP_API_URL	https://api.hr-solx-mobile.com	Upstream HR API URL
MCP_API_KEY	—	API key to protect MCP endpoint
API_TOKEN	—	Bearer token for upstream API auth
RATE_LIMIT_WINDOW_MS	900000	Rate limit window (15 min)
RATE_LIMIT_MAX_REQUESTS	100	Max requests per window

Copy .env.example to get started:

cp .env.example .env

Available Tools

Health Checks

Tool	Description
basic-health-check	Check if API is reachable
detailed-health-check	Comprehensive system health

Geographic Data

Tool	Description
get-countries	List all countries
get-states	List all states
get-cities	List all cities

Reference Data

Tool	Description
get-skills	List available skills
get-languages	List available languages
get-working-statuses	List working statuses
get-roles	List available roles

User Management

Tool	Description	Params
get-users	List all users	—
create-user	Create a new user	name, email, mobile

Usage Examples

List Available Tools

curl -X POST http://localhost:4000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","method":"tools/list","params":{},"id":1}'

Call a Tool

curl -X POST http://localhost:4000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "get-users",
      "arguments": {}
    },
    "id": 1
  }'

Create a User

curl -X POST http://localhost:4000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "create-user",
      "arguments": {
        "name": "John Doe",
        "email": "[email protected]",
        "mobile": "+1234567890"
      }
    },
    "id": 1
  }'

With Authentication

curl -X POST http://localhost:4000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "X-API-Key: your-api-key" \
  -d '{"jsonrpc":"2.0","method":"tools/list","params":{},"id":1}'

Project Structure

├── docs/                          # Detailed documentation
│   ├── ARCHITECTURE.md            # System architecture & design
│   ├── MCP-PROTOCOL.md            # MCP protocol guide
│   ├── TOOLS-REFERENCE.md         # Complete tool catalog
│   ├── DEVELOPER-GUIDE.md         # How to extend & test
│   ├── SECURITY.md                # Security considerations
│   ├── TROUBLESHOOTING.md         # Common issues & fixes
│   └── REQUEST-FLOW.md            # Request lifecycle
├── src/
│   ├── index.ts                   # Server entry point
│   ├── types/
│   │   ├── api.ts                 # API response interfaces
│   │   └── errors.ts              # Custom error types
│   ├── client/
│   │   └── api-client.ts          # Upstream API client
│   ├── tools/
│   │   ├── echo.ts                # Echo tool/resource/prompt
│   │   ├── health.ts              # Health check tools
│   │   ├── reference.ts           # Reference data tools
│   │   └── users.ts               # User management tools
│   └── middleware/
│       ├── auth.ts                # API key authentication
│       └── rate-limit.ts          # Rate limiting
├── .env.example                   # Environment template
├── package.json
└── tsconfig.json

Module Dependencies

graph TD
    Index["src/index.ts\n(Server Entry)"] --> Types["src/types/\n(api.ts, errors.ts)"]
    Index --> Client["src/client/\n(api-client.ts)"]
    Index --> Tools["src/tools/\n(echo, health, reference, users)"]
    Index --> Middleware["src/middleware/\n(auth, rate-limit)"]
    Tools --> Client
    Tools --> Types
    Client --> Types

    classDef entry fill:#fff3e0,stroke:#e65100
    classDef module fill:#e3f2fd,stroke:#1565c0
    class Index entry
    class Types,Client,Tools,Middleware module

See docs/ARCHITECTURE.md for full details.

Adding New Tools

1. Define the TypeScript interface in src/types/api.ts
2. Register the tool in the appropriate module under src/tools/
3. Import and register in src/index.ts

See docs/DEVELOPER-GUIDE.md for step-by-step instructions.

Security

The server supports two layers of authentication:

• MCP endpoint — Protected via X-API-Key header (MCP_API_KEY)
• Upstream API — Authenticated via Bearer token (API_TOKEN)

See docs/SECURITY.md for full security guide and production checklist.

Troubleshooting

Common issues and solutions are documented in docs/TROUBLESHOOTING.md.

Quick checks:

# Verify server is running
curl http://localhost:4000/mcp

# Test upstream API
curl https://api.hr-solx-mobile.com/health

# Check environment variables
echo $MCP_API_URL
echo $MCP_SERVER_PORT

License

MIT