mcp-human-resources by dbrown725 - MCP Server

mcp-human-resources

Spring Boot MCP Server implementation focused on exposing Human Resources department data

This was built as a learning tool. Do not use it as a template for a Production application. Giving your LLM access to create, update and delete database rows is probably not a good idea.

Installation

Assumes Linux with Java, Maven, node and npm installed

Clone the repository:

git clone https://github.com/dbrown725/mcp-human-resources.git
cd mcp-human-resources

Setup Brave Search: Acquire API Key, update configuration file and install Node module(s):
https://github.com/modelcontextprotocol/servers-archived/tree/main/src/brave-search
Follow the above directions and acquire an API Key

export BRAVE_API_KEY=<YOUR_BRAVE_API_KEY>

Note: If using the convenience scripts (start-run.sh or start-debug.sh), you don't need to run this export command manually. Just edit the script files and set your API key there.

Setup Google Cloud Storage: Used as a guide: https://github.com/sohamkamani/java-gcp-examples/blob/main/src/main/java/com/sohamkamani/storage/App.java // https://www.youtube.com/watch?v=FXiV4WPQveY
```
export GEMINI_PROJECT_ID=<YOUR_GEMINI_PROJECT_ID>
export STORAGE_BUCKET_NAME=<YOUR_STORAGE_BUCKET_NAME>
```

Note: If using start-run.sh or start-debug.sh, set these values in the script files instead of exporting manually.

4. Needed for Nano Banana image generation bash export GEMINI_API_KEY=<YOUR_GEMINI_API_KEY>

Note: Set this in start-run.sh or start-debug.sh if using those scripts.

5. Setup Elastic Search:
Elastic Search MCP: https://github.com/elastic/mcp-server-elasticsearch

Install Elastic Search and Kibana: https://www.elastic.co/docs/deploy-manage/deploy/self-managed/install-kibana
Directions for loading a csv file into Elastic Search using Kibana.
https://www.elastic.co/blog/importing-csv-and-log-data-into-elasticsearch-with-file-data-visualizer

Use the following data to load an Elastic Index: mcp-human-resources/employee_code_of_conduct_policies.csv
Name the index: employee_code_of_conduct_policies

Configuration: src/main/resources/mcp-servers.json
Note that a space was needed in "ES_API_KEY": " ", since my local Elastic Index does not have security enabled

For ElasticSearch RAG Ingest use later, navigate to http://localhost:5601/app/dev_tools and run "PUT /spring-ai-document-index"

npm i @elastic/mcp-server-elasticsearch

Setup your preferred LLMs, tested with GROQ, OPENROUTER and Google Vertex AI. Image Detection works with Google only, Gemini Flash 2.5 specifically:
Spring AI supported models: https://docs.spring.io/spring-ai/reference/api/index.html
Current code setup with Google Vertex AI as the Primary model/chatClient and two OpenAi compliant models as Secondary and Tertiary models/chatClients
Acquire an API KEY: https://console.groq.com/keys
Acquire an OPENROUTER KEY: https://openrouter.ai/settings/keys

export GROQ_API_KEY=<YOUR_GROQ_API_KEY>
export OPENROUTER_API_KEY=<YOUR_OPENROUTER_API_KEY>

Note: Set these in start-run.sh or start-debug.sh for automatic configuration.

Notes on Google Vertex AI
https://docs.spring.io/spring-ai/reference/api/chat/vertexai-gemini-chat.html
Including the following command run in the terminal that also starts the spring-boot app.
gcloud config set project <YOUR_PROJECT_ID> && gcloud auth application-default login <YOUR_ACCOUNT>

Need to set up ADC. (Need to run on a machine with a browser)
Helped with seting up ADC locally:
https://cloud.google.com/docs/authentication/set-up-adc-local-dev-environment https://www.youtube.com/watch?v=mEsC0BpEYGM
gcloud auth application-default login
In the browser when prompted choose my google user and then selected all access options.
Terminal then showed: Credentials saved to file: [/home/davidbrown/.config/gcloud/application_default_credentials.json]
First test resulted in an error and instructions with url link to resolve. I needed to follow the link and enable Vertex AI API
Setup GMAIL access
Email configuration, currently only Save Draft functionality exists.
Password is NOT your normal gmail password, the password needs to be an APP password: https://support.google.com/mail/answer/185833?hl=en
```
export GMAIL_EMAIL_ADDRESS=<GMAIL_ADDRESSS>
export GMAIL_EMAIL__APP_PASSWORD=<GMAIL_APP_PASSWORD>
```

Note: Set these in start-run.sh or start-debug.sh - these scripts handle all environment variable configuration.

Setup log directory and file

sudo mkdir /var/log/mcp-human-resources
sudo touch /var/log/mcp-human-resources/mcp-human-resources.log
sudo touch /var/log/mcp-human-resources/mcp-human-resources-call-advisor.log
sudo chmod -R 777 /var/log/mcp-human-resources

Setup and configure Prometheus and Grafana on Docker Metrics and Tracing Configuration. Based on https://github.com/danvega/spring-ai-metrics and https://youtu.be/FzLABAppJfM?t=17141

