Leave Manager MCP Server

Пользовательский сервер Model Context Protocol (MCP), созданный на TypeScript для управления операциями, связанными с отпусками сотрудников, через таких ИИ-клиентов, как Claude Desktop.

Этот проект в настоящее время предназначен для внутренней разработки и тестирования и использует фиктивную/внутрипроцессную базу данных вместо производственной базы данных.

Архитектура спроектирована таким образом, чтобы фиктивную базу данных можно было позже заменить на реальную базу данных или внутренний API управления отпусками без изменения интерфейса инструментов MCP.

Оглавление

• Обзор

• Возможности

• Архитектура

• Технологический стек

• Предварительные требования

• Установка

• Структура проекта

• Конфигурация

• Доступные MCP-инструменты

• Запуск MCP-сервера

• Сборка проекта

• Запуск производственной сборки

• Тестирование с MCP Inspector

• Подключение к Claude Desktop

• Тестирование Leave Manager с Claude

• Фиктивная база данных

• Рабочий процесс разработки

• Устранение неполадок

• Будущие улучшения

• Вопросы производственной эксплуатации

• Лицензия

Обзор

Сервер Leave Manager MCP предоставляет функциональность управления отпусками в виде MCP-инструментов, которые могут использоваться ИИ-клиентами.

Например, вместо ручного вызова API пользователь может спросить у Claude:

Сколько у меня отпусков за свой счёт?

Claude может определить подходящий MCP-инструмент и вызвать:

get_leave_balance

MCP-сервер обрабатывает запрос и возвращает структурированную информацию, которую Claude может использовать для формирования ответа на естественном языке.

Пример

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

Возможности

Текущая версия предоставляет следующие MCP-инструменты:

• Получение остатка отпуска сотрудника

• Получение истории отпусков сотрудника

• Получение доступных типов отпусков

• Подача заявки на отпуск

• Отмена отпуска

• Проверка входных данных с помощью Zod

• Фиктивная/внутрипроцессная база данных

• Реализация на TypeScript

• Транспорт MCP на основе stdio

• Поддержка MCP Inspector

• Интеграция с Claude Desktop

Архитектура

Текущая архитектура:

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

Сервер использует stdio, потому что Claude Desktop может запустить MCP-сервер как локальный процесс и общаться с ним через стандартный ввод/вывод. MCP TypeScript SDK предоставляет serveStdio() для этого случая.

Технологический стек

Текущий MCP TypeScript SDK v2 — это стабильная линия SDK, использующая @modelcontextprotocol/server.

Предварительные требования

Перед началом убедитесь, что установлено следующее.

Node.js

Требуется Node.js 20 или новее.

Проверьте установленную версию:

node --version

Пример:

v22.9.0

Проверьте npm:

npm --version

Claude Desktop

Установите Claude Desktop на свой компьютер.

Claude Desktop будет выступать в роли MCP-клиента и запустит сервер Leave Manager MCP локально.

Установка

1. Клонируйте репозиторий

git clone <YOUR_REPOSITORY_URL>

Перейдите в проект:

cd leave-manager-mcp

2. Установите зависимости

Выполните:

npm install

Проект использует пакет MCP TypeScript server:

npm install @modelcontextprotocol/server

Zod используется для проверки входных данных инструментов:

npm install zod

Для разработки на TypeScript:

npm install -D typescript tsx @types/node

Официальная настройка MCP-сервера в настоящее время использует Node.js 20+, ES-модули, @modelcontextprotocol/server, Zod и tsx.

Структура проекта

Рекомендуемая структура проекта:

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

Обязанности

src/index.ts

Создаёт и запускает MCP-сервер.

src/models/leave.ts

Содержит TypeScript-модели/интерфейсы, связанные с сотрудниками и отпусками.

src/data/dummy-db.ts

Содержит временные тестовые данные в памяти.

src/repositories/leave-repository.ts

Предоставляет операции доступа к данным.

src/tools/leave-tools.ts

Регистрирует MCP-инструменты, которые может вызывать Claude.

