convez.ai
MCP Server
osa-ora

hr-mcp-agent-demo

osa-ora/hr-mcp-agent-demo

Ver no GitHub
InicialPluginScore · de 0 a 100

Demo building HR system using Custom HR MCP Server & Agent

Instalação

$npx convez-ai osa-ora/hr-mcp-agent-demo

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
0
Saúde
28%
Último commit
há 4 meses
Versão
—
Issues abertas
0
Contribuidores
1

README

A tradução para o português deste README ainda está na fila.

HR MCP Agent Demo


A demonstration project showing how to build an AI-powered HR assistant using a custom MCP (Model Context Protocol) server, an autonomous agent, and a PostgreSQL-backed HR system.

The goal of this project is to illustrate how enterprise business systems can be exposed as AI tools (via a custom MCP server) and consumed by an agent capable of performing HR workflows through natural language interactions.

This demostrates the concept that:

AI is the new UI for applications


Overview

This demo consists of five main components:

1. HR Database

A PostgreSQL database containing HR-related information such as:

  • Employee profiles
  • Managers and reporting structures
  • Employee contacts
  • Employment information
  • Leave balances
  • Leave requests
  • Leave types
  • Compensation information
  • HR policies

You can see tables like employees:

employees = Table(
    "employees",
    metadata,
    # Business identity (PRIMARY KEY NOW)
    Column("employee_code", String(50), primary_key=True),
    Column("full_name", String(200), nullable=False),
    Column("sex", String(20)),
    Column("birthdate", Date),
    Column("marital_status", String(50)),
    Column("nationality", String(100)),
    # Business relationship (no FK constraint by design)
    Column("manager_code", String(50), nullable=True),
    Column("created_at", DateTime),
    Column("updated_at", DateTime)
)

Here is a simplified view of the sample HR DB:

2. Database Service Layer

This layer exposes the database functionality in the file db_service.py. It exposes the needed CRUD operations for all tables transactions and enforce some rules as well:

def get_employee_profile(employee_code: str):
    with engine.begin() as conn:
        emp = _get_employee(conn, employee_code)
        return dict(emp) if emp else None

The database is configured in the file db.py and it inherit the value from config file which get these values from .env file. You can update that file .env it to point to your database:

from config import DATABASE_URL

engine = create_engine(
    DATABASE_URL or "postgresql+psycopg2://postgres:postgres@localhost:5432/hrdb",
    echo=False
)

3. Custom HR MCP Server

A custom MCP server built using FastMCP that exposes HR operations as tools, FastMCP is a Python framework for building and exposing tools through the Model Context Protocol (MCP). It simplifies the creation of AI-accessible services by providing a lightweight way to define, register, and serve tools that can be discovered and invoked by MCP-compatible agents and clients.

Example capabilities include:

  • Employee profile lookup
  • Detailed employee information retrieval
  • Manager lookup
  • Leave balance inquiries
  • Leave request creation
  • Leave request approval and rejection
  • Policy search
  • Leave type discovery

You can see function like:

import db_service as db

# =========================================================
# EMPLOYEE PROFILE
# SKILL: employee_profile
# =========================================================
@mcp.tool(
    annotations={"skill": "employee_profile"},
    description="""
ROLE: ANY EMPLOYEE

Get basic employee basic profile information using employee_code
"""
)
def get_employee_basic_profile(employee_code: str):
    return db.get_employee_profile(employee_code)

That's very simple and easy way to build pluggable integration layer for AI that exposes your internal system functionality. Without MCP, the LLM would need custom integration code for every business system. MCP standardizes tool access, allowing any MCP-compatible client or agent to discover and invoke enterprise functionality through a common protocol.

The good level of tool description is essential to let the LLM understand the use of that function very well and its input parameters and if there is any constraints like required role.

You can change the mcp_server configurations especially if you plan to run many and need different ports for execution, to do this change the .env file:

from config import MCP_HOST, MCP_PORT, MCP_TRANSPORT

if __name__ == "__main__":
    print("REGISTERED TOOLS:", mcp.list_tools())

    mcp.run(
        transport=MCP_TRANSPORT,
        host=MCP_HOST,
        port=MCP_PORT
    )

We used initially SSE protocol but then switched to HTTP, The SSE (Server-Sent Events) is a lightweight HTTP-based protocol that allows a server to continuously push real-time updates to a client over a single long-lived connection, it becomes a legacy now and most of the modern mcp are using http (or streamable_http).

The MCP server acts as a secure abstraction layer between the agent and the HR system.


4. HR Agent

HR Agent Examples

We have built four HR agent examples:

First: Custom Python Agent

A custom Python AI agent powered by a local LLM through Ollama, named hr_agent.py.

Second: Level-1 LangGraph Agent

A Level-1 LangGraph agent, also powered by a local LLM through Ollama, named lang-graph-hr-agent.py. This version sends all MCP server tools to the LLM for planning and execution.

LangGraph is a framework for building stateful, multi-step AI agents using graph-based workflows. It enables developers to model complex reasoning, planning, tool-calling, and decision-making processes as interconnected nodes, making agent execution more controllable, observable, and maintainable than traditional prompt chains.

Third: Level-2 LangGraph Agent

A Level-2 LangGraph agent named lang-graph-hr-agent-v2.py. This version is skill-based, filtering MCP server tools by skill (virtual grouping) and sending only the relevant tool groups required by the LLM to complete the requested task.

Skill-Based Tool Routing

