epiplan

Your my.epitech.eu planning, as tools an AI agent can use. Check what's open, get a clear report, register to activities and modules — with you in the loop.

What it does

• Reads your planning, modules, seats and slots

• Tells you what's open, closing soon, or already booked

• Registers you to events, slots and modules after you confirm

• Logs in through your Microsoft account, no password stored

• Runs on demand, nothing stays running in the background

What it never does

• Register without a dry run and your approval

• Show other students' names

• Unregister you unless you name the exact event

• Touch exams, or overlap your schedule, unless you say so

• Go past its write budget or module allowlist

 AI agent ──MCP──▶ server.py ─▶ tools.py ─▶ client.py ─▶ my.epitech.eu/api
 (you ask)            │            │             │
                      │     guardrails +         └─ silent Microsoft SSO
                      │     audit log               when tokens expire
                      └─ stdio (on demand) or HTTP

Install

Needs Python 3.10+ and an MCP-capable agent. The installer registers itself automatically with the claude and codex CLIs when they are available; otherwise it prints what to add by hand.

git clone https://github.com/daniilsys/epiplan.git
cd epiplan
./install.sh
epiplan login          # once: log in with Microsoft in the window that opens (MFA works)

Then edit ~/.config/epiplan/rules.md with your preferences, restart your agent, and ask it to check your planning (the installed skill is called planning).

Nothing is installed system-wide. Remove the symlinks, the MCP entry and the folder to uninstall.

Related MCP server: campus-edu-mcp

Use it

Ask in plain words: "check my planning", "what can I register to this week?", "book me the review". A typical run:

1. It reads your rules and the next 14 days.

2. You get a short report: already booked, open and matching your rules, to decide, to watch.

3. It asks which items you want, with choices for slots.

4. For each one: a dry run first (checks module, window, seats, slot, overlaps), then the real call, which your agent asks you to approve.

5. A recap of what was done and what was refused.

CLI for quick checks:

epiplan whoami
epiplan list --days 7 --open-only
epiplan serve --http 8765        # run the MCP server by hand

Tools

Dates are Europe/Paris; a bare date means that day at midnight. There is deliberately no module-unregistration tool.

Safety

The guardrails live in tools.py, not in a prompt, so a confused agent can't talk its way around them.

Your agent's own permission prompt on each real write is the last line of defence. Don't set "always allow" on the write tools.

tokens.json and session.json are mode 0600 and as sensitive as your login: never commit or share them.

How login works

The site signs you in with Microsoft Entra ID. Its internal refresh token only survives a few days of inactivity (measured: dead after about 67 hours), so pasting a token isn't reliable. epiplan uses your Microsoft session instead, which lasts much longer.

1. epiplan login opens a browser once. You sign in normally; the state is saved to session.json.

2. When the API refresh fails, client.py runs a headless browser with that state, clicks the Office 365 button, lets Microsoft's silent SSO do its job, captures the new tokens and saves them back, along with the renewed cookies.

3. If the Microsoft session itself has expired, you get a clear error: run epiplan login again.

Fallback chain: access token → POST /auth/refresh → silent SSO → stop with an error. No retry loops.

Run it on a server

session.json is the only state to move.

# on your machine
epiplan login
scp ~/.config/epiplan/session.json server:/srv/epiplan/data/

# on the server
docker build -t epiplan .
docker run -d --name epiplan -v /srv/epiplan/data:/data -p 127.0.0.1:8765:8765 \
  -e EPIPLAN_ENABLE_WRITES=1 epiplan

• Keep /data on a persistent, writable volume: the session is rewritten after each login.

• Never use the same session.json on two machines at once (cookie and token rotation).

• The HTTP endpoint has no authentication: keep it on localhost or a private network, or put an authenticating proxy in front.

• Not known yet: how long a Microsoft session lives for your tenant, and whether a new IP or country triggers MFA again. If so, refresh fails with a clear message: log in locally and copy the file again.

Add-ons

Optional features that live on their own branch, so main stays small.

To use one, install from its branch instead of main:

git clone -b addon/apple-calendar https://github.com/daniilsys/epiplan.git
cd epiplan && ./install.sh
epiplan calendar connect

Or, from an existing clone: git fetch origin && git switch addon/apple-calendar, then restart your agent. Setup details are in docs/APPLE_CALENDAR.md on that branch.

Repository

Status

• Read tools tested against the live API; the MCP server tested end to end over stdio; dry-run guardrails verified.

• Event registration and unregistration (no slots) tested by hand and reverted.

• Not tested live: module registration, slot registration against the API's own refusals (full event, overlap), deployment from another IP.

API notes and open questions are in docs/API.md. Issues and pull requests welcome.

License

MIT