Конфигурация

package.json

Типовая конфигурация:

{
  "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"
  }
}

Версии зависимостей могут отличаться в зависимости от того, когда выполняется npm install. Всегда предпочитайте версии, сгенерированные npm.

Конфигурация TypeScript

Создайте tsconfig.json:

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

Запись Node types важна для текущих версий TypeScript, поскольку опубликованные определения типов MCP SDK ссылаются на Node API.

Доступные MCP-инструменты

Текущий сервер Leave Manager MCP предоставляет следующие инструменты.

1. get_leave_balance

Возвращает текущий остаток отпуска сотрудника.

Входные данные

{
  "employeeId": "EMP001"
}

Пример результата

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

2. get_leave_history

Возвращает историю отпусков сотрудника.

Входные данные

{
  "employeeId": "EMP001"
}

Пример результата

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

3. get_leave_types

Возвращает доступные типы отпусков.

Пример результата

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

4. apply_leave

Создаёт новый запрос на отпуск.

Входные данные

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

Пример результата

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

5. cancel_leave

Отменяет существующий запрос на отпуск.

Входные данные

{
  "leaveId": "LR002"
}

Пример результата

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

Запуск MCP-сервера

Во время разработки есть два способа запустить сервер.

Вариант 1: Запуск напрямую с помощью tsx

Рекомендуется во время разработки.

npm run dev

Внутри это выполняет:

tsx src/index.ts

Вы должны увидеть:

Leave Manager MCP server running...

Процесс продолжит работу, потому что stdio MCP-сервер ожидает клиента для связи.

Остановите сервер с помощью:

Ctrl + C

Сборка проекта

Перед использованием скомпилированной версии выполните:

npm run build

Это выполняет:

tsc

Скомпилированные JavaScript-файлы будут созданы внутри:

dist/

Ожидаемая структура:

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

Запуск производственной сборки

После сборки:

npm start

Это выполняет:

node dist/index.js

MCP-сервер запустится с использованием скомпилированного JavaScript.

Тестирование с MCP Inspector

Перед подключением сервера к Claude Desktop рекомендуется протестировать его с помощью MCP Inspector.

MCP Inspector предоставляет локальный пользовательский интерфейс для подключения к MCP-серверу и непосредственного вызова его инструментов.

Запуск Inspector

Из корня проекта:

npx @modelcontextprotocol/inspector npm run dev

Альтернативно:

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

Inspector предоставит URL-адрес браузера.

Откройте этот URL-адрес в браузере.

Тестирование инструментов в MCP Inspector

После подключения сервера откройте раздел:

Tools

Вы должны увидеть:

get_leave_balance
get_leave_history
get_leave_types
apply_leave
cancel_leave

Тест get_leave_balance

Выберите:

get_leave_balance

Укажите:

{
  "employeeId": "EMP001"
}

Ожидаемый ответ:

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

Тест get_leave_history

Входные данные:

{
  "employeeId": "EMP001"
}

Тест get_leave_types

Этот инструмент не требует ввода данных.

Тест apply_leave

Входные данные:

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

Тест cancel_leave

Входные данные:

{
  "leaveId": "LR002"
}

Подключение к Claude Desktop

После того как сервер корректно работает в MCP Inspector, подключите его к Claude Desktop.

MCP-сервер следует настроить как локальный stdio-сервер, поскольку Claude Desktop запускает процесс и общается через stdin/stdout.

1. Соберите проект

Сначала выполните:

npm run build

Убедитесь, что этот файл существует:

dist/index.js

2. Получите абсолютный путь к проекту

Из корня проекта:

pwd

Пример:

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

Следовательно, путь к вашему серверу будет:

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

Используйте абсолютный путь в конфигурации Claude Desktop.

Конфигурация Claude Desktop

Добавьте MCP-сервер Leave Manager в конфигурацию MCP в Claude Desktop.

Пример:

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

Например, на macOS:

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

Замените путь на фактический абсолютный путь на вашем компьютере.

Важно: перезапустите Claude Desktop

После изменения конфигурации MCP:

