waseda-portal-mcp

Ein inoffizieller, lokaler, read-only MCP-Server, der Waseda Moodle, MyWaseda-Vorlesungsausfälle, den Web-Syllabus und den offiziellen akademischen Kalender der Waseda-Universität zusammenfasst. Er steht in keiner Verbindung zur Waseda-Universität und wird von dieser weder anerkannt, garantiert noch unterstützt.

Der Hauptzweck besteht darin, von einem MCP-Client zu fragen: „Zeig mir die Vorlesungen und Fristen von morgen“ und Vorlesungen, Ausfälle und Änderungen, Fristen des Tages sowie unvollständige überfällige Aufgaben mit Quellenangabe zu prüfen.

Unterstützte Datenquellen

• Waseda Moodle: reguläre Kurse, Aktivitätstypen, strukturierte Start- und Fristzeiten, Abgabe- und Abschlussstatus

• MyWaseda-Vorlesungsausfälle: Ausfälle und Änderungen für belegte Kurse in der initialen Ansicht nach dem Login

• Web-Syllabus: Jahr, Kurs- und Klassen-Code, anbietende Einrichtung, Verantwortliche, Zieljahrgang, veröffentlichte Zielgruppe und Voraussetzungen, Wochentag und Zeitraum, Raum, Modus, Überblick, Plan, Bewertung, Prüfungsangaben

• Offizieller akademischer Kalender der Waseda-Universität: Vorlesungsbeginn und -ende, Ferien, Feiertagsvorlesungen, Vorlesungsunterbrechungen, Prüfungszeiträume

Universitätslogos, Bildschirmaufnahmen, Lehrmaterialien, abgerufene Syllabus-Texte und reale personenbezogene Daten werden nicht in das Repository aufgenommen.

Voraussetzungen und Einrichtung

• Node.js 22 oder höher

• npm

• Auf dem System installiertes Google Chrome

git clone https://github.com/TakeruF/waseda-portal-mcp.git
cd waseda-portal-mcp
npm install
npm run build
npm run auth

npm run auth (oder nach dem Build waseda-portal-mcp auth) öffnet ein dediziertes Chrome-Profil. Der Login zu Waseda Moodle und MyWaseda erfolgt durch die Person selbst im Chrome; zuletzt öffnen Sie bitte unter MyWaseda „Vorlesungen → Vorlesungsbezogen → Ausfälle“. Wenn die Ausfallseite allein über die URL erreicht wird, wird der Authentifizierungsstatus gespeichert und das dedizierte Chrome automatisch geschlossen. Die CLI fragt weder Benutzername noch Passwort ab. Vorhandene Chrome-Profile oder Cookies aus der normalen Nutzung werden nicht kopiert.

Das standardmäßige dedizierte Profil liegt unter ~/.waseda-portal-mcp/chrome-profile, der vom Server geladene Authentifizierungsstatus unter ~/.waseda-portal-mcp/auth-state.json. Beide liegen außerhalb des Repositorys; die Authentifizierungsstatusdatei wird owner-only (0600) gesetzt. Die Speicherorte können über WASEDA_PORTAL_PROFILE_DIR und WASEDA_PORTAL_AUTH_STATE_PATH geändert werden. Chrome und der MCP-Server, die dasselbe dedizierte Profil verwenden, können nicht gleichzeitig gestartet werden.

MCP-Client-Konfiguration

Ersetzen Sie die absoluten Pfade durch Ihren tatsächlichen Checkout.

{
  "mcpServers": {
    "waseda-portal": {
      "command": "node",
      "args": ["/absolute/path/to/waseda-portal-mcp/dist/cli.js"]
    }
  }
}

Zum Deaktivieren des Caches fügen Sie "--no-cache" zu args hinzu. Die Standardausgabe von stdio ist ausschließlich für das MCP-Protokoll reserviert; Betriebsmeldungen werden auf die Standardfehlerausgabe ausgegeben.

Werkzeuge

• get_day_brief: integriert Vorlesungen, Änderungen, Fristen des Tages und unvollständige überfällige Aufgaben für date (YYYY-MM-DD)

