# edookit-mcp

MCP server for the [Edookit](https://www.edookit.com/) school management system API. Exposes all 13 Edookit API modules as 49 MCP tools.

## Installation

### Claude Desktop

Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "edookit": {
      "command": "npx",
      "args": ["github:thewulf7/edookit-mcp"],
      "env": {
        "EDOOKIT_SCHOOL": "your-school-subdomain",
        "EDOOKIT_USERNAME": "api-username",
        "EDOOKIT_PASSWORD": "api-password"
      }
    }
  }
}
```

`EDOOKIT_SCHOOL` is the subdomain of your school's Edookit portal — if the portal is at `https://zs-example.edookit.net`, the subdomain is `zs-example`.

### Docházka (RFID Attendance) module

The attendance module uses HMAC authentication and requires prior vendor registration with Edookit (email `support@edookit.com`). Once registered, add three extra env vars:

```json
"EDOOKIT_HMAC_CLIENT_ID": "your-client-id",
"EDOOKIT_HMAC_CLIENT_KEY": "your-client-key",
"EDOOKIT_HMAC_MARK": "your-mark"
```

## Tools

### Attendance / Docházka (HMAC auth)

| Tool | Description |
|---|---|
| `attendance_version` | Service version (public, no auth) |
| `attendance_settings` | Current school year and semester |
| `attendance_classes` | List classes; optional `pk` to get one |
| `attendance_schedule_groups` | Schedule groups and courses |
| `attendance_job_classifications` | Staff job classification codebook |
| `attendance_bell_schedule` | Teaching period time ranges |
| `attendance_staff` | All staff including RFID card numbers |
| `attendance_students` | All students including guardian contacts and RFID cards |
| `attendance_daily_schedule` | Daily schedule for a person on a date |
| `attendance_passages_by_date` | All RFID passages on a date |
| `attendance_passage_by_id` | Single passage by ID |
| `attendance_insert_passage` | Record a new RFID entry/exit event |

### Lessons / Hodiny

| Tool | Description |
|---|---|
| `lessons_version` | API version |
| `lessons_list` | Timetable for a day; filters by course, room, teacher, student, class |
| `lessons_rooms` | All rooms |
| `lessons_course_types` | All course types |
| `lessons_work_types` | All work/activity types |

### People

| Tool | Description |
|---|---|
| `person_search` | Search by Edookit ID or Plus4U ID; returns roles, children, representatives |
| `student_personal_data` | Student personal data as of a reference date |
| `employee_personal_data` | Employee personal data as of a reference date |
| `student_statistics` | Pseudonymized student statistics (no names, anonymous UUID) |

### Grades / Hodnocení

| Tool | Description |
|---|---|
| `evaluations_list` | List evaluations filtered by student, course, or evaluation term |

### Payments / Platby

| Tool | Description |
|---|---|
| `payments_version` | API version |
| `payments_categories` | Payment categories |
| `payments_currencies` | Available currencies |
| `payments_bank_accounts` | Configured bank accounts |
| `payments_types` | Payment types |
| `payments_organizations` | Organizations |
| `payments_list_prescriptions` | List prescriptions with filters |
| `payments_create_prescription` | Create a prescription with optional per-person overrides |
| `payments_create_payment` | Record a payment transaction |
| `payments_update_prescription` | Update a prescription |
| `payments_delete_prescription` | Delete a prescription or remove persons from it |
| `payments_update_payment` | Update a payment record |
| `payments_delete_payment` | Delete a payment record |

### Courses / Kurzy

| Tool | Description |
|---|---|
| `courses_version` | API version |
| `courses_student_courses` | Students with courses, lessons, final evaluations, and attendance % |

### Timetable

| Tool | Description |
|---|---|
| `public_events` | Public school events in a date range (no auth required) |
| `changed_timetable` | Substitution schedule — only lessons that changed vs original |

### Direct Attendance / Přímý zápis docházky

| Tool | Description |
|---|---|
| `direct_attendance_lessons` | Lesson overview for a student on a day |
| `direct_attendance_future_excuse` | Submit a future absence notice (avízo) |
| `direct_attendance_current_excuse` | Submit a current excuse (omluvenka) |
| `direct_attendance_record` | Insert an attendance record with optional status/minutes |
| `direct_attendance_student_overview` | Full attendance history for a student |

### Individual Goals / Individuální cíle

| Tool | Description |
|---|---|
| `individual_goals_lesson_content` | Individual lesson content per student |
| `individual_goals_learning_agreements` | Learning agreements with coach feedback and subcompetences |

## Notes

- All dates use `YYYY-MM-DD` format unless noted otherwise.
- Person IDs are unique **within one Edookit instance** but not across different schools.
- `public_events` and `changed_timetable` use the legacy `-login.edookit.net` base URL automatically.
- The Timetable creation module (Tvorba rozvrhů) is not yet publicly available in the Edookit API.

## Development

```bash
git clone https://github.com/thewulf7/edookit-mcp
cd edookit-mcp
npm install
npm run build
```