The agent uses a lightweight skill-selection layer to identify the minimum set of MCP tool categories required for a user request. By filtering available tools before planning, the agent reduces prompt size, improves tool-selection accuracy, and keeps reasoning focused on the relevant domain capabilities.

Fourth: Level-3 LangGraph Agent

A Level-3 LangGraph agent named lang-graph-hr-agent-v3.py. This version builds on the skill-based architecture and externalizes prompts into dedicated template files.

Prompt Externalization with Jinja2

The agent uses Jinja2 templates to externalize all LLM prompts from the application code. This separates prompt engineering from business logic, making prompts easier to maintain, version, test, and update without modifying the agent implementation. Runtime context (such as user input, tool schemas, and execution history) is injected into templates to generate the final prompts sent to the model.

Jinja is a fast, expressive, extensible templating engine. Special placeholders in the template allow writing code similar to Python syntax. Then the template is passed data to render the final document, e.g. {{ variable }} place holders, while {% %} is control flow syntax. Read more: https://jinja.palletsprojects.com/en/stable/

For Example: response.jinja2

You are a helpful HR Assistant.

Answer the user's original request using the provided history of tool execution steps.
Be concise, professional, and do not mention the technical tool names.

User Request: {{ user_input }}

Execution History Data:
{{ history }}

And we seed these placeholders with the corresponding values for the agent.

The agent main functions:

  • Understands user requests
  • Discovers available MCP tools
  • Selects the appropriate tool
  • Executes multi-step workflows
  • Maintains conversational context
  • Produces user-friendly responses

You can still customize agent(s) configurations as following:

# For the custom Python agent:

agent = HRAgent(
    AgentConfig(
        debug=False,
        max_steps=9,
        mcp_endpoint="http://127.0.0.1:8000/mcp",
        model_name="llama3.1"
    )
)

# if you called in of them without any configurations, the defaults are resolved from environment variables via .env file through config.py.

from config import MODEL_NAME, DEBUG, MAX_STEPS, MCP_ENDPOINT

# for both LangGraph agent(s):

class Config:
    model_name = "llama3.1"
    mcp_url = "http://127.0.0.1:8000/mcp"
    debug = False
    max_steps= = 5

# And it also get these values from the .env file through config.py

Example requests:

  • "leave balance for Osama Oransa?"
  • "basic profile for Sara Ali"
  • "Show my full profile for EMP001?"
  • "policy for remote work?"
  • "leave requests for Osama Oransa."
  • "basic profile for EMP002"

Alternatively, you can use any ChatClient and configure the model and the mcp server to convert it to HR Agent (as we well see in the following section).

5. LLM Models

In this demo, we used local Ollama models such as llama3.1.


Technologies Used

  • Python, FastMCP, MCP (Model Context Protocol), Ollama, Llama 3.1, PostgreSQL, SQLAlchemy, AsyncIO, Langgraph and others.

Learning Objectives

This project demostrates:

  • Building custom MCP servers
  • Tool-based AI agents
  • LangGraph orchestration Agent
  • Enterprise system integration
  • Multi-step agent workflows
  • Database-backed AI applications
  • Agent-to-tool orchestration
  • Natural language interfaces for business systems.

How to Run the Demo

After cloning the repository, follow these steps:

1. Setup environment

./setup_venv.sh

This will create a Python 3.12 virtual environment and install all required dependencies.


2. Activate environment

source .venv/bin/activate

Then edit the .env file for any changes you need to do.


3. Start PostgreSQL DB & Create 'hrdb' database

CREATE DATABASE hrdb;

4. Initialize database schema

python3 init_db.py

5. Seed test data

python3 seed_init_data.py

6. Run MCP server

python3 mcp_server.py

If successful, you will see:

Starting MCP server 'hr-system-v2' with transport 'http' on transport.py:304 http://0.0.0.0:8000/mcp

MCP Server Screenshot


Run the Local LLM

Install and start Ollama:

ollama pull llama3.1
ollama serve

You can also use other compatible models if needed.


Run the Python Agent

You can test the agent using the provided notebook:

test-agent.ipynb

Run all cells and interact with the HR Agent the way you want.

Or you can run it directly from the command line:


source .venv/bin/activate
python3 hr_agent.py

Or you can run the LangGraph Agent directly from the command line:


source .venv/bin/activate
python3 lang-graph-hr-agent.py

You can then use the better quality agent, that filter the mcp tools based on the needed skills to respond to customer specific request, using:


source .venv/bin/activate
python3 lang-graph-hr-agent-v2.py

Finally, the more dynamic agent, that filter the mcp tools and load the prompt from templates, using:


source .venv/bin/activate
python3 lang-graph-hr-agent-v3.py

You can see the LangGraph agent is much more mature and more accurate.

Note: The performance of all these agents can be more solid if they use a better and strong LLM.

Note: To check the optimal agent, with multiple dynamic MCP Server discovery, check the following repository: https://github.com/osa-ora/ocp-ai-mcp-client-demo


Using a Chat UI (Optional)

The other way is to integrate the system with a chat interface such as Open WebUI or any MCP-compatible client.

  • Add the required model: e.g. Ollama
  • Add MCP_SERVER and name it as HR MCP_SERVER

Here I am using for example: ChatBox: https://github.com/chatboxai/chatbox

This allows a more natural chat-based experience instead of running the Python agent directly.


How to Run the HR MCP Server on OpenShift Environment

Folliw the detailed instructions in the GitHub Repository: https://github.com/osa-ora/ocp-ai-custom-mcp-demo

License

This project is for educational and demonstration purposes only.

Ver o original no GitHub

Bom para

Relacionados