MCP Time Server

MCP (Model Context Protocol) сервер для работы с временными зонами, датами и календарями России. Предоставляет LLM инструменты для получения текущего времени, конвертации между временными зонами, сдвига дат, а также праздники, производственный календарь, фазы Луны, народный и профессиональный календари.

Функции

Время и даты

• currentTime — текущее время в указанной временной зоне
• convertTime — конвертация времени между временными зонами
• customTime — информация о произвольной дате/времени
• localTZ — локальная временная зона сервера
• beforeDays / afterDays — дата N дней назад/вперёд
• beforeWeeks / afterWeeks — дата N недель назад/вперёд
• beforeMonths / afterMonths — дата N месяцев назад/вперёд

Календари и праздники

• getHolidays — праздники по дате, месяцу или году (официальные, православные, лунные, народные, профессиональные, неофициальные)
• searchHolidays — fuzzy-поиск праздников по названию (опечатки, транслит)
• getLunarPhase — фаза Луны на дату
• getFolkCalendar — народный календарь: праздники, приметы, обычаи
• getGardeningCalendar — календарь огородника: посадочные дни по луне и приметам
• getProfessionalCalendar — профессиональные и памятные дни отраслей
• getUnofficialCalendar — неофициальные и международные праздники

Производственный календарь и рабочие дни

• getWorkCalendar — производственный календарь на месяц/год (тип каждого дня)
• getPersonnelCalendar — кадровый календарь: рабочие/выходные, праздники, переносы
• getAccountingCalendar — бухгалтерский календарь: нормы времени и дедлайны отчётности
• isWorkingDay — является ли дата рабочим днём
• nextWorkingDay / previousWorkingDay — ближайший рабочий день после/перед датой
• addWorkingDays — прибавить N рабочих дней к дате
• workingDaysBetween — количество рабочих дней в интервале

Полное описание параметров и форматов ответов — в docs/API.md.

Запуск

Docker

docker run -p 3000:3000 \
           -v /etc/localtime:/etc/localtime:ro \
           -v /etc/timezone:/etc/timezone:ro \
           git.ymnuktech.ru/ymnuk/mcp-time

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

docker run -p 8080:8080 \
           -v /etc/localtime:/etc/localtime:ro \
           -v /etc/timezone:/etc/timezone:ro \
           -e WEB_PORT=8080 \
           git.ymnuktech.ru/ymnuk/mcp-time

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

Настройки задаются YAML-файлом, переменными окружения или CLI-флагами. Пример полного конфига — config.yml.example:

# YAML-файл
./mcp-time --config config.yml.example
CONFIG_FILE=config.yml.example ./mcp-time

# или флаги
./mcp-time --port 8080 --log-level debug

Флаг	Переменная окружения	Описание
-p, --port	WEB_PORT	Порт HTTP-сервера (по умолчанию 3000)
--config <path>	CONFIG_FILE	Путь к YAML-конфигу
--log-level	LOG_LEVEL	Уровень лога: debug, info, warn, error, off
--log-file	LOG_FILE	Файл лога (пусто = stdout)
—	JWT_SECRET	HS256-секрет JWT (пусто = анонимный режим)
—	JWT_ID_CLAIM	JWT-claim с id пользователя (по умолчанию sub)
—	JWT_INVALID_MODE	Поведение при невалидном JWT: reject | skip
—	HOLIDAYS_DIR	Директория с файлами переносов holidays-{YEAR}.yaml

Полная схема конфигурации — в docs/config-schema.md.

Аутентификация и доступ

• JWT-идентификация (HS256) через заголовок Authorization: Bearer <token>; при пустом JWT_SECRET — анонимный режим.
• Инструменты календарей привязаны к группам (official, orthodox, lunar, folk, gardeners, professional, unofficial, accountant, personnel), каждая с уровнем доступа public | authenticated | private.
• Фильтрация tools/list и результатов вызовов по правам пользователя.

Подробности — в docs/ACCESS.md.

Необходимые монтирования

Для корректной работы в Docker-контейнере:

• /etc/localtime:/etc/localtime:ro — временная зона
• /etc/timezone:/etc/timezone:ro — дополнительная информация о временной зоне
• ./data:/app/data:ro — директория с файлами переносов holidays-{YEAR}.yaml (путь настраивается через HOLIDAYS_DIR)

Требования

• Docker 20.10 или выше
• Поддержка монтирования файлов из хоста

Лицензия

Этот проект распространяется под лицензией MIT. См. файл LICENSE для подробностей.