MCP Ukrainian Calendar: побудова open-source MCP-сервера

Є щось приємне в маленькому проекті, що працює рівно так як задумано. MCP Ukrainian Calendar сервер почався з практичної потреби — ШІ-асистенти майже нічого не знають про українські традиційні свята, язичницькі сезонні відзначення чи народний календар, що формував українську культуру протягом століть — і перетворився на чисту ілюстрацію того, як побудувати та опублікувати MCP-сервер з нуля.

Сервер доступний на GitHub: https://github.com/ChuprinaDaria/mcp-ukrainian-calendar та внесений до каталогу mcpservers.org: https://mcpservers.org/servers/chuprinadaria/mcp-ukrainian-calendar.

Проблема: ШІ не знає українських традицій

Запитайте будь-якого ШІ-асистента про українські свята — отримаєте комбінацію православних свят (добре задокументованих онлайн) і, якщо пощастить, кілька сучасних державних свят. Чого ви не отримаєте:

• Купала (Іван Купала) та його язичницькі ритуали вогню і води
• Маланку — старе новорічне свято з ряженими ходами
• Колодія — передвеликопосні гуляння, пов'язані з жіночим началом
• Повний цикл сезонних землеробських обрядів, задокументованих такими етнографами як Валерій Войтович

Енциклопедична праця Войтовича з української міфології та народного календаря — чудовий ресурс. Український традиційний календар є багатошаровим: дохристиянські слов'янські обряди, синкретизовані з православним християнством, землеробські сезони з відповідними ритуалами, кожен місяць зі своїми характерними відзначеннями. Це не тривіальність. Це жива культура, яку багато українців активно практикують або хочуть зрозуміти.

Стандартні тренувальні дані ШІ сильно зміщені на користь англомовного інтернет-контенту. Українська культурна спадщина — особливо дохристиянські народні традиції — недопредставлена. MCP-сервер є практичним способом заповнити цю прогалину для всіх, хто використовує сумісні з MCP ШІ-інструменти.

Що таке MCP (для незнайомих)

Model Context Protocol — відкритий стандарт Anthropic для підключення моделей ШІ до зовнішніх інструментів і джерел даних. MCP-сервер — це процес, що надає можливості: інструменти, ресурси, промпти, — які будь-який сумісний ШІ-клієнт може виявити та використати.

Ключовий висновок: вам не потрібно дообробляти модель або модифікувати будь-яку ШІ-систему, щоб додати нові можливості. Ви пишете MCP-сервер, підключаєте його до ШІ-клієнта — і можливості відразу доступні.

Думайте про це як систему плагінів для ШІ, але стандартизовану між клієнтами та моделями.

Архітектура сервера

MCP-сервер Ukrainian Calendar навмисно простий. Простота тут — перевага: MCP-сервер, який важко зрозуміти, важко довіряти та важко підтримувати.

Сервер надає три інструменти:

get_holiday_by_date — Задавши дату (або місяць/день), повертає всі українські традиційні відзначення на цю дату: назву свята, традиційні звичаї, символічне значення та будь-які пов'язані народні ритуали.

get_holidays_by_month — Повертає повний календар відзначень для заданого місяця. Корисно коли ШІ-асистент допомагає планувати заходи або пояснює сезонні теми.

search_holidays — Повнотекстовий пошук по базі свят за ключовим словом. Хочете знайти всі відзначення, пов'язані з водою? Вогнем? Конкретними землеробськими діяльностями?

Шар даних — структурований JSON-датасет, зібраний з етнографічних джерел, насамперед праці Войтовича з народного календаря. Кожен запис містить:

{
  "date": "07-07",
  "name": "Іван Купала (Купальська ніч)",
  "traditional_name": "Іван Купала",
  "type": "folk_pagan_syncretized",
  "customs": [
    "Стрибання через вогнища для очищення та здоров'я",
    "Плетіння вінків з квітів та пускання їх річкою",
    "Пошук mythical папороті-квітки опівночі",
    "Ритуальне купання в річках та росі"
  ],
  "symbolism": "Відзначення літнього сонцестояння; очищення водою та вогнем; ворожіння на любов та родючість",
  "source": "Традиція народного календаря Войтовича"
}

Побудова MCP-сервера: покрокова інструкція

