Leave Manager MCP Server

Un servidor de Model Context Protocol (MCP) personalizado construido con TypeScript para gestionar operaciones relacionadas con permisos de empleados a través de clientes de IA como Claude Desktop.

Este proyecto está actualmente diseñado para desarrollo y pruebas internas y utiliza una base de datos ficticia/en memoria en lugar de una base de datos de producción.

La arquitectura está diseñada para que la base de datos ficticia pueda reemplazarse posteriormente por una base de datos real o una API interna de gestión de permisos sin cambiar la interfaz de herramientas MCP.

Índice de contenidos

• Descripción general

• Características

• Arquitectura

• Pila tecnológica

• Requisitos previos

• Instalación

• Estructura del proyecto

• Configuración

• Herramientas MCP disponibles

• Ejecutar el servidor MCP

• Compilar el proyecto

• Ejecutar la compilación de producción

• Probar con MCP Inspector

• Conectar con Claude Desktop

• Probar Leave Manager con Claude

• Base de datos ficticia

• Flujo de trabajo de desarrollo

• Solución de problemas

• Mejoras futuras

• Consideraciones de producción

• Licencia

Descripción general

El servidor MCP de Leave Manager expone funcionalidades de gestión de permisos como herramientas MCP que pueden ser utilizadas por clientes de IA.

Por ejemplo, en lugar de llamar manualmente a una API, un usuario puede preguntar a Claude:

¿Cuántos permisos ocasionales tengo?

Claude puede identificar la herramienta MCP adecuada e invocar:

get_leave_balance

El servidor MCP procesa la solicitud y devuelve información estructurada que Claude puede utilizar para generar una respuesta en lenguaje natural.

Ejemplo

User
 │
 │ "How many leaves do I have?"
 ▼
Claude Desktop
 │
 │ MCP Tool Call
 ▼
Leave Manager MCP Server
 │
 ▼
Dummy Database
 │
 ▼
Leave Balance
 │
 ▼
Claude Desktop
 │
 ▼
Natural Language Response

Características

La versión actual proporciona las siguientes herramientas MCP:

• Obtener el saldo de permisos de un empleado

• Obtener el historial de permisos de un empleado

• Obtener los tipos de permisos disponibles

• Solicitar un permiso

• Cancelar un permiso

• Validación de entrada mediante Zod

• Base de datos ficticia/en memoria

• Implementación en TypeScript

• Transporte MCP basado en stdio

• Compatibilidad con MCP Inspector

• Integración con Claude Desktop

Arquitectura

La arquitectura actual es:

                    ┌──────────────────────┐
                    │    Claude Desktop    │
                    │                      │
                    │   User Interaction   │
                    └──────────┬───────────┘
                               │
                               │ MCP / stdio
                               ▼
                    ┌──────────────────────┐
                    │ Leave Manager MCP    │
                    │      Server          │
                    │                      │
                    │ MCP Tool Layer       │
                    └──────────┬───────────┘
                               │
                               ▼
                    ┌──────────────────────┐
                    │    Leave Service     │
                    │    / Repository      │
                    └──────────┬───────────┘
                               │
                               ▼
                    ┌──────────────────────┐
                    │     Dummy DB         │
                    │                      │
                    │ employees[]          │
                    │ leaveBalances[]      │
                    │ leaveRequests[]      │
                    └──────────────────────┘

El servidor utiliza stdio porque Claude Desktop puede iniciar el servidor MCP como un proceso local y comunicarse con él a través de la entrada/salida estándar. El SDK de TypeScript de MCP proporciona serveStdio() para este caso de uso.

Pila tecnológica

El SDK actual de MCP TypeScript v2 es la línea estable del SDK y utiliza @modelcontextprotocol/server.

Requisitos previos

Antes de comenzar, asegúrate de tener instalado lo siguiente.

Node.js

Se requiere Node.js 20 o posterior.

Comprueba la versión instalada:

node --version

Ejemplo:

v22.9.0

Comprueba npm:

npm --version

Claude Desktop

