Librus MCP Server

MCP (Model Context Protocol) server dla Librus API - umożliwia integrację z systemem dziennika elektronicznego Synergia/Librus poprzez narzędzia MCP.

Cechy

• ✅ Autoryzacja z kontem Librus
• 📚 Pobieranie ocen
• 📋 Pobieranie nieobecności
• 📅 Pobieranie planu lekcji
• ✉️ Obsługa wiadomości (odbieranie, wysyłanie)
• 📝 Pobieranie prac domowych
• 🎲 Pobranie szczęśliwego numeru
• 🔔 Powiadomienia
• 👥 Lista odbiorców wiadomości
• 📖 Lista przedmiotów

Wymagania

• Node.js 18+ (lub wyższa)
• npm lub yarn
• Konto Librus/Synergia

Instalacja

1. Sklonuj lub stwórz katalog projektu:

mkdir librus-mcp-server-node
cd librus-mcp-server-node

2. Zainstaluj zależności:

npm install

3. Skonfiguruj zmienne środowiska (.env):

cp .env.example .env

Edytuj .env i dodaj swoje dane Librus:

[email protected]
LIBRUS_PASSWORD=your_password

⚠️ WAŻNE: Login i hasło są wymagane! Serwer będzie się automatycznie logować przy każdym wywołaniu tool.

Użycie

Uruchamianie serwera

npm start

Serwer będzie nasłuchiwać na stdio i czekać na żądania MCP.

Tryb development z hot reload

npm run dev

Dostępne narzędzia (Tools)

Wszystkie narzędzia automatycznie się logują przy użyciu zmiennych z .env.

Informacje o koncie

• get_account_info - Pobierz informacje o koncie

Oceny

• get_grades - Pobierz wszystkie oceny
• get_grade - Pobierz szczegóły konkretnej oceny

Nieobecności

• get_absences - Pobierz wszystkie nieobecności
• get_absence - Pobierz szczegóły konkretnej nieobecności

Plan i Kalendarz

• get_timetable - Pobierz plan lekcji
• get_calendar - Pobierz kalendarz szkolny

Wiadomości

• get_messages - Pobierz wiadomości z folderu (1=inbox, 5=wysłane, 6=archiwum)
• get_message - Pobierz szczegóły wiadomości
• send_message - Wyślij wiadomość
• list_receivers - Pobierz listę odbiorców

Prace Domowe

• list_subjects - Pobierz listę przedmiotów
• get_homework - Pobierz prace domowe (opcjonalnie filtrowane po przedmiocie)
• get_homework_details - Pobierz szczegóły pracy domowej

Pozostałe

• get_lucky_number - Pobierz szczęśliwy numer na dzisiaj
• get_notifications - Pobierz powiadomienia

Przykład użycia

Nie musisz się logować ręcznie! Serwer automatycznie się zaloguje przy każdym wywołaniu tool.

Krok 1: Pobierz oceny

{
  "name": "get_grades",
  "arguments": {}
}

Krok 2: Pobierz plan lekcji

{
  "name": "get_timetable",
  "arguments": {}
}

Krok 3: Pobierz wiadomości z inbox

{
  "name": "get_messages",
  "arguments": {
    "folder_id": 1
  }
}

Krok 4: Wyślij wiadomość

{
  "name": "send_message",
  "arguments": {
    "recipient_id": 648158,
    "title": "Pytanie o pracę domową",
    "body": "Cześć, czy możesz mi wyjaśnić zadanie z matematyki?"
  }
}

Konfiguracja dla Claude.ai

Aby użyć tego MCP server z Claude.ai:

1. Uruchom serwer: npm start
2. W ustawieniach Claude dodaj konfigurację MCP server
3. Podaj ścieżkę do serwera: /path/to/librus-mcp-server-node/server.js
4. Ustaw args: [] (lub ["node"] jeśli jest potrzebne)

Struktura Folderów w Librus

ID folderów do get_messages:

• 1 - Odebrane (Inbox)
• 5 - Wysłane
• 6 - Archiwum
• Inne ID mogą się różnić w zależności od konfiguracji

Obsługa Błędów

Serwer automatycznie obsługuje błędy i zwraca:

{
  "success": false,
  "error": "Opis błędu"
}

Typowe błędy:

• Not authenticated - Musisz najpierw wybrać authorize
• Błędy połączenia - Sprawdzić połączenie z internetem
• Błędy autoryzacji - Sprawdzić login i hasło

Zabezpieczenia

⚠️ Ważne:

• Nigdy nie przechowuj hasła w kodzie na produkcji
• Używaj zmiennych środowiskowych (.env)
• Nie udostępniaj pliku .env publicznie
• Serwer nie przechowuje haseł - są one przesyłane bezpośrednio do Librus

Troubleshooting

"Module not found: @modelcontextprotocol/sdk"

npm install

Problemy z autoryzacją

1. Sprawdź czy login i hasło są poprawne
2. Sprawdź czy konto Librus jest aktywne
3. Sprawdź połączenie z internetem

Serwer nie uruchamia się

npm install --save-exact
npm start

Rozwijanie

Aby dodać nowe narzędzie:

1. Dodaj definicję w tablicy tools
2. Dodaj obsługę w handleToolCall
3. Używaj metod z librusClient z biblioteki librus-api

Licencja

MIT

Contributing

Zapraszamy do zgłaszania błędów i pull requestów!

Zasoby

• Librus API GitHub
• MCP Specification
• Model Context Protocol SDK