HumanResourcesManagement-MCP — Servidor MCP para Gestión de Recursos Humanos

Servidor MCP (Model Context Protocol) que actúa como puente entre un LLM (Claude Desktop, ChatGPT, etc.) y el backend Spring Boot HumanResourcesManagement-Backend. Expone todas las operaciones del backend como tools MCP que el LLM puede invocar directamente.

LLM (Claude / ChatGPT)
    ↕  MCP Protocol (stdio o HTTP)
MCP Server (Node.js + TypeScript)
    ↕  HTTP REST (JWT)
Spring Boot Backend

Arquitectura

El proyecto sigue arquitectura hexagonal (puertos y adaptadores) en 3 capas, reflejando la misma filosofía del backend:

Capa	Responsabilidad
Domain	Modelos puros (Persona, Usuario, Sesion), excepciones, interfaz del puerto de salida BackendApiPort
Application	Casos de uso (*UseCase), DTOs, mappers, interfaces de puertos de entrada *ToolsPort
Infrastructure	Adaptador de entrada MCP (McpServerAdapter), adaptador de salida HTTP (HttpClientAdapter), configuración

Stack: Node.js 22, TypeScript 5, Express 4, @modelcontextprotocol/sdk 1.x, Zod 3

Estructura del proyecto

HumanResourcesManagement-MCP/
├── src/
│   ├── index.ts                              # Punto de entrada
│   ├── domain/
│   │   ├── model/                            # Sesion, Persona, Usuario
│   │   ├── exception/                        # AuthException, BackendException, ValidationException
│   │   └── port/output/
│   │       └── backend-api.port.ts           # Contrato del backend
│   ├── application/
│   │   ├── dto/                              # DTOs de aplicación
│   │   ├── mapper/                           # Mappers DTO ↔ Modelo dominio
│   │   ├── port/input/                       # Interfaces de casos de uso
│   │   └── usecase/                          # Implementación de casos de uso
│   └── infrastructure/
│       ├── config/
│       │   └── app.config.ts                 # Carga de variables de entorno
│       ├── input/mcp/
│       │   ├── mcp-server.adapter.ts         # Servidor MCP (stdio + HTTP)
│       │   └── tools/                        # Definición de tools MCP
│       └── output/http/
│           └── http-client.adapter.ts        # Cliente HTTP al backend
├── Dockerfile                                # Build multi-stage para producción
├── Dockerfile.dev                            # Imagen de desarrollo
├── docker-compose.yml                        # Orquestación de producción
├── docker-compose.dev.yml                    # Orquestación de desarrollo
├── .env.example                              # Plantilla de variables
├── .env.dev / .env.prod                      # Variables por entorno (NO versionar)
└── package.json / tsconfig.json

Tools MCP disponibles

El servidor expone 11 tools que mapean 1:1 con los endpoints REST del backend:

Tool	Método	Endpoint Backend	Roles
auth_login	POST	/api/auth/login	Público
auth_register	POST	/api/auth/register	Público
auth_me	GET	/api/auth/me	Autenticado
persona_crear	POST	/api/personas	ADMIN, MANAGER
persona_obtener	GET	/api/personas/{id}	ADMIN, MANAGER, USER
persona_listar	GET	/api/personas?search&page&size&sortBy&direction	ADMIN, MANAGER, USER
persona_actualizar	PUT	/api/personas/{id}	ADMIN, MANAGER
persona_eliminar	DELETE	/api/personas/{id}	ADMIN
usuario_crear	POST	/api/usuarios	ADMIN
usuario_listar	GET	/api/usuarios?search&rol&page&size&sortBy&direction	ADMIN, MANAGER
usuario_obtener_por_email	GET	/api/usuarios/email/{email}	ADMIN, MANAGER

Flujo de autenticación

El MCP gestiona la sesión automáticamente:

1. El LLM invoca auth_login con email y contraseña
2. El MCP recibe el JWT y lo almacena internamente
3. Las tools subsecuentes (persona_*, usuario_*, auth_me) usan ese token sin que el LLM tenga que pasarlo
4. Si no hay sesión activa, las tools protegidas devuelven un error indicando que debe hacerse auth_login primero