• list_courses: normalerweise nur Kurse, deren Kategorie mit 正規科目/ beginnt; mit includeNonRegular werden auch Einführungskurse usw. einbezogen

• list_deadlines: listet Aktivitäten mit Fristen innerhalb von ISO-8601-from und to auf. Normalerweise werden eingereichte und abgeschlossene ausgeschlossen

• list_changes: listet Ausfälle und Änderungen im angegebenen Datumsbereich auf

• get_syllabus: gibt aus courseId oder syllabusKey Details oder mehrdeutige Kandidaten zurück

• search_syllabi: durchsucht den Web-Syllabus des aktuellen Jahres unabhängig vom Belegungsstatus nach Kursname oder Inhalt

Der mode von search_syllabi ist course_name für bekannte Kursnamen und content, wenn Sie nach Lerninhalten suchen. Bei der Inhaltssuche wird natürlicher Text in maximal drei Wörter zerlegt. Der MCP-Client kann über relatedTerms bis zu drei kurze verwandte Begriffe übergeben und so die Anzahl der Suchen und die Absicht explizit machen.

{
  "query": "日本の貨幣の歴史を学びたい",
  "mode": "content",
  "relatedTerms": ["貨幣", "通貨", "経済史"],
  "maxResults": 3,
  "useAcademicProfile": true
}

Die Ergebnisse enthalten den vollständigen Syllabus, die in der offiziellen Suche übereinstimmenden Wörter, die abgeglichenen Felder und die lexikalische Relevanz. Wenn ein lokales Lernprofil eingerichtet ist, wird profileApplied true, und für jeden Kandidaten wird eine beratende Übereinstimmung zu Einrichtung, Jahrgang und Voraussetzungen mitgeliefert. Die Inhaltssuche ist keine Garantie für eine semantische Kursempfehlung oder die Berechtigung zur Kursbelegung.

Optionales lokales Lernprofil

Nur die von der Person explizit angegebenen minimalen Lerninformationen können optional, standardmäßig unter ~/.waseda-portal-mcp/academic-profile.json, gespeichert werden. Es gibt keine Funktion, Name, Studentennummer, Einrichtung, Jahrgang oder Belegungshistorie automatisch aus MyWaseda oder Moodle abzurufen.

{
  "schemaVersion": 1,
  "affiliations": ["例示学部"],
  "academicLevel": "undergraduate",
  "year": 3,
  "completedPrerequisites": ["合成基礎科目"]
}

affiliations enthält bis zu fünf offizielle Fakultäts- und Graduiertenschulnamen, academicLevel ist undergraduate, masters, doctoral oder other, year ist 1 bis 6. In completedPrerequisites trägt die Person selbst nur bis zu 30 Kursnamen und Voraussetzungen ein, die für den Abgleich verwendet werden sollen. Da dies der Belegungshistorie entspricht, kann es weggelassen werden, wenn es nicht benötigt wird.

Setzen Sie das übergeordnete Verzeichnis auf 0700 und die Datei auf 0600 und legen Sie sie außerhalb des Repositorys ab. Wenn die Datei nicht existiert, wird wie bisher gesucht. Für einen anderen Speicherort kann WASEDA_PORTAL_ACADEMIC_PROFILE_PATH verwendet werden. Dateien mit zu weit gefassten Berechtigungen oder Dateien, die anderen Benutzern gehören, werden nicht gelesen.

Profilwerte werden nicht in MCP-Antworten, Logs, Snapshots oder Caches dupliziert. Ausgegeben werden nur profileApplied und die Begründung der verdeckten Bewertungen consistent, conflict, review_required und unavailable. Mit useAcademicProfile: false pro Aufruf wird das Profil nicht verwendet.

Datums- und Zeitangaben werden in ISO 8601 gehalten; wenn die Ursprungsseite keine Zeitzone angibt, werden sie als Asia/Tokyo interpretiert. Alle Ergebnisse enthalten die Quell-URL und den Prüfzeitpunkt. Bei Konflikten gilt die Reihenfolge MyWaseda, Moodle-Strukturinformationen, Web-Syllabus, Freitext.