Instala Claude Desktop en tu máquina.

Claude Desktop actuará como cliente MCP e iniciará el servidor MCP de Leave Manager localmente.

Instalación

1. Clonar el repositorio

git clone <YOUR_REPOSITORY_URL>

Navega al proyecto:

cd leave-manager-mcp

2. Instalar dependencias

Ejecuta:

npm install

El proyecto utiliza el paquete de servidor MCP TypeScript:

npm install @modelcontextprotocol/server

Zod se utiliza para validar la entrada de las herramientas:

npm install zod

Para el desarrollo con TypeScript:

npm install -D typescript tsx @types/node

La configuración oficial del servidor MCP utiliza actualmente Node.js 20+, módulos ES, @modelcontextprotocol/server, Zod y tsx.

Estructura del proyecto

Estructura recomendada del proyecto:

leave-manager-mcp/
│
├── src/
│   │
│   ├── index.ts
│   │
│   ├── data/
│   │   └── dummy-db.ts
│   │
│   ├── models/
│   │   └── leave.ts
│   │
│   ├── repositories/
│   │   └── leave-repository.ts
│   │
│   └── tools/
│       └── leave-tools.ts
│
├── dist/
│
├── package.json
├── package-lock.json
├── tsconfig.json
└── README.md

Responsabilidades

src/index.ts

Crea e inicia el servidor MCP.

src/models/leave.ts

Contiene modelos/interfaces de TypeScript relacionados con empleados y permisos.

src/data/dummy-db.ts

Contiene datos de prueba temporales en memoria.

src/repositories/leave-repository.ts

Proporciona operaciones de acceso a datos.

src/tools/leave-tools.ts

Registra las herramientas MCP que Claude puede invocar.

Configuración

package.json

Una configuración típica:

{
  "name": "leave-manager-mcp",
  "version": "1.0.0",
  "description": "Leave Manager MCP Server",
  "type": "module",
  "scripts": {
    "dev": "tsx src/index.ts",
    "build": "tsc",
    "start": "node dist/index.js"
  },
  "dependencies": {
    "@modelcontextprotocol/server": "^2.0.0",
    "zod": "^4.0.0"
  },
  "devDependencies": {
    "@types/node": "^24.0.0",
    "tsx": "^4.0.0",
    "typescript": "^6.0.0"
  }
}

Las versiones de las dependencias pueden variar según el momento en que se ejecute npm install. Siempre se deben preferir las versiones generadas por npm.

Configuración de TypeScript

Crea tsconfig.json:

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "types": ["node"],
    "outDir": "dist"
  },
  "include": [
    "src/**/*.ts"
  ]
}

La entrada de tipos de Node es importante con las versiones actuales de TypeScript porque las definiciones de tipos publicadas del SDK de MCP hacen referencia a las API de Node.

Herramientas MCP disponibles

El servidor MCP de Leave Manager actual expone las siguientes herramientas.

1. get_leave_balance

Devuelve el saldo de permisos actual de un empleado.

Entrada

{
  "employeeId": "EMP001"
}

Ejemplo de resultado

{
  "employeeId": "EMP001",
  "casual": 8,
  "sick": 5,
  "earned": 12,
  "unpaid": 0
}

2. get_leave_history

Devuelve el historial de permisos de un empleado.

Entrada

{
  "employeeId": "EMP001"
}

Ejemplo de resultado

[
  {
    "id": "LR001",
    "employeeId": "EMP001",
    "leaveType": "CASUAL",
    "startDate": "2026-08-20",
    "endDate": "2026-08-21",
    "reason": "Personal work",
    "status": "APPROVED"
  }
]

3. get_leave_types

Devuelve los tipos de permisos disponibles.

Ejemplo de resultado

[
  {
    "type": "CASUAL",
    "description": "Casual leave"
  },
  {
    "type": "SICK",
    "description": "Sick leave"
  },
  {
    "type": "EARNED",
    "description": "Earned leave"
  },
  {
    "type": "UNPAID",
    "description": "Unpaid leave"
  }
]

4. apply_leave

