MCP Ukrainian Calendar: budowanie open-source serwera MCP

Jest coś satysfakcjonującego w małym projekcie, który działa dokładnie tak jak zamierzono. Serwer MCP Ukrainian Calendar zaczął się od praktycznej potrzeby — asystenci AI wiedzą prawie nic o ukraińskich tradycyjnych świętach, pogańskich obchodach sezonowych ani o kalendarzu ludowym, który kształtował kulturę ukraińską przez wieki — i stał się czystą ilustracją jak zbudować i opublikować serwer MCP od zera.

Serwer jest dostępny na GitHub pod adresem https://github.com/ChuprinaDaria/mcp-ukrainian-calendar i wymieniony na mcpservers.org: https://mcpservers.org/servers/chuprinadaria/mcp-ukrainian-calendar.

Problem: AI nie zna ukraińskich tradycji

Zapytaj dowolnego głównego asystenta AI o ukraińskie święta, a dostaniesz kombinację świąt prawosławnych (dobrze udokumentowanych online) i, jeśli masz szczęście, kilka współczesnych świąt obywatelskich. Czego nie dostaniesz:

• Kupały (Noc Iwana Kupały) i jej pogańskich rytuałów ognia i wody
• Malankę — stary noworoczny obchód z korowodami w przebraniach
• Kołodija — przedpostne uroczystości związane z zasadą kobiecości
• Pełnego cyklu sezonowych obrzędów rolniczych udokumentowanych przez etnografów takich jak Walerij Wojtowycz

Encyklopedyczna praca Wojtowycza nad ukraińską mitologią i kalendarzem ludowym to niezwykłe źródło. Ukraiński tradycyjny kalendarz jest warstwowy — przedchrześcijańskie słowiańskie obrzędy zsynchronizowane z prawosławnym chrześcijaństwem, sezony rolnicze z odpowiadającymi im rytuałami, każdy miesiąc ze swoimi charakterystycznymi obchodami.

Standardowe dane treningowe AI są silnie przesunięte w kierunku anglojęzycznych treści internetowych. Ukraińskie dziedzictwo kulturowe — zwłaszcza przedchrześcijańskie tradycje ludowe — jest niedoreprezentowane. Serwer MCP to praktyczny sposób na wypełnienie tej luki dla każdego używającego narzędzi AI kompatybilnych z MCP.

Czym jest MCP (dla niewtajemniczonych)

Model Context Protocol to otwarty standard Anthropic do łączenia modeli AI z zewnętrznymi narzędziami i źródłami danych. Serwer MCP to proces eksponujący możliwości — narzędzia, zasoby, prompty — które każdy kompatybilny klient AI może wykryć i użyć.

Kluczowy wniosek: nie musisz fine-tunować modelu ani modyfikować żadnego systemu AI, aby dodać nowe możliwości. Piszesz serwer MCP, podłączasz go do klienta AI i możliwości są natychmiast dostępne.

Pomyśl o tym jak o systemie wtyczek dla AI, ale ustandaryzowanym między klientami i modelami.

Architektura serwera

Serwer MCP Ukrainian Calendar jest celowo prosty. Prostota jest tu zaletą — serwer MCP, który jest trudny do zrozumienia, jest trudny do ufania i trudny do utrzymania.

Serwer eksponuje trzy narzędzia:

get_holiday_by_date — Podając datę (lub miesiąc/dzień), zwraca wszystkie ukraińskie tradycyjne obchody na tę datę: nazwę święta, tradycyjne zwyczaje, symboliczne znaczenie i wszelkie związane rytuały ludowe.

get_holidays_by_month — Zwraca pełny kalendarz obchodów dla danego miesiąca. Przydatne gdy asystent AI pomaga w planowaniu wydarzeń lub wyjaśnianiu sezonowych motywów.

search_holidays — Wyszukiwanie pełnotekstowe w bazie świąt według słów kluczowych. Chcesz znaleźć wszystkie obchody związane z wodą? Ogniem? Konkretnymi czynnościami rolniczymi?