Read-only-Garantie

Der normale Abruf besteht nur aus Seitenanzeige und DOM-Lesen. ReadOnlyGuard lehnt bekannte URLs für Aufgabenabgabe, Uploads, Quiz- und Umfrageantworten, Anwesenheit, Abschlussänderungen, Terminerstellung, Beiträge, Nachrichten und Belegungsänderungen sowie nicht erlaubte Nicht-GET-Anfragen ab.

Nur das offizielle Suchformular des Web-Syllabus verwendet trotz Suche HTTP POST. Daher wird ausschließlich der Such-POST eng zugelassen, bei dem der offizielle Host, /syllabus/JAA101.php und der read-only-Controller JAA103SubCon alle übereinstimmen. Auch für das verzögerte Laden von Moodle werden nur bekannte referenzierende Methoden für /lib/ajax/service.php zugelassen. Detailseiten werden per GET gelesen. Der Authentifizierungsablauf läuft in einem separaten Prozess; die Eingabe und Übermittlung der Anmeldedaten erfolgt durch die Person selbst.

Noten, Bewertungen, Dozenten-Feedback und Namen eingereichter Dateien existieren nicht im Modell und sind auch nicht in normalen Antworten enthalten. Moodle-Externalkalender-Token werden weder ausgestellt, gespeichert noch verwendet.

Personenbezogene Daten und Cache

Authentifiziertes HTML wird nach der Analyse im Speicher verworfen und nicht dauerhaft gespeichert. Cookies und Sitzungstoken befinden sich ausschließlich im dedizierten Profil und in der Authentifizierungsstatusdatei außerhalb des Repositorys und werden nicht in MCP-Antworten oder Logs ausgegeben. Das optionale Lernprofil wird ebenfalls beim Start einmal aus einer owner-only-Datei außerhalb des Repositorys gelesen; die Werte werden nicht in Antworten oder Caches gespeichert. Nur normalisierte Minimaldaten werden standardmäßig fünf Minuten im Prozessspeicher zwischengespeichert. Die TTL wird über WASEDA_PORTAL_CACHE_TTL_MS gesteuert, die Deaktivierung über --no-cache oder WASEDA_PORTAL_CACHE=false.

Nur die bestätigte Zuordnung courseId → syllabusKey kann zur Reduzierung erneuter Suchen unter ~/.waseda-portal-mcp/cache/course-syllabus-map.json gespeichert werden. Diese Zuordnungstabelle enthält keine Kursnamen, Verantwortlichennamen oder Studentennummern und wird atomar mit Verzeichnis 0700 und Datei 0600 aktualisiert. Mehrdeutige Kandidaten oder fehlende Übereinstimmungen werden nicht gespeichert.

Alle Fixtures sind künstliche Daten. Fügen Sie keine echten Daten in Issues, Logs, Fixtures oder Testausgaben ein. Weitere Details finden Sie in SECURITY.md.

Fehler

Es werden AUTH_REQUIRED, SESSION_EXPIRED, MAINTENANCE, SOURCE_UNAVAILABLE, PAGE_STRUCTURE_CHANGED, AMBIGUOUS_COURSE_MATCH, RATE_LIMITED und READ_ONLY_VIOLATION unterschieden. Wenn wichtige Selektoren verschwinden, wird ein leeres Array nicht als Erfolg behandelt, sondern PAGE_STRUCTURE_CHANGED zurückgegeben. Ein leeres Array wird nur zurückgegeben, wenn der reguläre Container für leere Listen bestätigt werden konnte.

Führen Sie bei fehlender Authentifizierung npm run auth aus. Bei Strukturänderungen reproduzieren Sie die minimale DOM-Struktur ohne personenbezogene Daten als künstliches Fixture und aktualisieren den betreffenden Parser und die Fixture-Tests. Fügen Sie authentifiziertes rohes HTML nicht in Issues oder Commits ein.

Entwicklung und Verifikation