Crea una nueva solicitud de permiso.

Entrada

{
  "employeeId": "EMP001",
  "leaveType": "CASUAL",
  "startDate": "2026-09-10",
  "endDate": "2026-09-11",
  "reason": "Family function"
}

Ejemplo de resultado

{
  "id": "LR002",
  "employeeId": "EMP001",
  "leaveType": "CASUAL",
  "startDate": "2026-09-10",
  "endDate": "2026-09-11",
  "reason": "Family function",
  "status": "PENDING"
}

5. cancel_leave

Cancela una solicitud de permiso existente.

Entrada

{
  "leaveId": "LR002"
}

Ejemplo de resultado

{
  "id": "LR002",
  "status": "CANCELLED"
}

Ejecutar el servidor MCP

Hay dos formas de ejecutar el servidor durante el desarrollo.

Opción 1: Ejecutar directamente con tsx

Esto se recomienda durante el desarrollo.

npm run dev

Internamente esto ejecuta:

tsx src/index.ts

Deberías ver:

Leave Manager MCP server running...

El proceso seguirá ejecutándose porque un servidor MCP stdio espera a que un cliente se comunique con él.

Detén el servidor con:

Ctrl + C

Compilar el proyecto

Antes de utilizar la versión compilada, ejecuta:

npm run build

Esto ejecuta:

tsc

Los archivos JavaScript compilados se generarán dentro de:

dist/

Estructura esperada:

dist/
├── index.js
├── data/
│   └── dummy-db.js
├── models/
│   └── leave.js
├── repositories/
│   └── leave-repository.js
└── tools/
    └── leave-tools.js

Ejecutar la compilación de producción

Después de compilar:

npm start

Esto ejecuta:

node dist/index.js

El servidor MCP se iniciará utilizando el JavaScript compilado.

Probar con MCP Inspector

Antes de conectar el servidor a Claude Desktop, se recomienda probarlo con MCP Inspector.

MCP Inspector proporciona una interfaz de usuario local para conectarse a un servidor MCP e invocar directamente sus herramientas.

Iniciar Inspector

Desde la raíz del proyecto:

npx @modelcontextprotocol/inspector npm run dev

Alternativamente:

npx @modelcontextprotocol/inspector npx tsx src/index.ts

Inspector proporcionará una URL de navegador.

Abre esa URL en tu navegador.

Probar herramientas en MCP Inspector

Después de conectar el servidor, abre la sección:

Tools

Deberías ver:

get_leave_balance
get_leave_history
get_leave_types
apply_leave
cancel_leave

Probar get_leave_balance

Selecciona:

get_leave_balance

Proporciona:

{
  "employeeId": "EMP001"
}

Respuesta esperada:

{
  "employeeId": "EMP001",
  "casual": 8,
  "sick": 5,
  "earned": 12,
  "unpaid": 0
}

Probar get_leave_history

Entrada:

{
  "employeeId": "EMP001"
}

Probar get_leave_types

Esta herramienta no requiere ninguna entrada.

Probar apply_leave

Entrada:

{
  "employeeId": "EMP001",
  "leaveType": "CASUAL",
  "startDate": "2026-09-10",
  "endDate": "2026-09-11",
  "reason": "Family function"
}

Probar cancel_leave

Entrada:

{
  "leaveId": "LR002"
}

Conectar con Claude Desktop

Una vez que el servidor funcione correctamente en MCP Inspector, conéctalo a Claude Desktop.

El servidor MCP debe configurarse como un servidor stdio local porque Claude Desktop inicia el proceso y se comunica a través de stdin/stdout.

1. Compilar el proyecto

Primero ejecuta:

npm run build

Asegúrate de que este archivo exista:

dist/index.js

2. Obtener la ruta absoluta del proyecto

Desde la raíz del proyecto:

pwd

Ejemplo:

/Users/ashish/projects/leave-manager-mcp

Por lo tanto, la ruta de tu servidor será:

/Users/ashish/projects/leave-manager-mcp/dist/index.js