Prometheus: http://localhost:9090
Grafana: http://localhost:3000

I had to update .../mcp-human-resources/docker/prometheus.yml to point to port 8081 instead of 8080 since this app runs on 8081.

I also had to
- go to http://localhost:3000/connections/datasources
- click on the Prometheus datasource
- change the name from 'Prometheus' to 'prometheus'
- click 'Save & Test' to make sure Grafana can connect to Prometheus

I also changed the admin password for Grafana in compose.yml to 'mysecretpassword' from 'admin' for better security.
if admin/mysecretpassword doesn't work, change it back to admin/admin
Rag elasticsearch data load. See ### RAG ingest document test case found in the rag.http file. Download the pdf, uncomment the test, set the path value to your download location and running the test will load the ElasticSearch index.
Run a Maven Install

"./mvnw install"

Start the server

Option A: Using the convenience scripts (Recommended for VS Code development)

The repository includes two convenience scripts that automatically set all required environment variables and start the server:

Step 1: Make the scripts executable

Navigate to the project root directory and run:

cd /home/<YOUR_HOME_DIRECTORY>/Documents/projects/mcp-human-resources
chmod +x start-run.sh
chmod +x start-debug.sh

Step 2: Run the appropriate script

For normal development:

./start-run.sh

For debugging with VS Code breakpoints:

./start-debug.sh

The scripts automatically export all environment variables listed above (BRAVE_API_KEY, GEMINI_PROJECT_ID, STORAGE_BUCKET_NAME, GEMINI_API_KEY, GROQ_API_KEY, OPENROUTER_API_KEY, GMAIL_EMAIL_ADDRESS, GMAIL_EMAIL_APP_PASSWORD).

Important: You need to edit start-run.sh and start-debug.sh to set your actual API keys and credentials before running them. Open each file and replace the placeholder values with your actual keys.

Step 3: (Debug mode only) Attach VS Code debugger

When using ./start-debug.sh, the server starts with remote debugging enabled on port 5005. To enable breakpoint debugging in VS Code:

Ensure your .vscode/launch.json contains an attach configuration:

{
    "type": "java",
    "name": "Attach to Debug Server (Port 5005)",
    "request": "attach",
    "hostName": "localhost",
    "port": 5005,
    "projectName": "humanresources"
}

Open the Run and Debug panel in VS Code (Ctrl+Shift+D or Cmd+Shift+D)
Select "Attach to Debug Server (Port 5005)" from the dropdown at the top
Click the green play button (or press F5) to attach the debugger
Set breakpoints in your Java files - they will now work!

Critical: You must perform the "Attach to Debug Server" step every time you start the server with ./start-debug.sh. If you don't attach the debugger, VS Code will ignore your breakpoints because it's not connected to the running Java process.

Understanding the difference:

"launch" configurations in VS Code start a new Java process
"attach" configurations connect to an already-running Java process
The scripts use Maven to start the server externally, so you need "attach" mode to connect VS Code's debugger to that running process

Option B: Setting environment variables permanently

If you don't want to use the scripts, you can set environment variables permanently in your shell configuration:

For bash users (most Linux systems), add the export statements to ~/.bashrc:

nano ~/.bashrc
# Add all the export statements from start-run.sh or start-debug.sh
# Save and exit (Ctrl+X, then Y, then Enter)
source ~/.bashrc

For zsh users (default on macOS), add them to ~/.zshrc:

nano ~/.zshrc
# Add all the export statements from start-run.sh or start-debug.sh
# Save and exit (Ctrl+X, then Y, then Enter)
source ~/.zshrc

After setting up permanent environment variables, you can start the server directly with Maven:

./mvnw spring-boot:run

Or for debug mode:

./mvnw spring-boot:run -Dspring-boot.run.jvmArguments="-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=*:5005"

Option C: Using the original run.sh script

Update run.sh with your JDK install location and environment variables, then run:

./run.sh

Additional Documentation

- Required extensions, debugging tips, and terminal navigation
- Solutions for common issues with environment variables, permissions, and ports

TESTS

Run unit tests

Navigate to project's root directory and run "./mvnw test"

Run HTTP API tests

Recommended: Use the .http files in src/test/http/ directory
- Install REST Client extension for VS Code
- Or use IntelliJ IDEA's built-in HTTP client
- Open any .http file and click "Send Request" above each endpoint
- See src/test/http/README.md for detailed instructions
```
**Alternative**: Use a browser, curl, or Postman<br>
- Example: http://localhost:8081/employees/5012<br>
- Example: http://localhost:8081/ai?prompt=How%20many%20employees%20in%20IT%20are%20asian?<br><br>
```
Can be tested using the associated Client APP:
https://github.com/dbrown725/mcp-human-resources-client
Uses H2 as a database, it is loaded on application startup.
http://localhost:8081/h2-console
Password is in application.properties
Sample query: Select * from EMPLOYEE where AGE > 50;
To see current logging level:
http://localhost:8081/log

Known Benign Startup Warnings

See for the same checklist in the troubleshooting doc.