npm test             # 外部アクセスなしの人工fixtureテスト
npm run typecheck
npm run lint
npm run format:check
npm run build
npm run test:live:auth-state     # 新規一時プロファイルでAUTH_REQUIREDを確認
npm run test:live:authenticated  # 認証必須。AUTH_REQUIRED/SESSION_EXPIREDは失敗
npm run test:live:catalog        # 公開シラバスの内容検索と科目名検索
npm run test:e2e:authenticated   # ビルド後、MCPクライアントからstdio E2E
npm run test:e2e:catalog         # search_syllabiのstdio E2E

test:live ist ein Alias für test:live:authenticated. Die authentifizierungspflichtige Live-Verifikation ist auf eine gleichzeitige Ausführung, ein Zugriffsintervall von einer Sekunde, einen regulären Kurs, maximal drei Syllabus-Kandidaten und maximal ein Aufgabendetail begrenzt. Ohne Authentifizierung schlägt sie fehl und wird nicht als Erfolg behandelt. Fixture-Erfolg, authentifizierter Live-Erfolg und MCP-Client-E2E-Erfolg sind als getrennte Nachweise zu behandeln.

Bekannte Einschränkungen

• DOM-Änderungen an Moodle, MyWaseda und dem Web-Syllabus können Parser-Updates erforderlich machen.

• Die Inhaltssuche ist eine lexikalische Suche über die Stichwortsuche aller Felder des offiziellen Web-Syllabus. Synonyme und abstrakte Interessen werden über relatedTerms ergänzt, begrenzt auf maximal drei Suchen und maximal fünf Details.

• Die Bewertung durch das Lernprofil ist beratend. Der Zieljahrgang, der im Web-Syllabus ein eigenständiges Feld ist, wird strukturell abgeglichen, aber die anbietende Einrichtung wird nicht als Zugehörigkeitsbeschränkung betrachtet. Wenn Zielgruppe, Voraussetzungskurse, Kapazität und Registrierungszeitraum in Freitext oder Fakultätsrichtlinien stehen, wird nicht automatisch auf Belegbarkeit geschlossen; die offiziellen Informationen müssen geprüft werden.

• MyWaseda unterstützt nur die initiale Ansicht für belegte Kurse; die POST-Operation für die fakultätsweite Anzeige ist nicht implementiert.

• Vorlesungstermine werden aus dem bestätigten Wochentag und Zeitraum des Syllabus sowie Semester und Ferientagen generiert. Freitexte zu Intensivkursen, Zusatzvorlesungen und einzelnen Terminen werden nicht als sicher angenommen.

• Der Abgleich von Moodle und Syllabus basiert auf Jahr, anbietender Einrichtung, normalisiertem Kursnamen, Klasse, Verantwortlichen und, falls verfügbar, Wochentag und Zeitraum. Wenn sich Moodle-Name und Syllabus-Name unterscheiden, werden über eine Teilübereinstimmung des Verantwortlichen bis zur maximalen Anzahl Kandidaten abgerufen. Bei schwacher Begründung oder geringem Abstand der obersten Kandidaten werden nur mehrdeutige Kandidaten zurückgegeben; Raum- und Prüfungsinformationen werden nicht bestätigt.

• Dauerhafte Benachrichtigungen, Schreibvorgänge, Notenabruf, Massenabruf von Lehrmaterialien, Kalendertoken, Chrome-Erweiterungen, Cloud-Authentifizierung, Remote-MCP und mehrere Universitäten sind nicht abgedeckt.

Adapter für andere Universitäten

Gemeinsam ist nicht die Abrufmethode, sondern das Ergebnis, das die Nutzer benötigen. Implementieren Sie zunächst UniversityAdapter innerhalb desselben Pakets; universitätsspezifische Selektoren, IDs und Abgleichsregeln liegen unter dem Adapter. Universitätsspezifische Informationen kommen in extensions. Erst wenn die tatsächlichen Grenzen mit einer zweiten Universität bestätigt sind, wird in ein separates Paket aufgeteilt. Weitere Details finden Sie in docs/architecture.md.

Lizenz

MIT