edu-mcp 1.0.0__tar.gz

edu_mcp-1.0.0/.env.example

@@ -0,0 +1,45 @@
+# Configuration Edu MCP Server
+# ================================
+
+# Plateforme : "pronote" (défaut), "ecoledirecte" ou "skolengo"
+EDU_PLATFORM=pronote
+
+# Option A : Connexion Pronote (+ ENT) avec identifiant / mot de passe ou navigateur SSO
+PRONOTE_URL=https://demo.pronote.index-education.net/pronote/eleve.html
+PRONOTE_USERNAME=demonstration
+PRONOTE_PASSWORD=demonstration
+
+# Type de compte : "student" (élève, défaut) ou "parent"
+PRONOTE_ACCOUNT_TYPE=student
+
+# Nom de l'ENT si applicable (ex: ile_de_france, monbureaunumerique, toutatice, atrium_sud, etc.)
+PRONOTE_ENT=
+
+# Code PIN 2FA / Nom de l'appareil
+PRONOTE_ACCOUNT_PIN=0000
+PRONOTE_DEVICE_NAME=Mon Appareil MCP
+
+# Fichier de cache de session (défaut : ~/.edu_mcp/.session_cache.pkl)
+# PRONOTE_SESSION_FILE=.session_cache.pkl
+
+# Option B : Authentification Pronote par Token / QR-Code (généré automatiquement)
+# PRONOTE_TOKEN=votre_token_64_chars
+# PRONOTE_UUID=votre_uuid
+
+# Option C : ÉcoleDirecte (jetons appareil de confiance QCM 2FA)
+# EDU_ED_CN=
+# EDU_ED_CV=
+
+# Option D : Skolengo (OAuth2 PKCE)
+# EDU_SKOLENGO_TOKEN=
+# EDU_SKOLENGO_REFRESH_TOKEN=
+# EDU_SKOLENGO_SCHOOL_ID=
+# EDU_SKOLENGO_EMS_CODE=
+# EDU_SKOLENGO_OIDC_URL=
+
+# Pour un compte parent avec plusieurs enfants
+# PRONOTE_CHILD_NAME=Alexandre
+
+PRONOTE_CACHE_TTL=180
+PRONOTE_TIMEOUT=30
+PRONOTE_DOWNLOAD_DIR=./downloads

edu_mcp-1.0.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,26 @@
+---
+name: Bug report
+about: Report a bug or connection issue
+title: "[Bug]: "
+labels: bug
+---
+
+**Platform**
+- [ ] Pronote (+ ENT)
+- [ ] ÉcoleDirecte
+- [ ] Skolengo
+
+**Environment**
+- OS: (e.g. Windows 11, macOS, Ubuntu)
+- Python version:
+- MCP Client: (Antigravity, Claude Desktop, Cursor, Windsurf, VS Code)
+
+**Describe the bug**
+A clear and concise description of what happened.
+
+**Steps to reproduce**
+1. ...
+2. ...
+
+**Sanitized logs**
+> Please remove any personal URLs, usernames, tokens, or PINs before pasting logs.

edu_mcp-1.0.0/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,12 @@
+---
+name: Feature or Platform Request
+about: Suggest a new school platform, ENT connector, or MCP tool
+title: "[Feature]: "
+labels: enhancement
+---
+
+**Platform / Feature**
+Which platform or capability would you like to see supported?
+
+**Use case**
+Describe how you would use this in your AI assistant.

edu_mcp-1.0.0/.github/workflows/ci.yml

@@ -0,0 +1,30 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install package and dev dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Run unit tests
+        run: pytest tests/unit -v --cov-fail-under=0

edu_mcp-1.0.0/.github/workflows/publish.yml

@@ -0,0 +1,32 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  pypi-publish:
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/edu-mcp
+    permissions:
+      id-token: write
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build
+        run: python -m pip install build
+
+      - name: Build sdist and wheel
+        run: python -m build
+
+      - name: Publish package to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

edu_mcp-1.0.0/.gitignore

@@ -0,0 +1,41 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+env/
+venv/
+ENV/
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Secrets & Sessions
+.env
+.env.test
+profiles/
+switch_account.py
+switch_to_*.bat
+sso_debug.log
+*.pkl
+.session_cache.pkl
+.device_uuid
+
+# Testing & Debug
+.pytest_cache/
+.playwright-mcp/
+.coverage
+htmlcov/

