npm package: @smartsoft001/librus-mcp-server
Description: MCP Server for Librus API (Synergia electronic gradebook)
Author: Twoje Imię
Latest version: 1.0.2

# 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:**

```bash
mkdir librus-mcp-server-node
cd librus-mcp-server-node
```

2. **Zainstaluj zależności:**

```bash
npm install
```

3. **Skonfiguruj zmienne środowiska (.env):**

```bash
cp .env.example .env
```

Edytuj `.env` i dodaj swoje dane Librus:

```env
LIBRUS_LOGIN=your_email@example.com
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

```bash
npm start
```

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

### Tryb development z hot reload

```bash
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

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

### Krok 2: Pobierz plan lekcji

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

### Krok 3: Pobierz wiadomości z inbox

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

### Krok 4: Wyślij wiadomość

```json
{
  "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:

```json
{
  "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"

```bash
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ę

```bash
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](https://github.com/Mati365/librus-api)
- [MCP Specification](https://modelcontextprotocol.io/)
- [Model Context Protocol SDK](https://github.com/modelcontextprotocol/node-sdk)