Work Journal MCP-сервер

Размещенный MCP-сервер, который позволяет любому члену команды читать свой Simplified HR Work Journal через Claude — всегда свои собственные записи, а также записи коллег, если их существующие разрешения Work Journal это уже допускают.

Только чтение. Ни один инструмент здесь не может создать, изменить или удалить запись.

Подключение из любого клиента Claude

Единый порядок действий для любого клиента: добавьте сервер по URL, а затем войдите в открывшемся окне браузера.

Claude Desktop или claude.ai — Настройки → Коннекторы → Добавить пользовательский коннектор →

https://wj-mcp.dev.besimplified.net/mcp

Claude Code

claude mcp add work-journal --transport http https://wj-mcp.dev.besimplified.net/mcp

В любом случае откроется окно браузера. Войдите, используя электронную почту и пароль Simplified HR. В dev-среде также укажите ваш workspace, например development-hr.dev.besimplified.net.

Если это устройство ранее не встречалось в сервисе учетных записей, на вашу электронную почту или по SMS будет отправлен код подтверждения. Введите его один раз; в том же клиенте он больше не потребуется.

Ваш пароль никогда не передается в Claude, и этот сервер никогда его не хранит.

Инструменты

work_journal_get_entries

Записи с полной детализацией задач за дату или диапазон до 31 дня.

Спросите: «покажи мои записи EOD за прошлую неделю»

work_journal_get_day

Одна дата полностью: все задачи с примечаниями и вложениями, уведомленными получателями, ETA и временем отправки.

Спросите: «что я записал 4 августа?»

work_journal_get_summary

Количество по типам и статусам за любой период, без детализации по дням. Используйте это для периодов длиннее 31 дня.

Спросите: «сколько отчетов EOW я пропустил в этом году?»

work_journal_find_member

Находит коллегу по части имени или электронной почты и возвращает его id участника, для использования в качестве member в инструментах выше.

Спросите: «найди id участника Rahul»

work_journal_get_team_report

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

Спросите: «кто пропустил свой EOD на прошлой неделе?»

Псевдонимы типов

Сопоставление не учитывает регистр и считает пробелы, дефисы и подчеркивания эквивалентными.

Кто может видеть чей журнал

Этот сервер не применяет собственных разрешений. Каждый запрос несет вашу собственную сессию Simplified HR, и Work Journal API применяет ровно те же разрешения, что и в веб-интерфейсе:

• Разрешение инстанса — вы можете читать журнал любого участника вашей компании

• Разрешение группы — вы можете читать участников в вашем поддереве подчиненных

• Ни того, ни другого — вы можете читать только свой собственный журнал, и любая попытка прочитать чужой будет отклонена

Две вещи, которые нужно знать при чтении записей коллеги: запрос может быть отклонен напрямую, а представление администратора исключает черновики, запланированные и приватные записи. Поэтому отсутствие записи не доказывает, что ничего не было записано.

Ограничения

• work_journal_get_entries отклоняет диапазоны длиннее 31 дня и указывает вам на work_journal_get_summary

• Не более 4 запросов выполняются одновременно на один вызов инструмента, поэтому широкий диапазон остается щадящим для API

• Относительные даты, такие как «прошлая неделя», разрешаются Claude до вызова; инструменты принимают только YYYY-MM-DD

Локальный запуск

npm install
cp .env.example .env      # then fill in the two secrets
WJ_ENV=dev \
WJ_PUBLIC_BASE_URL=http://localhost:8080 \
WJ_TOKEN_KEY=$(openssl rand -hex 32) \
WJ_FINGERPRINT_SECRET=$(openssl rand -hex 32) \
npm start

GET /healthz должен отвечать {"status":"ok"}. При запуске node src/index.js без окружения процесс должен немедленно завершиться, перечислив все отсутствующие переменные.

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

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

Примечания по развертыванию

• Привязка cookie (stickiness) требуется только для /authorize. Отправка OTP должна достичь той задачи, которая начала вход, поскольку незавершенный вход хранится в памяти этого процесса в течение пяти минут. /mcp и /token не сохраняют состояние и не должны быть липкими.

• Оба секрета должны храниться в SSM Parameter Store как SecureString и быть указаны в блоке secrets определения задачи — никогда не как литералы окружения. Создайте их один раз для каждого окружения перед первым развертыванием; ничто другое в платформе не использует префикс /hr/work-journal-mcp/, поэтому их еще не существует:

  aws ssm put-parameter --type SecureString --name /hr/work-journal-mcp/<env>/token_key           --value "$(openssl rand -hex 32)"
  aws ssm put-parameter --type SecureString --name /hr/work-journal-mcp/<env>/fingerprint_secret  --value "$(openssl rand -hex 32)"

  Роль ecsTaskExecutionRole должна иметь разрешения ssm:GetParameters и kms:Decrypt для обоих секретов, иначе задача завершится ошибкой ResourceInitializationError при запуске, до выполнения любого из этого кода.

• Продакшн отклоняет поле входа workspace, которое требуется в dev, поэтому страница входа скрывает его вне dev.

Безопасность

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

• Состояние сессии передается в зашифрованном конверте AES-256-GCM, который может открыть только этот сервер. JWT Simplified HR никогда не попадает в Claude или модель.

• Конверты access, refresh и кода авторизации криптографически привязаны к своему типу, поэтому один не может быть использован как другой.

• Попытки входа ограничиваются по количеству на каждый адрес электронной почты.

• Каждый вызов инструмента логируется с указанием вызывающего, инструмента и участника, чей журнал был прочитан, что делает чтение чужих журналов аудируемым. Токены и содержимое записей никогда не логируются.

Тесты

npm test