HRMS Tool

Resumen

HRMS Tool es un servidor Model Context Protocol que convierte un conjunto de flujos de trabajo básicos de RR. HH. — incorporación, desvinculación, seguimiento de vacaciones, programación de reuniones, gestión de incidencias de TI y correo electrónico — en herramientas que un agente de IA puede invocar directamente.

En lugar de navegar por un portal de RR. HH., puedes preguntar a un asistente conectado a MCP cosas como:

"Incorporar a Marcus Webb como nuevo reporte de Elena Cross, a partir del lunes." "¿Quién en el equipo de Naomi Steele tiene pocos días de vacaciones?" "Cerrar todos los tickets abiertos de Diego Ramos y cancelar sus próximas reuniones — se va el viernes."

El asistente planifica los pasos, llama a las herramientas adecuadas en el orden correcto y reporta el resultado, utilizando los prompts guiados que se indican a continuación para flujos de trabajo de varios pasos, o herramientas individuales para acciones puntuales.

Related MCP server: HRizzle-HR-Assist

✨ Características

• 👤 Gestión de empleados — añadir, actualizar, buscar y consultar empleados; resolver relaciones jefe/reporte

• 🌴 Gestión de vacaciones — consultar saldos, solicitar vacaciones, revisar historial

• 📅 Programación de reuniones — reservar, listar y cancelar reuniones con detección de conflictos

• 🎫 Sistema de tickets — crear solicitudes de equipos/recursos, seguir el estado, filtrar e inspeccionar tickets

• 📧 Correo electrónico — enviar correos transaccionales a través de Gmail SMTP (texto plano, HTML y adjuntos)

• 🧭 Prompts guiados — flujos de trabajo preconstruidos con múltiples herramientas para incorporación, desvinculación e informe de vacaciones del equipo

• 🌱 Datos de demostración precargados — se inicia con un organigrama realista, historial de vacaciones, reuniones y tickets para que puedas probarlo inmediatamente

🏗️ Arquitectura

flowchart LR
    Client(["MCP Client<br/>(Claude Desktop, etc.)"])

    subgraph MCPServer["mcp-server/"]
        Server["server.py<br/>MCPServer('HRMS Tool')"]
    end

    subgraph HRMSPkg["hrms/"]
        EM["EmployeeManager"]
        LM["LeaveManager"]
        MM["MeetingManager"]
        TM["TicketManager"]
        MAIL["EmailManager"]
    end

    subgraph UtilsPkg["utils/"]
        Seed["seed_services()"]
    end

    Client <-->|stdio| Server

    Server --> EM
    Server --> LM
    Server --> MM
    Server --> TM
    Server --> MAIL
    Server -->|once, at startup| Seed

    EM -->|holds a reference to| LM
    Seed --> EM
    Seed --> LM
    Seed --> MM
    Seed --> TM

    MAIL -->|SMTP| Gmail[(Gmail)]

hrms/schemas.py no se dibuja por separado arriba — es la capa de modelos Pydantic de la que dependen todos los gestores y todas las firmas de herramientas.

Todos los datos residen en memoria durante la vida del proceso — no hay base de datos. Cada reinicio vuelve a generar un conjunto de datos fresco y aleatorio (consulta Datos y persistencia más abajo).

📁 Estructura del proyecto

hrms-claude-tool/
├── hrms/
│   ├── email_manager.py      # Gmail SMTP sender
│   ├── employee_manager.py   # employee CRUD, org chart, name search
│   ├── leave_manager.py      # leave balances & history
│   ├── meeting_manager.py    # meeting scheduling & cancellation
│   ├── schemas.py            # Pydantic models (Employee, Leave, Meeting, Ticket, Email)
│   └── ticket_manager.py     # ticket lifecycle
├── mcp-server/
│   └── server.py             # MCP server entrypoint: tools + prompts
├── utils/
│   └── utils.py              # seed_services() — dummy data generator
├── .env                       # Gmail credentials (not committed)
├── .gitignore
├── .python-version
├── pyproject.toml
├── README.md
└── uv.lock

⚙️ Requisitos previos

• Python 3.14+

• uv para la gestión de dependencias (recomendado)

• Una cuenta de Gmail con una Contraseña de aplicación, si quieres que funcione la herramienta de correo (primero debes activar la verificación en dos pasos)

🚀 Instalación

# Clone the repo
git clone <your-repo-url>
cd hrms-claude-tool

# Install dependencies
uv sync

python -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install "mcp[cli]>=2.0.0" "pydantic>=2.13.4" "requests>=2.34.2" python-dotenv

Nota: email_manager.py importa python-dotenv para cargar .env, pero actualmente no está listado en las dependencias de pyproject.toml — agrégala también allí si estás usando uv sync.

🔐 Variables de entorno

El envío de correo necesita credenciales SMTP de Gmail. Rellena el archivo .env en la raíz del proyecto con:

GMAIL_SENDER_EMAIL=your-address@gmail.com
GMAIL_APP_PASSWORD=your-16-character-app-password

Genera una Contraseña de aplicación en myaccount.google.com/apppasswords (Seguridad → Verificación en dos pasos → Contraseñas de aplicación). Una contraseña normal de Gmail no funcionará.

▶️ Ejecución del servidor

uv run mcp-server/server.py

Esto inicia el servidor MCP a través de stdio y lo precarga con empleados de demostración, registros de vacaciones, reuniones y tickets.

Conexión desde Claude Desktop / Claude Code

Añade una entrada a la configuración de tu cliente MCP (por ejemplo, claude_desktop_config.json):

{
  "mcpServers": {
    "hrms-tool": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/hrms-claude-tool", "run", "mcp-server/server.py"]
    }
  }
}

Reinicia el cliente, y las herramientas y prompts siguientes estarán disponibles en la conversación.

🛠️ Herramientas disponibles

Empleados y organigrama

Vacaciones

Reuniones

Tickets

Correo electrónico

🧭 Prompts disponibles

Los prompts encadenan múltiples herramientas en un flujo de trabajo completo — proporciona un nombre y deja que el agente lo ejecute.

💾 Datos y persistencia

• Todos los datos se mantienen en memoria — nada sobrevive a un reinicio del servidor.

• En cada inicio, seed_services() genera un conjunto de datos de demostración coherente: un organigrama de 8 personas en dos equipos, saldos e historial de vacaciones aleatorios, de 2 a 6 próximas reuniones por empleado, y de 8 a 15 tickets en estados mixtos.

• Los IDs de empleados siguen E001, E002, …; los IDs de tickets siguen T0001, T0002, …

• Los nuevos empleados tienen por defecto un saldo de 20 días de vacaciones, a menos que se siembren con otro valor.

Si necesitas que los datos persistan entre reinicios, deberás reemplazar los diccionarios/listas en memoria de cada clase gestora por un almacén de datos real.

⚠️ Limitaciones conocidas

• No hay autenticación ni autorización en las llamadas a herramientas — el control de acceso se deja completamente al cliente MCP.

• No hay capa de persistencia (ver arriba).

• El envío de correo es solo para Gmail, a través de SMTP + Contraseña de aplicación.

• La detección de conflictos de reuniones solo verifica una coincidencia exacta de marca de tiempo, no rangos superpuestos.

📄 Licencia

Este proyecto está licenciado bajo la Licencia MIT.