edu_mcp-1.0.0/CONTRIBUTING.md

@@ -0,0 +1,26 @@
+# Contributing to Edu MCP
+
+Thank you for your interest in contributing to **Edu MCP**!
+
+## Development Setup
+
+```bash
+git clone https://github.com/jujukingg/edu-mcp.git
+cd edu-mcp
+pip install -e ".[dev]"
+```
+
+## Running Tests
+
+```bash
+pytest tests/unit -v --cov-fail-under=0
+```
+
+## Adding or Improving a Platform Provider
+
+All school platform providers live under `src/edu_mcp/providers/` and implement the `SchoolProvider` protocol in `src/edu_mcp/providers/base.py`, returning the shared immutable Pydantic DTOs from `src/edu_mcp/models.py`.
+
+1. Keep credentials out of logs and error messages.
+2. Add unit tests with mocked HTTP/client responses in `tests/unit/test_providers.py` (never commit real `.env` files or tokens).
+3. Update `README.md` and `README.fr.md` if you add new environment variables or tools.
+4. Use [Conventional Commits](https://www.conventionalcommits.org/) (`feat:`, `fix:`, `docs:`, `test:`, `chore:`).

edu_mcp-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pronote MCP Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

edu_mcp-1.0.0/PKG-INFO

@@ -0,0 +1,246 @@
+Metadata-Version: 2.5
+Name: edu-mcp
+Version: 1.0.0
+Summary: Unified Model Context Protocol (MCP) server for French school platforms (Pronote, ÉcoleDirecte, Skolengo, ENT).
+Project-URL: Homepage, https://github.com/jujukingg/edu-mcp
+Project-URL: Repository, https://github.com/jujukingg/edu-mcp
+Project-URL: Issues, https://github.com/jujukingg/edu-mcp/issues
+Author: Edu MCP Contributors
+License: MIT
+License-File: LICENSE
+Keywords: ecoledirecte,education,mcp,pronote,school,skolengo
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Education
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10
+Requires-Dist: ecoledirecte-py-client>=0.2.1
+Requires-Dist: httpx>=0.28.0
+Requires-Dist: mcp>=2.0.0
+Requires-Dist: opencv-python-headless>=4.8.0
+Requires-Dist: playwright>=1.40.0
+Requires-Dist: pronotepy>=2.11.0
+Requires-Dist: pydantic-settings>=2.2.0
+Requires-Dist: pydantic>=2.7.0
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: truststore>=0.10.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0.0; extra == 'dev'
+Requires-Dist: pytest-mock>=3.12.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+<div align="center">
+
+<img src="assets/logo.png" alt="Edu MCP" width="112" />
+
+<h1>Edu MCP</h1>
+
+<p>
+  <strong>The unified Model Context Protocol server for French school platforms.</strong><br />
+  Connect <strong>Pronote (+ ENT)</strong>, <strong>ÉcoleDirecte</strong>, and <strong>Skolengo</strong> to your AI assistant in seconds.
+</p>
+
+<p>
+  <a href="README.md"><strong>English</strong></a> · <a href="README.fr.md">Français</a>
+</p>
+
+<p>
+  <a href="https://github.com/jujukingg/edu-mcp/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/jujukingg/edu-mcp/ci.yml?style=flat-square&logo=github&label=CI" alt="CI" /></a>
+  <a href="https://pypi.org/project/edu-mcp/"><img src="https://img.shields.io/badge/PyPI-edu--mcp-3775A9?style=flat-square&logo=pypi&logoColor=white" alt="PyPI" /></a>
+  <img src="https://img.shields.io/badge/Python-3.10%2B-3776AB?style=flat-square&logo=python&logoColor=white" alt="Python 3.10+" />
+  <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-16a34a?style=flat-square" alt="MIT License" /></a>
+</p>
+
+</div>
+
+---
+
+## Supported Platforms
+
+<table>
+  <tr>
+    <td align="center" width="33%">
+      <img src="assets/logos/pronote.png" alt="Pronote" height="44" /><br /><br />
+      <strong>Pronote (+ ENT)</strong> &nbsp;<img src="https://img.shields.io/badge/Stable-16a34a?style=flat-square" alt="Stable" /><br />
+      <sub>Toutatice, MonBureauNumérique, Île-de-France, Atrium…</sub><br /><br />
+      <code>Browser SSO + 2FA + QR Token</code>
+    </td>
+    <td align="center" width="33%">
+      <img src="assets/logos/ecoledirecte.png" alt="ÉcoleDirecte" height="44" /><br /><br />
+      <strong>ÉcoleDirecte</strong> &nbsp;<img src="https://img.shields.io/badge/Beta-d97706?style=flat-square" alt="Beta" /><br />
+      <sub>Student &amp; Family multi-child spaces</sub><br /><br />
+      <code>Credentials + QCM 2FA</code>
+    </td>
+    <td align="center" width="33%">
+      <img src="assets/logos/skolengo.png" alt="Skolengo" height="44" /><br /><br />
+      <strong>Skolengo</strong> &nbsp;<img src="https://img.shields.io/badge/Beta-d97706?style=flat-square" alt="Beta" /><br />
+      <sub>School search &amp; federated ENT login</sub><br /><br />
+      <code>OAuth2 PKCE Browser</code>
+    </td>
+  </tr>
+</table>
+
+---
+
+## How It Works
+
+```mermaid
+flowchart LR
+    AI["AI Assistant<br/>Antigravity · Claude · Cursor · Windsurf"] <-->|MCP stdio| Server["Edu MCP<br/>(uvx edu-mcp)"]
+    Server --> P1["Pronote (+ ENT)"]
+    Server --> P2["ÉcoleDirecte"]
+    Server --> P3["Skolengo"]
+    Server --- Store[("~/.edu_mcp/.env (0600)<br/>Session Cache &amp; Device UUID")]
+```
+
+> [!IMPORTANT]
+> **Privacy & Security by Design**
+> - **Zero-leak login**: Pronote & Skolengo authenticate directly in your native browser — passwords never enter the chat.
+> - **Read-only messaging**: Your AI can read school announcements and discussion threads, never send messages.
+> - **Local-only storage**: Tokens and session caches stay on your machine in `~/.edu_mcp/.env` (`chmod 600`).
+
+---
+
+## Quick Start
+
+### 1. Add to Your AI Client
+
+Paste this into your MCP configuration file — no cloning or manual Python setup required:
+
+```json
+{
+  "mcpServers": {
+    "edu-mcp": {
+      "command": "uvx",
+      "args": ["edu-mcp"]
+    }
+  }
+}
+```
+
+<details>
+<summary><strong>Where is my MCP config file?</strong> (Antigravity, Claude Desktop, Cursor, Windsurf, VS Code)</summary>
+
+| Client | Configuration Path |
+|---|---|
+| **Antigravity** | `~/.gemini/config/mcp_config.json` |
+| **Claude Desktop (macOS)** | `~/Library/Application Support/Claude/claude_desktop_config.json` |
+| **Claude Desktop (Windows)** | `%APPDATA%\Claude\claude_desktop_config.json` |
+| **Cursor** | `~/.cursor/mcp.json` or `.cursor/mcp.json` |
+| **Windsurf** | `~/.codeium/windsurf/mcp_config.json` |
+| **VS Code (Copilot)** | `.vscode/mcp.json` |
+
+</details>
+
+<details>
+<summary><strong>Alternative:</strong> Run via <code>pip</code> or from a local git clone</summary>
+
+```bash
+pip install edu-mcp
+edu-mcp
+```
+
+Or from a cloned repository:
+
+```json
+{
+  "mcpServers": {
+    "edu-mcp": {
+      "command": "python",
+      "args": ["-m", "edu_mcp"],
+      "cwd": "/path/to/edu-mcp"
+    }
+  }
+}
+```
+
+</details>
+
+### 2. Connect in Chat
+
+Just ask your assistant:
+
+> *"Connect my Pronote / ÉcoleDirecte / Skolengo account"*
+
+1. The assistant calls `edu_setup_account` and guides you through the exact flow for your platform.
+2. **Pronote / Skolengo**: your browser opens on the official login page; sign in normally (ENT + 2FA) and your durable token is captured automatically.
+3. **ÉcoleDirecte**: sign in once with QCM 2FA verification; trusted device tokens (`cn`/`cv`) are saved for future sessions.
+
+---
+
+## Capabilities
+
+| Category | What Your Assistant Can Do |
+|---|---|
+| **Schedule** | Fetch daily/weekly timetables, room changes, cancellations, and lesson content; export `.ics` or `.pdf`. |
+| **Homework** | List upcoming assignments with attachments and mark homework as done/pending. |
+| **Grades & Analytics** | Read grades, subject & class averages, skill evaluations, report cards, simulate grades, and track progression. |
+| **School Life** | Check absences, delays, punishments, canteen menus, and school news. |
+| **Messaging** | Read unread threads and announcements *(strictly read-only)*. |
+| **Parent Mode** | List linked children and switch active child seamlessly. |
+
+<details>
+<summary><strong>Full MCP Tool, Resource &amp; Prompt Reference</strong> (25+ tools)</summary>
+
+### Unified Multi-Platform Tools (`edu_*`)
+
+| Tool | Description |
+|---|---|
+| `edu_list_platforms` | List supported platforms and search Skolengo schools. |
+| `edu_setup_account` | Chat-guided setup for Pronote, ÉcoleDirecte, or Skolengo. |
+| `edu_get_user_info` | Active user profile (name, class, school, account type). |
+| `edu_get_timetable` | Timetable lessons for a date range. |
+| `edu_get_homework` / `edu_set_homework_done` | Homework list and completion toggle. |
+| `edu_get_grades` / `edu_get_averages` | Individual grades and subject/class averages. |
+| `edu_get_absences` | Absences, delays, and punishments. |
+| `edu_get_news` | School announcements and news items. |
+| `edu_get_discussions` / `edu_get_discussion_messages` | Read-only messaging threads and messages. |
+| `edu_list_children` / `edu_select_child` | Multi-child switching for parent accounts. |
+
+> **Pronote-specific & Analytics tools** (`pronote_weekly_radar`, `pronote_simulate_grade`, `pronote_analyze_progression`, `pronote_get_evaluations`, `pronote_get_report`, `pronote_get_canteen_menu`, `pronote_export_ical`, `pronote_export_timetable_pdf`, `pronote_download_attachment`) are also registered.
+
+### Resources & Prompts
+
+- **Resources**: `pronote://student/profile`, `pronote://timetable/today`, `pronote://homework/pending`, `pronote://grades/overview`, `pronote://messages/unread`, `pronote://academics/weekly-radar`
+- **Prompts**: `pronote_daily_briefing`, `pronote_homework_planner`, `pronote_period_review`
+
+</details>
+
+<details>
+<summary><strong>Environment Variables</strong> (resolved from <code>PRONOTE_ENV_FILE</code>, <code>~/.edu_mcp/.env</code>, or local <code>.env</code>)</summary>
+
+| Variable | Description |
+|---|---|
+| `EDU_PLATFORM` | Active platform: `pronote`, `ecoledirecte`, or `skolengo`. |
+| `PRONOTE_MCP_HOME` | Custom directory for `.env`, session cache, and logs (default: `~/.edu_mcp`). |
+| `PRONOTE_ENV_FILE` | Explicit path to a `.env` file. |
+| `PRONOTE_URL` | Full Pronote web space URL (`eleve.html` or `parent.html`). |
+| `PRONOTE_USERNAME` / `PRONOTE_TOKEN` | Username and durable token (auto-generated). |
+| `PRONOTE_ACCOUNT_PIN` | Optional 4-digit 2FA PIN. |
+| `EDU_ED_CN` / `EDU_ED_CV` | ÉcoleDirecte trusted 2FA device tokens. |
+| `EDU_SKOLENGO_TOKEN` / `EDU_SKOLENGO_REFRESH_TOKEN` | Skolengo OAuth2 tokens. |
+| `PRONOTE_DOWNLOAD_DIR` | Directory for downloaded attachments and exports (default: `./downloads`). |
+
+</details>
+
+---
+
+## Development
+
+```bash
+git clone https://github.com/jujukingg/edu-mcp.git
+cd edu-mcp
+pip install -e ".[dev]"
+pytest tests/unit -v
+```
+
+---
+
+<p align="center">
+  Released under the <a href="LICENSE">MIT License</a>.
+</p>