HRMS Tool

Обзор

HRMS Tool — это сервер Model Context Protocol, который превращает набор основных HR-процессов — онбординг, офбординг, отслеживание отпусков, планирование встреч, IT-заявки и электронную почту — в инструменты, которые ИИ-агент может вызывать напрямую.

Вместо того чтобы кликать по HR-порталу, вы можете спросить у MCP-подключенного помощника что-то вроде:

"Зачислите Маркуса Уэбба как нового подчиненного Елены Кросс, начиная с понедельника." "У кого в команде Наоми Стил осталось мало отпусков?" "Закройте все открытые заявки Диего Рамоса и отмените его предстоящие встречи — он увольняется в пятницу."

Помощник планирует шаги, вызывает нужные инструменты в правильном порядке и сообщает результат — используя приведенные ниже руководящие подсказки для многошаговых рабочих процессов или отдельные инструменты для разовых действий.

Related MCP server: HRizzle-HR-Assist

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

• 👤 Управление сотрудниками — добавление, обновление, поиск и просмотр сотрудников; разрешение отношений руководитель/подчиненный

• 🌴 Управление отпусками — проверка остатков, подача заявок на отпуск, просмотр истории

• 📅 Планирование встреч — бронирование, список и отмена встреч с обнаружением конфликтов

• 🎫 Система заявок — создание запросов на оборудование/ресурсы, отслеживание статуса, фильтрация и просмотр заявок

• 📧 Электронная почта — отправка транзакционных писем через Gmail SMTP (обычный текст, HTML и вложения)

• 🧭 Руководящие подсказки — готовые многоинструментальные рабочие процессы для онбординга, офбординга и отчетов об отпусках команды

• 🌱 Предварительные демо-данные — запускается с реалистичной оргструктурой, историей отпусков, встречами и заявками, чтобы вы могли сразу попробовать

🏗️ Архитектура

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 не показан отдельно выше — это уровень моделей Pydantic, от которого зависят все менеджеры и все сигнатуры инструментов.

Все данные хранятся в памяти в течение всего времени работы процесса — базы данных нет. Каждый перезапуск повторно заполняет новый, рандомизированный набор данных (см. Данные и постоянство ниже).

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

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

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

• Python 3.14+

• uv для управления зависимостями (рекомендуется)

• Аккаунт Gmail с паролем приложения (App Password), если вы хотите, чтобы инструмент электронной почты работал (должна быть включена двухэтапная аутентификация)

🚀 Установка

# 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

Примечание: email_manager.py импортирует python-dotenv для загрузки .env, но он в настоящее время не указан в зависимостях pyproject.toml — добавьте его туда, если вы используете uv sync.

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

Для отправки электронной почты требуются учетные данные Gmail SMTP. Заполните файл .env в корне проекта следующим образом:

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

Сгенерируйте пароль приложения на myaccount.google.com/apppasswords (Безопасность → Двухэтапная аутентификация → Пароли приложений). Обычный пароль Gmail не подойдет.

▶️ Запуск сервера

uv run mcp-server/server.py

Это запускает MCP-сервер через stdio и заполняет его демо-сотрудниками, записями отпусков, встречами и заявками.

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

Добавьте запись в конфигурацию вашего MCP-клиента (например, claude_desktop_config.json):

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

Перезапустите клиент, и инструменты и подсказки, приведенные ниже, станут доступны в разговоре.

🛠️ Доступные инструменты

Сотрудники и оргструктура

Отпуска

Встречи

Заявки

Электронная почта

🧭 Доступные подсказки

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

💾 Данные и постоянство

• Все данные хранятся в памяти — ничего не сохраняется после перезапуска сервера.

• При каждом запуске seed_services() генерирует согласованный набор демо-данных: оргструктура из 8 человек в двух командах, рандомизированные остатки/история отпусков, 2–6 предстоящих встреч на сотрудника и 8–15 заявок в различных состояниях.

• Идентификаторы сотрудников имеют вид E001, E002, …; идентификаторы заявок — T0001, T0002, …

• Новые сотрудники по умолчанию имеют остаток отпуска 20 дней, если не указано иное.

• Если вам нужно, чтобы данные сохранялись между перезапусками, замените словари/списки в памяти в каждом классе менеджера на реальное хранилище данных.

⚠️ Известные ограничения

• Отсутствие аутентификации или авторизации при вызовах инструментов — контроль доступа полностью возлагается на MCP-клиент.

• Отсутствие уровня постоянства (см. выше).

• Отправка электронной почты только через Gmail, по SMTP + пароль приложения.

• Обнаружение конфликтов встреч проверяет только точное совпадение временных меток, а не пересекающиеся диапазоны.

📄 Лицензия

Этот проект лицензирован на условиях MIT License.