Utiliza una ruta absoluta en la configuración de Claude Desktop.

Configuración de Claude Desktop

Añade el servidor MCP de Leave Manager a la configuración MCP de Claude Desktop.

Ejemplo:

{
  "mcpServers": {
    "leave-manager": {
      "command": "node",
      "args": [
        "/ABSOLUTE/PATH/TO/leave-manager-mcp/dist/index.js"
      ]
    }
  }
}

Por ejemplo, en macOS:

{
  "mcpServers": {
    "leave-manager": {
      "command": "node",
      "args": [
        "/Users/ashish/projects/leave-manager-mcp/dist/index.js"
      ]
    }
  }
}

Reemplaza la ruta con la ruta absoluta real de tu máquina.

Importante: Reiniciar Claude Desktop

Después de cambiar la configuración MCP:

1. Guarda la configuración.

2. Cierra completamente Claude Desktop.

3. Inicia Claude Desktop de nuevo.

4. Abre una nueva conversación.

5. Comprueba las herramientas MCP disponibles.

Deberías ver el servidor Leave Manager y sus herramientas.

Probar Leave Manager con Claude

Una vez conectado, no necesitas invocar manualmente las herramientas MCP.

Puedes simplemente hacer preguntas en lenguaje natural a Claude.

Ejemplo 1 — Saldo de permisos

Pregunta:

How many leaves does EMP001 have?

Claude debería utilizar:

get_leave_balance

con:

{
  "employeeId": "EMP001"
}

Ejemplo 2 — Historial de permisos

Pregunta:

Show me the leave history of EMP001.

Claude debería utilizar:

get_leave_history

Ejemplo 3 — Tipos de permisos disponibles

Pregunta:

What types of leaves are available?

Claude debería utilizar:

get_leave_types

Ejemplo 4 — Solicitar un permiso

Pregunta:

Apply casual leave for EMP001 from September 10 to September 11 because of a family function.

Claude debería utilizar:

apply_leave

con los parámetros adecuados.

Ejemplo 5 — Cancelar un permiso

Pregunta:

Cancel leave request LR002.

Claude debería utilizar:

cancel_leave

Base de datos ficticia

La implementación actual utiliza una base de datos en memoria.

Ejemplo:

export const employees = [
  {
    id: "EMP001",
    name: "Ashish Kushwaha",
    email: "ashish@example.com",
    department: "Engineering"
  }
];

Saldo de permisos:

export const leaveBalances = [
  {
    employeeId: "EMP001",
    casual: 8,
    sick: 5,
    earned: 12,
    unpaid: 0
  }
];

Solicitudes de permiso:

export const leaveRequests = [
  {
    id: "LR001",
    employeeId: "EMP001",
    leaveType: "CASUAL",
    startDate: "2026-08-20",
    endDate: "2026-08-21",
    reason: "Personal work",
    status: "APPROVED",
    createdAt: "2026-08-10"
  }
];

Limitación importante de la base de datos ficticia

La base de datos actual se almacena en la memoria de la aplicación.

Por lo tanto:

Server starts
      ↓
Dummy data loaded
      ↓
Apply leave
      ↓
New request added
      ↓
Server stops
      ↓
Data is lost

Esto es esperado.

La base de datos ficticia está destinada únicamente al desarrollo y a las pruebas MCP.

Flujo de trabajo de desarrollo

Flujo de trabajo de desarrollo recomendado:

1. Modify TypeScript
        ↓
2. Run npm run build
        ↓
3. Run MCP Inspector
        ↓
4. Test MCP tools
        ↓
5. Fix issues
        ↓
6. Test with Claude Desktop
        ↓
7. Commit changes

Durante el desarrollo también puedes utilizar:

npm run dev

en lugar de compilar después de cada cambio.

Registro de logs

Debido a que el servidor utiliza stdio, no utilices console.log() para el registro normal del servidor.

Evita:

console.log("Server started");

Utiliza:

console.error("Server started");

La razón es que stdout se utiliza para la comunicación del protocolo MCP. Escribir logs normales en stdout puede corromper el flujo de comunicación JSON-RPC/MCP.

