mcp-human-resources

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

1. Clone the repository:

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

Repository data layout

• Runtime classpath assets stay in src/main/resources.
• Operational data files used by setup/loading workflows stay under ops/data.
• Current locations:
  • DB seed CSV: ops/data/db/employee_data_load.csv
• Startup note: data.sql reads the DB seed CSV via a relative path, so start the app from the repository root.

2. 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.

3. 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>
   

   Upload policy PDF files from ops/data/gcs and use the GCS object path format policies/<FILENAME>.pdf (example: policies/policies_Business Dress Code Policy.pdf).

   Signed URLs: To enable time-limited signed URL generation for GCS files (e.g. in-browser PDF viewing), you need to create a GCP service account, configure IAM permissions, and set the SIGNING_SERVICE_ACCOUNT environment variable:

   export SIGNING_SERVICE_ACCOUNT=<YOUR_SERVICE_ACCOUNT>@<YOUR_PROJECT_ID>.iam.gserviceaccount.com
   

   See SIGNED_URLS.md for full setup instructions.

Note: If using start-run.sh or start-debug.sh, set these values (including SIGNING_SERVICE_ACCOUNT) 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

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 Policy Vector RAG ingest use later, navigate to http://localhost:5601/app/dev_tools and run:
- `PUT /hr-policy-rag-index`
- Optional mapping override (if needed): set a dense_vector field with dimensions 768

npm i @elastic/mcp-server-elasticsearch

6. 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 Judge 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.

7. 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
   
   

8. 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.

9. 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

10. 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

11. Policy RAG elasticsearch vector data load.

    • Ensure policy PDFs exist in your GCS bucket under policies/.
    • Call POST /rag/policies/ingest-gcs?prefix=policies/ (see src/test/http/rag.http) to ingest GCS PDFs into the hr-policy-rag-index vector index.
    • Query with GET /rag/policies/query?question=... to retrieve grounded policy context and matched policy attachment paths.

12. Run a Maven Install
    

"./mvnw install"

13. 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:

1. 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"
}

2. Open the Run and Debug panel in VS Code (Ctrl+Shift+D or Cmd+Shift+D)

3. Select "Attach to Debug Server (Port 5005)" from the dropdown at the top

4. Click the green play button (or press F5) to attach the debugger

5. 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

• VS Code Setup and Tips - Required extensions, debugging tips, and terminal navigation
• Troubleshooting - Solutions for common issues with environment variables, permissions, and ports

14. 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
    
    

    Inbox listener email test cases (policy + employee flows)
    
    - Sample subject/body content for sending real emails to the monitored inbox is in ops/data/email-samples/
    - Available formats:
    - ops/data/email-samples/inbox_test_emails.md
    - ops/data/email-samples/inbox_test_emails.csv
    - ops/data/email-samples/inbox_test_emails.json
    
    

    **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

15. 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;

16. To see current logging level:
    http://localhost:8081/log

Known Benign Startup Warnings

See Troubleshooting startup warning guidance for the same checklist in the troubleshooting doc.