kazhian/hr-data-mcp

HR Data MCP Server

A Model Context Protocol (MCP) server built with Spring Boot and Spring AI, providing AI assistants with access to HR employee data through standardized queries and operations.

Overview

This project implements an MCP server that exposes HR employee data to AI assistants, enabling them to answer questions about employees, departments, skills, and organizational structure. The server uses an in-memory H2 database pre-populated with comprehensive employee records for testing and demonstration purposes.

Features

• MCP Protocol Implementation: Standards-compliant Model Context Protocol server
• Spring Boot Integration: Built on Spring Boot with Spring AI for robust enterprise-grade architecture
• In-Memory Database: H2 database with 100+ employee records across multiple departments
• Comprehensive Data Model: Employee records include roles, departments, skills, and contact information
• RESTful API: Easy-to-use endpoints for HR data operations
• Department Coverage: Data spans across AP, AFS, DAP, ISBLT, OPSSVC, CORE, and LIGHT departments

Technology Stack

• Java 17+
• Spring Boot 3.x
• Spring AI
• H2 Database (In-Memory)
• Gradle (Build Tool)
• Model Context Protocol (MCP)

Database Schema

CREATE TABLE employees (
    id INT PRIMARY KEY,
    name VARCHAR(100),
    role VARCHAR(100),
    department VARCHAR(50),
    email VARCHAR(100),
    skills VARCHAR(200)
);

Sample Data

The database includes 100 diverse employee records with:

• Departments: AP, AFS, DAP, ISBLT, OPSSVC, CORE, LIGHT
• Roles: Developers, Engineers, Managers, Analysts, Specialists
• Skills: Various technology stacks, programming languages, frameworks, and business skills
• Email Format: firstname.lastname@mcp.com

Getting Started

Prerequisites

• Java 17 or higher
• Gradle 7.x or higher

Installation

1. Clone the repository:

   git clone https://github.com/yourusername/hr-data-mcp.git
   cd hr-data-mcp
   

2. Build the project:

   ./gradlew build
   

3. Run the application:

   ./gradlew bootRun
   

The server will start on http://localhost:8080

Configuration

Application properties can be configured in src/main/resources/application.properties:

# Server configuration
server.port=8080

# H2 Database configuration
spring.datasource.url=jdbc:h2:mem:hrdb
spring.datasource.driver-class-name=org.h2.Driver
spring.h2.console.enabled=true

# Spring AI configuration
# Add your AI provider configurations here

API Endpoints

Employee Operations

• GET /api/employees - Get all employees
• GET /api/employees/{id} - Get employee by ID
• GET /api/employees/department/{dept} - Get employees by department
• GET /api/employees/search?skill={skill} - Search employees by skill

MCP Protocol Endpoints

• POST /mcp/query - Execute MCP queries
• GET /mcp/schema - Get available data schema
• GET /mcp/capabilities - Get server capabilities

Example Queries

The MCP server can handle various types of queries:

• "Show me all Java developers in the AP department"
• "Who are the machine learning engineers?"
• "List employees with React skills"
• "What departments does the company have?"
• "Find employees with cloud computing experience"

Project Structure

src/
├── main/
│   ├── java/
│   │   └── com/example/hrdatamcp/
│   │       ├── HrDataMcpApplication.java
│   │       ├── controller/
│   │       ├── model/
│   │       ├── repository/
│   │       └── service/
│   └── resources/
│       ├── application.properties
│       └── data.sql
└── test/

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Use Cases

This MCP server is ideal for:

• AI Assistant Integration: Enable AI assistants to query HR data
• Learning MCP Protocol: Understand how to implement MCP servers
• HR Analytics: Demonstrate AI-powered HR data analysis
• Prototyping: Quick setup for HR-related AI applications
• Testing: Comprehensive dataset for various query scenarios

License

This project is licensed under the MIT License - see the file for details.

Acknowledgments

• Built with Spring Boot
• Uses Spring AI for AI integration
• Implements Model Context Protocol
• H2 Database for lightweight data storage

Support

If you have questions or run into issues, please:

1. Check the Issues page
2. Create a new issue with detailed information
3. Contribute improvements via Pull Requests

Note: This is a demonstration project with sample data. For production use, implement proper security, authentication, and use a persistent database.