Solución de problemas

Problema: Cannot find module

Ejecuta:

rm -rf node_modules
rm -f package-lock.json
npm install

Después:

npm run build

Problema: Error de compilación de TypeScript

Ejecuta:

npx tsc --noEmit

Esto mostrará los errores de TypeScript sin generar archivos.

Problema: dist/index.js no existe

Ejecuta:

npm run build

Después verifica:

ls dist

Problema: Claude Desktop no muestra el servidor MCP

Comprueba:

1. Que la configuración MCP sea JSON válido.

2. Que la ruta a dist/index.js sea absoluta.

3. Que npm run build se haya completado correctamente.

4. Que dist/index.js exista.

5. Que Node.js esté instalado.

6. Que Claude Desktop se haya reiniciado por completo.

7. Que el servidor MCP funcione en MCP Inspector.

Problema: MCP Inspector no puede conectarse

Primero ejecuta:

npm run dev

Si el servidor se inicia correctamente, detenlo y después ejecuta:

npx @modelcontextprotocol/inspector npm run dev

Revisa la terminal para ver los errores.

Problema: El servidor se inicia pero las herramientas no son visibles

Comprueba:

src/index.ts

y asegúrate de que tus herramientas estén registradas:

registerLeaveTools(
  server,
  repository
);

También asegúrate de que se llame a serveStdio():

void serveStdio(createServer);

Problema: Errores de protocolo JSON-RPC/MCP

Revisa el código en busca de:

console.log(...)

Reemplaza el registro normal con:

console.error(...)

stdout debe permanecer disponible para la comunicación del protocolo MCP.

Mejoras futuras

La versión actual es un prototipo. Se recomiendan las siguientes mejoras.

Base de datos

Reemplaza la base de datos ficticia con:

PostgreSQL
MySQL
MongoDB

o una API interna existente de gestión de permisos.

Autenticación

Añade autenticación de empleados para que el usuario no tenga que proporcionar:

employeeId

manualmente.

Arquitectura futura:

Claude
   ↓
MCP Server
   ↓
Authentication
   ↓
Employee Context
   ↓
Leave Service

Validación de permisos

Añade reglas de negocio:

• Validar fechas de permiso

• Validar saldo de permisos

• Evitar solapamiento de permisos

• Comprobar días festivos de la empresa

• Comprobar fines de semana

• Validar duración mínima/máxima del permiso

• Validar el estado del empleado

• Validar el tipo de permiso

• Evitar la cancelación después de la aprobación, si corresponde

Aprobación del responsable

Añade herramientas como:

get_pending_leave_requests
approve_leave
reject_leave

Calendario del equipo

Añade:

get_team_leave_calendar

Ejemplo de solicitud de usuario:

Who from my team is on leave next week?

Notificaciones

Integra con:

Email
Slack
Microsoft Teams

para notificar a empleados y responsables.

Arquitectura de producción recomendada

La arquitectura a largo plazo debe separar MCP de la lógica de negocio:

                    Claude Desktop
                          │
                          │ MCP
                          ▼
                ┌───────────────────┐
                │    MCP Server     │
                │                   │
                │ Tool Definitions  │
                │ Input Validation  │
                └─────────┬─────────┘
                          │
                          ▼
                ┌───────────────────┐
                │   Leave Service   │
                │                   │
                │ Business Rules    │
                │ Validation        │
                │ Authorization     │
                └─────────┬─────────┘
                          │
                          ▼
                ┌───────────────────┐
                │ Leave Repository  │
                └─────────┬─────────┘
                          │
                 ┌────────┴────────┐
                 ▼                 ▼
          Internal Leave API    Database

Esto permite reemplazar la base de datos ficticia sin cambiar las herramientas expuestas a Claude.

Consideraciones de seguridad

El proyecto actual está destinado únicamente a desarrollo/pruebas.

Antes de utilizarlo con datos reales de empleados:

• Añadir autenticación.

• Añadir autorización.

• No confiar en el employeeId proporcionado por el modelo.