1. Сохраните конфигурацию.

2. Полностью закройте Claude Desktop.

3. Снова запустите Claude Desktop.

4. Откройте новый чат.

5. Проверьте доступные MCP-инструменты.

Вы должны увидеть сервер Leave Manager и его инструменты.

Тестирование Leave Manager с Claude

После подключения вам не нужно вручную вызывать MCP-инструменты.

Вы можете просто задавать Claude вопросы на естественном языке.

Пример 1 — остаток отпуска

Спросите:

How many leaves does EMP001 have?

Claude должен использовать:

get_leave_balance

с:

{
  "employeeId": "EMP001"
}

Пример 2 — история отпусков

Спросите:

Show me the leave history of EMP001.

Claude должен использовать:

get_leave_history

Пример 3 — доступные типы отпусков

Спросите:

What types of leaves are available?

Claude должен использовать:

get_leave_types

Пример 4 — подача заявки на отпуск

Спросите:

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

Claude должен использовать:

apply_leave

с соответствующими параметрами.

Пример 5 — отмена отпуска

Спросите:

Cancel leave request LR002.

Claude должен использовать:

cancel_leave

Фиктивная база данных

Текущая реализация использует базу данных в памяти.

Пример:

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

Остаток отпуска:

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

Запросы на отпуск:

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"
  }
];

Важное ограничение фиктивной БД

Текущая база данных хранится в памяти приложения.

Поэтому:

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

Это ожидаемо.

Фиктивная база данных предназначена только для разработки и тестирования MCP.

Рабочий процесс разработки

Рекомендуемый рабочий процесс разработки:

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

Во время разработки вы также можете использовать:

npm run dev

вместо сборки после каждого изменения.

Ведение журнала

Поскольку сервер использует stdio, не используйте console.log() для обычного ведения журнала сервера.

Избегайте:

console.log("Server started");

Используйте:

console.error("Server started");

Причина в том, что stdout используется MCP для протокольного общения. Запись обычных журналов в stdout может повредить поток JSON-RPC/MCP.

Устранение неполадок

Проблема: Cannot find module

Выполните:

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

Затем:

npm run build

Проблема: ошибка сборки TypeScript

Выполните:

npx tsc --noEmit

Это покажет ошибки TypeScript без создания файлов.

Проблема: dist/index.js не существует

Выполните:

npm run build

Затем проверьте:

ls dist

Проблема: Claude Desktop не показывает MCP-сервер

Проверьте:

1. Конфигурация MCP является допустимым JSON.

2. Путь к dist/index.js является абсолютным.

3. npm run build завершился успешно.

4. dist/index.js существует.

5. Node.js установлен.

6. Claude Desktop был полностью перезапущен.

7. MCP-сервер работает в MCP Inspector.

Проблема: MCP Inspector не может подключиться

Сначала выполните:

npm run dev

Если сервер запускается успешно, остановите его, а затем выполните:

npx @modelcontextprotocol/inspector npm run dev

Проверьте терминал на наличие ошибок.

Проблема: сервер запускается, но инструменты не видны

Проверьте:

src/index.ts

и убедитесь, что ваши инструменты зарегистрированы:

registerLeaveTools(
  server,
  repository
);

Также убедитесь, что вызывается serveStdio():

void serveStdio(createServer);

Проблема: ошибки протокола JSON-RPC/MCP

Проверьте код на наличие:

console.log(...)

Замените обычное ведение журнала на:

console.error(...)

stdout должен оставаться доступным для связи по протоколу MCP.

Будущие улучшения

Текущая версия — это прототип. Рекомендуются следующие улучшения.

База данных

Замените фиктивную базу данных на:

PostgreSQL
MySQL
MongoDB

или существующий внутренний API управления отпусками.

Аутентификация

Добавьте аутентификацию сотрудников, чтобы пользователю не приходилось вводить:

employeeId

вручную.

Будущая архитектура:

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

Проверка отпусков

Добавьте бизнес-правила:

• Проверка дат отпуска

• Проверка остатка отпуска