Warstwa danych to ustrukturyzowany zestaw danych JSON skompilowany ze źródeł etnograficznych, przede wszystkim pracy Wojtowycza nad kalendarzem ludowym. Każdy wpis zawiera:

{
  "date": "07-07",
  "name": "Ivan Kupala (Noc Kupały)",
  "traditional_name": "Іван Купала",
  "type": "folk_pagan_syncretized",
  "customs": [
    "Skakanie przez ogniska dla oczyszczenia i zdrowia",
    "Plecenie wieńców z kwiatów i puszczanie ich na rzekach",
    "Poszukiwanie mitycznego kwiatu paproci o północy",
    "Rytualna kąpiel w rzekach i rosie"
  ],
  "symbolism": "Obchody przesilenia letniego; oczyszczenie wodą i ogniem; wróżby płodności i miłości",
  "source": "Tradycja kalendarza ludowego Wojtowycza"
}

Budowanie serwera MCP: krok po kroku

Serwer używa oficjalnego MCP Python SDK (mcp). Struktura jest prosta:

1. Zainstaluj zależności

pip install mcp
# lub z uv (zalecane)
uv add mcp

2. Zdefiniuj serwer i jego narzędzia

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=(
                "Pobierz ukraińskie tradycyjne święta i obchody dla konkretnej daty. "
                "Zwraca ludowe zwyczaje, pogańskie tradycje i kulturowe znaczenie. "
                "Format daty: MM-DD (np. '07-07' dla 7 lipca)."
            ),
            inputSchema={
                "type": "object",
                "properties": {
                    "date": {
                        "type": "string",
                        "description": "Data w formacie 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"Brak konkretnych tradycyjnych obchodów odnotowanych dla {date}."
            )]

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

    raise ValueError(f"Nieznane narzędzie: {name}")

3. Punkt wejścia

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. Uczyń instalowalnym

Punkt wejścia pyproject.toml umożliwia instalację przez uvx:

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

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

Publikacja na mcpservers.org

mcpservers.org to katalog społeczności serwerów MCP. Wymagania do wylistowania:

1. Publikacja pakietu na PyPI (aby był instalowalny przez uvx lub pip)
2. Wysłanie PR do repozytorium mcpservers.org z metadanymi serwera
3. Metadane zawierają: nazwę, opis, listę narzędzi, instrukcje instalacji, licencję

Format wylistowania jest ustandaryzowany. Twój serwer potrzebuje działającego README.md wyjaśniającego co robi, jak go zainstalować i jak skonfigurować w Claude Desktop lub innych klientach MCP.

Dla użytkowników Claude Desktop konfiguracja jest prosta:

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

Po tym Claude może odpowiadać na pytania o ukraińskie święta ludowe z prawdziwą głębią — rytuały Nocy Kupały, znaczenie Maslanki, które daty mają konkretne znaczenie rolnicze w tradycyjnym kalendarzu.

Co to pokazuje

Serwer Ukrainian Calendar jest mały celowo. Demonstruje coś ważnego: MCP obniża barierę dodawania wyspecjalizowanej wiedzy do systemów AI do punktu, gdzie eksperci dziedzinowi — historycy, etnografowie, praktycy rzemiosła — mogą opakować swoją wiedzę i udostępnić ją użytkownikom AI bez czekania, aż duże laboratorium doda ją do danych treningowych.

Tradycje ludowe udokumentowane przez Wojtowycza wymagały dziesięcioleci pracy terenowej do skompilowania. Ta wiedza może być teraz dostępna dla każdego asystenta AI, natychmiast, przez serwer MCP, który zbudowanie zajęło weekend.

To jest właściwa obietnica protokołu: nie tylko łączenie AI z bazami danych i API, ale udostępnianie wyspecjalizowanej ludzkiej wiedzy dla AI w ustandaryzowany, kompozycyjny sposób.

Serwer jest open source i przyjmuje wkłady — zwłaszcza do rozszerzania zestawu danych świąt i dodawania regionalnych wariantów. Znajdź go na github.com/ChuprinaDaria/mcp-ukrainian-calendar.