• Validar todas las entradas de las herramientas.

• Proteger la información de los empleados.

• Evitar exponer datos innecesarios de los empleados.

• Añadir registro de auditoría.

• Implementar control de acceso basado en roles.

• Proteger las operaciones exclusivas de los gerentes.

• Añadir limitación de frecuencia cuando corresponda.

• No almacenar secretos en el código fuente.

• Usar variables de entorno para las credenciales.

• Asegurar las conexiones a APIs/bases de datos internas.

El servidor MCP debe aplicar los permisos de negocio en lugar de depender de Claude para tomar decisiones de seguridad.

Variables de entorno

Al conectarse a servicios reales, use variables de entorno.

Ejemplo de .env:

LEAVE_API_URL=https://internal.example.com/api
LEAVE_API_KEY=your-api-key

No haga commit de .env en Git.

Añada:

.env

a .gitignore.

Ignorar con Git

.gitignore recomendado:

node_modules/
dist/
.env
.DS_Store
*.log

Comandos útiles

Instalar dependencias

npm install

Desarrollo

npm run dev

Compilar

npm run build

Ejecutar el servidor compilado

npm start

Comprobación de tipos

npx tsc --noEmit

Ejecutar MCP Inspector

npx @modelcontextprotocol/inspector npm run dev

Comprobar la versión de Node

node --version

Comprobar la versión de npm

npm --version

Lista de comprobación de desarrollo de MCP

Antes de considerar que el servidor MCP está listo para las pruebas internas:

• Node.js 20+ instalado

• Dependencias instaladas

• La compilación de TypeScript se realiza correctamente

• Base de datos de prueba configurada

• El servidor MCP se inicia correctamente

• MCP Inspector se conecta correctamente

• get_leave_balance probado

• get_leave_history probado

• get_leave_types probado

• apply_leave probado

• cancel_leave probado

• Configuración de Claude Desktop añadida

• Claude Desktop reiniciado

• Herramientas de Leave Manager visibles en Claude

• Solicitudes en lenguaje natural probadas

• Escenarios de error probados

Ejemplos de consultas de usuario

Una vez conectados a Claude Desktop, los usuarios deberían poder hacer preguntas como:

How many casual leaves do I have?

Show my leave history.

What leave types are available?

Apply casual leave from September 10 to September 11.

Cancel my leave request LR002.

Ejemplos futuros:

Do I have enough leave for next Monday?

Who from my team is on leave next week?

Show all pending leave requests.

Approve Rahul's leave request.

Recursos de MCP

SDK oficial de MCP para TypeScript:

https://ts.sdk.modelcontextprotocol.io/v2/

Guía oficial del primer servidor:

https://ts.sdk.modelcontextprotocol.io/v2/get-started/first-server

API oficial del servidor:

https://ts.sdk.modelcontextprotocol.io/v2/api/@modelcontextprotocol/server/

El proyecto sigue actualmente la arquitectura del SDK de MCP para TypeScript v2 y la línea de protocolo moderna 2026-07-28.

Licencia

Este proyecto está destinado al desarrollo y las pruebas internas.

Añada aquí la licencia y la política de uso de su organización.

Mantenedor

Ashish Kushwaha

Leave Manager MCP Server TypeScript + MCP + Claude Desktop

Inicio rápido

Para desarrolladores experimentados, la configuración completa se puede resumir como:

# Clone
git clone <YOUR_REPOSITORY_URL>

# Enter project
cd leave-manager-mcp

# Install
npm install

# Build
npm run build

# Run
npm start

# Development
npm run dev

# MCP Inspector
npx @modelcontextprotocol/inspector npm run dev

A continuación, configure Claude Desktop para que se inicie:

dist/index.js

usando:

{
  "mcpServers": {
    "leave-manager": {
      "command": "node",
      "args": [
        "/ABSOLUTE/PATH/TO/leave-manager-mcp/dist/index.js"
      ]
    }
  }
}

Reinicie Claude Desktop y comience a probar las herramientas MCP de Leave Manager.