• Предотвращение пересекающихся отпусков

• Проверка корпоративных праздников

• Проверка выходных

• Проверка минимальной/максимальной продолжительности отпуска

• Проверка статуса сотрудника

• Проверка типа отпуска

• Запрет отмены после утверждения, если применимо

Утверждение руководителем

Добавьте такие инструменты, как:

get_pending_leave_requests
approve_leave
reject_leave

Командный календарь

Добавьте:

get_team_leave_calendar

Пример запроса пользователя:

Who from my team is on leave next week?

Уведомления

Интегрируйтесь с:

Email
Slack
Microsoft Teams

для уведомления сотрудников и руководителей.

Рекомендуемая производственная архитектура

Долгосрочная архитектура должна отделять MCP от бизнес-логики:

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

Это позволит заменить фиктивную базу данных без изменения инструментов, доступных Claude.

Вопросы безопасности

Текущий проект предназначен только для разработки/тестирования.

Перед использованием с реальными данными сотрудников:

• Добавьте аутентификацию.

• Добавьте авторизацию.

• Не доверяйте employeeId, предоставленному моделью.

• Проверяйте все входные данные инструментов.

• Защищайте информацию о сотрудниках.

• Избегайте раскрытия ненужных данных о сотрудниках.

• Добавьте журналирование аудита.

• Реализуйте управление доступом на основе ролей.

• Защищайте операции, доступные только менеджерам.

• Добавьте ограничение частоты запросов, где это применимо.

• Не храните секреты в исходном коде.

• Используйте переменные окружения для учётных данных.

• Обеспечьте безопасность соединений с внутренними API/базами данных.

MCP-сервер должен обеспечивать соблюдение бизнес-разрешений, а не полагаться на Claude при принятии решений по безопасности.

Переменные окружения

При подключении к реальным сервисам используйте переменные окружения.

Пример .env:

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

Не коммитьте .env в Git.

Добавьте:

.env

в .gitignore.

Git Ignore

Рекомендуемый .gitignore:

node_modules/
dist/
.env
.DS_Store
*.log

Полезные команды

Установка зависимостей

npm install

Разработка

npm run dev

Сборка

npm run build

Запуск скомпилированного сервера

npm start

Проверка типов

npx tsc --noEmit

Запуск MCP Inspector

npx @modelcontextprotocol/inspector npm run dev

Проверка версии Node.js

node --version

Проверка версии npm

npm --version

Контрольный список разработки MCP

Прежде чем считать MCP-сервер готовым к внутреннему тестированию:

• Установлен Node.js 20+

• Установлены зависимости

• Сборка TypeScript проходит успешно

• Настроена тестовая база данных

• MCP-сервер запускается успешно

• MCP Inspector подключается успешно

• get_leave_balance протестирован

• get_leave_history протестирован

• get_leave_types протестирован

• apply_leave протестирован

• cancel_leave протестирован

• Добавлена конфигурация Claude Desktop

• Claude Desktop перезапущен

• Инструменты Leave Manager видны в Claude

• Протестированы запросы на естественном языке

• Протестированы сценарии ошибок

Примеры пользовательских запросов

После подключения к Claude Desktop пользователи смогут задавать такие вопросы, как:

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.

Будущие примеры:

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.

Ресурсы MCP

Официальный MCP TypeScript SDK:

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

Официальное руководство по первому серверу:

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

Официальный API сервера:

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

Проект в настоящее время следует архитектуре MCP TypeScript SDK v2 и современной линии протокола 2026-07-28.

Лицензия

Этот проект предназначен для внутренней разработки и тестирования.

Добавьте сюда лицензию и политику использования вашей организации.

Сопровождающий

Ashish Kushwaha

Leave Manager MCP Server TypeScript + MCP + Claude Desktop

Быстрый старт

Для опытных разработчиков полную настройку можно кратко описать так:

# 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

Затем настройте Claude Desktop для запуска:

dist/index.js

используя:

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

Перезапустите Claude Desktop и начните тестировать инструменты Leave Manager MCP.