Requisitos

• Docker instalado
• El backend HumanResourcesManagement-Backend corriendo (en la red gestion-network)
• Para desarrollo: clon local del backend con el entorno de desarrollo levantado

Variables de entorno

Variable	Descripción	Default
BACKEND_API_URL	URL base del backend Spring Boot	http://gestion-backend:8080
MCP_TRANSPORT	Modo de transporte: stdio (Claude Desktop) o http (remoto/testing)	stdio
MCP_HTTP_PORT	Puerto HTTP cuando MCP_TRANSPORT=http	3001

Copia .env.example a .env.dev o .env.prod y ajusta los valores según tu entorno.

Ejecución

Desarrollo

Levanta el contenedor de desarrollo con bind mount del código fuente:

cd HumanResourcesManagement-MCP
docker-compose --env-file .env.dev -f docker-compose.dev.yml up -d

El servidor se reinicia automáticamente al modificar archivos en src/. Los logs se ven con:

docker logs -f human-resources-mcp-dev

Para ejecutar typecheck o lint dentro del contenedor:

docker exec -it human-resources-mcp-dev sh

# Dentro del contenedor:
npm run typecheck
npm run build

Producción

Compila la imagen y levanta el servicio:

cd HumanResourcesManagement-MCP
docker-compose --env-file .env.prod up -d --build

La imagen de producción es multi-stage: compila TypeScript en una etapa y copia solo dist/ + dependencias de producción a una imagen node:22-alpine mínima. No incluye herramientas de desarrollo ni código fuente.

Para forzar recompilación sin caché:

docker-compose --env-file .env.prod build --no-cache
docker-compose --env-file .env.prod up -d

Validación desde la PC anfitriona

Una vez el contenedor está corriendo con MCP_TRANSPORT=http:

# Health check
curl http://localhost:3001/health
# {"status":"ok","transport":"http","sesionActiva":false}

# Inicializar sesión MCP
$init = @{jsonrpc="2.0"; id=1; method="initialize"; params=@{
  protocolVersion="2024-11-05"; capabilities=@{};
  clientInfo=@{name="test";version="1.0"}
}} | ConvertTo-Json -Depth 5 -Compress

$resp = Invoke-WebRequest -Uri http://localhost:3001/mcp `
  -Method Post -Body $init -ContentType "application/json" `
  -Headers @{"Accept"="application/json, text/event-stream"} -UseBasicParsing

$sessionId = $resp.Headers["Mcp-Session-Id"]

# Listar tools
$list = @{jsonrpc="2.0"; id=2; method="tools/list"; params=@{}} | ConvertTo-Json -Depth 5 -Compress

Invoke-WebRequest -Uri http://localhost:3001/mcp `
  -Method Post -Body $list -ContentType "application/json" `
  -Headers @{"Accept"="application/json, text/event-stream"; "Mcp-Session-Id"=$sessionId} -UseBasicParsing

# Llamar una tool (auth_login)
$call = @{jsonrpc="2.0"; id=3; method="tools/call"; params=@{
  name="auth_login"; arguments=@{email="admin@example.com"; password="SecurePass1!"}
}} | ConvertTo-Json -Depth 5 -Compress

Invoke-WebRequest -Uri http://localhost:3001/mcp `
  -Method Post -Body $call -ContentType "application/json" `
  -Headers @{"Accept"="application/json, text/event-stream"; "Mcp-Session-Id"=$sessionId} -UseBasicParsing

Integración con Claude Desktop

En claude_desktop_config.json:

{
  "mcpServers": {
    "human-resources": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "--network", "host",
        "-e", "BACKEND_API_URL=http://localhost:8080",
        "-e", "MCP_TRANSPORT=stdio",
        "human-resources-mcp:prod"
      ]
    }
  }
}

El transporte stdio permite que Claude Desktop se comunique directamente con el MCP sin exponer un puerto HTTP.

Nota: Compila la imagen de producción con docker-compose --env-file .env.prod build antes de usarla con Claude Desktop. Si el backend corre en otro host, ajusta BACKEND_API_URL.