Сервер використовує офіційний MCP Python SDK (mcp). Структура проста:

1. Встановіть залежності

pip install mcp
# або з uv (рекомендовано)
uv add mcp

2. Визначте сервер та його інструменти

from mcp.server import Server
from mcp.server.models import InitializationOptions
from mcp.types import Tool, TextContent
import mcp.server.stdio as stdio

server = Server("ukrainian-calendar")

@server.list_tools()
async def list_tools() -> list[Tool]:
    return [
        Tool(
            name="get_holiday_by_date",
            description=(
                "Отримати українські традиційні свята та відзначення для конкретної дати. "
                "Повертає народні звичаї, язичницькі традиції та культурне значення. "
                "Формат дати: MM-DD (наприклад, '07-07' для 7 липня)."
            ),
            inputSchema={
                "type": "object",
                "properties": {
                    "date": {
                        "type": "string",
                        "description": "Дата у форматі MM-DD",
                        "pattern": "^\\d{2}-\\d{2}$"
                    }
                },
                "required": ["date"]
            }
        ),
        # ... інші інструменти
    ]

@server.call_tool()
async def call_tool(name: str, arguments: dict) -> list[TextContent]:
    if name == "get_holiday_by_date":
        date = arguments["date"]
        holidays = calendar_data.get(date, [])

        if not holidays:
            return [TextContent(
                type="text",
                text=f"Немає конкретних традиційних відзначень для {date}."
            )]

        result = format_holidays(holidays)
        return [TextContent(type="text", text=result)]

    raise ValueError(f"Невідомий інструмент: {name}")

3. Точка входу

async def main():
    async with stdio.stdio_server() as (read_stream, write_stream):
        await server.run(
            read_stream,
            write_stream,
            InitializationOptions(
                server_name="ukrainian-calendar",
                server_version="0.1.0",
            )
        )

if __name__ == "__main__":
    import asyncio
    asyncio.run(main())

4. Зробіть його встановлюваним

Точка входу pyproject.toml дозволяє встановлення через uvx:

[project.scripts]
mcp-ukrainian-calendar = "mcp_ukrainian_calendar.server:main_sync"

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

Публікація на mcpservers.org

mcpservers.org — каталог MCP-серверів від спільноти. Вимоги для внесення до каталогу:

1. Публікація пакету на PyPI (щоб він був встановлюваний через uvx або pip)
2. Надсилання PR до репозиторію mcpservers.org з метаданими вашого сервера
3. Метадані включають: назву, опис, список інструментів, інструкції зі встановлення, ліцензію

Формат внесення до каталогу стандартизований. Ваш сервер потребує працюючого README.md, що пояснює що він робить, як встановити та як налаштувати в Claude Desktop або інших MCP-клієнтах. Спільнота переглядає та об'єднує.

Для користувачів Claude Desktop конфігурація проста:

{
  "mcpServers": {
    "ukrainian-calendar": {
      "command": "uvx",
      "args": ["mcp-ukrainian-calendar"]
    }
  }
}

Після цього Claude може відповідати на питання про українські народні свята з реальною глибиною — ритуали Купальської ночі, значення Масляної, які дати мають конкретне землеробське значення у традиційному календарі.

Що це демонструє

Сервер Ukrainian Calendar малий навмисно. Він демонструє щось важливе: MCP знижує бар'єр для додавання спеціалізованих знань до ШІ-систем до такого рівня, що доменні експерти — історики, етнографи, практики ремесла — можуть упакувати свої знання та зробити їх доступними для користувачів ШІ без очікування, поки велика лабораторія додасть їх до тренувальних даних.

Народні традиції, задокументовані Войтовичем, вимагали десятиліть польової роботи для збору. Ці знання тепер можуть бути доступні будь-якому ШІ-асистенту — негайно, через MCP-сервер, що зайняв вихідні для побудови.

Це і є реальна обіцянка протоколу: не просто підключення ШІ до баз даних та API, а надання спеціалізованих людських знань ШІ у стандартизований, композиційний спосіб.

Сервер є open source і приймає внески — особливо щодо розширення датасету свят та додавання регіональних варіацій. Знайдіть його на github.com/ChuprinaDaria/mcp-ukrainian-calendar.