tempo-mcp

MCP-сервер для Tempo Capacity Planner на Jira Data Center. Позволяет менеджеру планировать нагрузку сотрудников (аллокации) прямо из чата: смотреть/создавать/менять/удалять плановую нагрузку и выполнять составные операции (врезка отпуска, split) одной командой.

Полное ТЗ — ТЗ-tempo-mcp.md. Результаты разведки API стенда — phase0-проверка-записи.md.

Возможности (v1.0) — 23 tool

Чтение / навигация

• tempo_whoami, tempo_user_resolve, tempo_project_resolve — identity и резолв сущностей.
• tempo_allocation_search, tempo_allocation_get — чтение плановой нагрузки.
• tempo_capacity_get — ёмкость сотрудника за период vs аллокации (свободно/переаллокация, utilization%), считается из его workload scheme.
• tempo_team_list, tempo_team_members — команды и участники.
• tempo_capacity_team — загрузка каждого участника команды за период.
• tempo_capacity_find_available — кто свободен на нужный объём (staffing-запрос).
• tempo_report_utilization — сводка загрузки команды (средняя/командная утилизация, переаллокации, недозагрузка).
• tempo_report_gaps — кто в команде не запланирован за период.

Запись (все — под confirm + dry-run)

• tempo_allocation_create / update / delete — базовое CRUD.
• tempo_allocation_insert_absence — врезать отпуск в нагрузку (главный кейс): укорачивает/разбивает пересекающиеся аллокации, сохраняя часы и описание-«вероятность».
• tempo_allocation_split — разбить аллокацию по дате.
• tempo_allocation_shift — сдвинуть на N дней / к новой дате (сохранив длительность).
• tempo_allocation_resize — изменить часы/день или дату окончания.
• tempo_allocation_set_probability — обновить «вероятность» (в описании, не теряя текст).
• tempo_allocation_move_to_project — перенести нагрузку на другой проект.
• tempo_allocation_copy_to — скопировать нагрузку на другого сотрудника.
• tempo_allocation_bulk_plan — поставить нагрузку на проект сразу команде/списку сотрудников.

Ресурс tempo://config.

Prompts (готовые сценарии): insert_vacation, plan_employee, team_load_overview, bulk_plan_sprint.

Составные операции (insert_absence, split) защищены от гонки: dry-run возвращает expect-снимок, на confirm сервер сверяет состояние и при стороннем изменении отдаёт CONFLICT. Workload-схемы кэшируются (TTL TEMPO_MCP_CACHE_TTL_S).

«Вероятность» нагрузки хранится в поле description (конвенция percent/label, см. TEMPO_MCP_PROBABILITY_PATTERN).

Быстрый старт (без клонирования)

Нужен только Node.js (LTS ≥ 18). Сервер запускается из npm через npx:

# проверить токен и доступность эндпоинтов
JIRA_BASE_URL=https://jira.company.com JIRA_PAT=xxxx npx -y @redcollar/tempo-mcp doctor

Подключение в MCP-хост

Вставьте в конфиг клиента (Claude Desktop claude_desktop_config.json, Cursor ~/.cursor/mcp.json или .mcp.json):

{
  "mcpServers": {
    "tempo": {
      "command": "npx",
      "args": ["-y", "@redcollar/tempo-mcp"],
      "env": {
        "JIRA_BASE_URL": "https://jira.company.com",
        "JIRA_PAT": "<ваш персональный PAT>",
        "TEMPO_MCP_TZ": "Europe/Moscow"
      }
    }
  }
}

Транспорт — stdio, identity — персональный Jira PAT каждого пользователя. Переменные окружения — см. .env.example.

CLI

| Команда | Что делает | |---|---| | npx -y @redcollar/tempo-mcp | Запуск MCP-сервера на stdio (так его запускают клиенты) | | npx -y @redcollar/tempo-mcp doctor | Проверка конфига, PAT и доступности эндпоинтов | | npx -y @redcollar/tempo-mcp help | Справка |

Локальная разработка

npm install
npm run build
npm test
npm run doctor

Тесты

npm test

Архитектура

src/
  index.ts                 stdio bootstrap + INIT
  config.ts                env → конфиг (без секретов наружу)
  lib/{logger,errors,dates}.ts
  domain/
    models.ts              нормализованные сущности
    probability.ts         «вероятность» ↔ description
    allocation-engine.ts   составные операции (split / insert_absence) — чистое ядро
  integration/
    http.ts                fetch + Bearer PAT + retry/timeout
    jira.client.ts         /rest/api/2 (myself, resolve)
    planner.client.ts      /rest/tempo-planning/1/allocation (CRUD)
  mcp/tools.ts             регистрация MCP tools (dry-run/confirm для write)
  cli/doctor.ts            tempo-mcp doctor

Особенности DC API (проверено на стенде)

• База Planner — tempo-planning/1 (не tempo-planner).
• Модель аллокации per-day: secondsPerDay + commitment (%).
• GET allocation игнорирует query-фильтры → фильтрация по сотруднику/проекту/периоду на клиенте.
• Выделенного capacity-эндпоинта нет → ёмкость считается из workload/holiday scheme (TODO движка).

Праздники (производственный календарь РФ)

Эндпоинт Tempo holidayscheme/{id} не отдаёт даты праздников, поэтому используется производственный календарь РФ (источник — xmlcalendar.ru). Праздничные будние дни вычитаются из ёмкости во всех capacity/utilization-расчётах автоматически. Три уровня:

1. Встроенные данные — src/data/holidays-ru.ts (работают офлайн, без сети).
2. Офлайн-обновление — npm run update-holidays [годы]: фетчит календарь и пересоздаёт файл, сливая данные (год, который источник ещё не отдаёт, сохраняется как fallback).
3. Рантайм-автоподтягивание — TEMPO_MCP_HOLIDAYS_AUTOFETCH=true: недостающие годы догружаются на лету при запросе, с кэшем на процесс и фолбэком на встроенные данные при сбое сети.

Прочее:

• TEMPO_MCP_HOLIDAYS_RU=false — отключить встроенный календарь.
• TEMPO_MCP_HOLIDAYS=YYYY-MM-DD,... — добавить свои даты.

Ограничения / TODO

• recurrence трактуется как «каждый рабочий день периода».
• Рабочие субботы-переносы пока не добавляют ёмкость (вычитаются только праздники).

Публикация (для мейнтейнеров)

npm version patch          # или minor / major
npm publish                # prepublishOnly прогонит build + test; dist пересоберётся

Пакет публикуется как scoped public (publishConfig.access=public). В npm попадают только dist/, README.md, .env.example, LICENSE (см. поле files). Перед публикацией можно проверить состав: npm pack --dry-run.

Лицензия

MIT — см. LICENSE.