N Lobby CLI

Hinweis: Der Entwickler übernimmt keine Verantwortung für Schäden, die durch die Nutzung dieses Tools entstehen könnten. Diese Software wurde zu Bildungszwecken entwickelt und ihr Betrieb ist nicht garantiert.

Ein Dual-Mode-CLI- und Model Context Protocol (MCP)-Server für den Zugriff auf Daten des N Lobby-Schulportals. Verwenden Sie ihn interaktiv über das Terminal mit nlobby oder verbinden Sie ihn als MCP-Server mit nlobby serve mit einem KI-Assistenten.

Funktionen

• CLI-Modus: Greifen Sie direkt vom Terminal auf N Lobby-Daten zu – Nachrichten, Stundenplan, Kurse, Profil und mehr

• MCP-Modus: Vollständiger MCP-Server, kompatibel mit Claude, Cursor und anderen MCP-fähigen KI-Assistenten

• Browserbasierte Authentifizierung: Interaktive Anmeldung über ein automatisiertes Puppeteer-Browserfenster

• Sitzungspersistenz: Der CLI-Modus speichert Cookies unter ~/.nlobby/session für eine nahtlose anschließende Nutzung

• Zugriff auf Schulinformationen: Abrufen von Ankündigungen, Stundenplänen und Lernressourcen

• Verwaltung erforderlicher Kurse: Zugriff auf Informationen zu erforderlichen Kursen und akademische Daten

• Mehrere Kalendertypen: Unterstützung für persönliche Kalender sowie Schulkaleder

• Benutzerrollen-Unterstützung: Unterschiedliche Zugriffsebenen für Schüler, Eltern und Mitarbeiter

Related MCP server: MCP Server Sample

Installation

Option 1: Installation über npm (Empfohlen)

npm install -g nlobby-cli

Option 2: Entwicklungsinstallation

1. Klonen Sie das Repository:

git clone https://github.com/minagishl/nlobby-cli.git
cd nlobby-cli

2. Installieren Sie die Abhängigkeiten:

pnpm install

3. Erstellen Sie das Projekt:

pnpm run build

Konfiguration

Erstellen Sie eine .env-Datei, falls Sie Standardwerte überschreiben müssen (optional):

NLOBBY_BASE_URL=https://nlobby.nnn.ed.jp
MCP_SERVER_NAME=nlobby-cli
MCP_SERVER_VERSION=1.0.0

CLI-Nutzung

Authentifizierung

# Interactive browser login (recommended)
nlobby login

# Set cookies manually
nlobby cookies set "__Secure-next-auth.session-token=ey...;"

# Check current authentication status
nlobby cookies check

Nachrichten

# List latest news (default: 10, newest first)
nlobby news

# Filter and sort
nlobby news --limit 20 --category お知らせ --sort oldest --unread

# Show full article
nlobby news show 980

# Download the first attachment to /tmp
nlobby news download 980 --index 1 --output-dir /tmp

# Mark as read
nlobby news read 980

Stundenplan & Kalender

# Today's schedule
nlobby schedule

# Specific date
nlobby schedule 2026-04-01

# This week's personal calendar
nlobby calendar

# School calendar for a date range
nlobby calendar --type school --from 2026-04-01 --to 2026-04-07

Kurse

# All required courses
nlobby courses

# Filter by grade / semester
nlobby courses --grade 2 --semester 2025

Profil & Gesundheit

nlobby profile
nlobby health

MCP-Server

# Start MCP server (stdio transport)
nlobby serve
# or
nlobby mcp

Alle Befehle unterstützen --json, um rohes JSON anstelle von formatiertem Text auszugeben.

MCP-Nutzung

Cursor IDE-Einrichtung

Fügen Sie Folgendes zu Ihren Cursor-Einstellungen hinzu (~/.cursor/config.json):

{
  "mcpServers": {
    "nlobby": {
      "command": "npx",
      "args": ["-y", "nlobby-cli", "serve"],
      "env": {
        "NLOBBY_BASE_URL": "https://nlobby.nnn.ed.jp"
      }
    }
  }
}

Claude Desktop-Einrichtung

Fügen Sie dies zu Ihrer Claude Desktop-Konfiguration hinzu (~/Library/Application Support/Claude/claude_desktop_config.json unter macOS):

{
  "mcpServers": {
    "nlobby": {
      "command": "npx",
      "args": ["-y", "nlobby-cli", "serve"],
      "env": {
        "NLOBBY_BASE_URL": "https://nlobby.nnn.ed.jp"
      }
    }
  }
}

Andere MCP-Clients

Verwenden Sie für jeden MCP-kompatiblen Client:

• Befehl: nlobby serve (falls global installiert) oder node /path/to/dist/index.js serve

• Protokoll: stdio

• Umgebung: Optionale Umgebungsvariablen wie im Abschnitt Konfiguration aufgeführt

MCP-Ressourcen

MCP-Tools

Authentifizierung

Nachrichten

Stundenplan & Kalender

Kurse & Prüfungen

Konto & Navigation

Fehlerbehebung

Authentifizierungsablauf

Methode 1: Interaktive Browser-Anmeldung (Empfohlen)

CLI:

nlobby login

MCP-Tool: interactive_login

Ein Browserfenster öffnet sich automatisch. Schließen Sie die N Lobby-Anmeldung ab; die Cookies werden extrahiert und gespeichert.

Methode 2: Manuelle Cookie-Einrichtung

1. Melden Sie sich in Ihrem Webbrowser bei N Lobby an

2. Öffnen Sie die Entwicklertools → Anwendung / Speicher → Cookies

3. Kopieren Sie alle Cookies als Zeichenfolge

CLI:

nlobby cookies set "__Secure-next-auth.session-token=ey...;"

MCP-Tool: set_cookies cookies="__Secure-next-auth.session-token=ey...;"

Benutzertypen

Der Server unterstützt drei Benutzertypen basierend auf der E-Mail-Domain:

Projektstruktur

src/
├── index.ts              # Entry point — CLI vs MCP mode detection
├── config.ts             # Configuration management
├── logger.ts             # Logging utilities
├── trpc-client.ts        # tRPC client for API calls
├── types.ts              # TypeScript type definitions
├── api/
│   ├── index.ts          # NLobbyApi facade + session persistence
│   ├── context.ts        # ApiContext interface
│   ├── shared.ts         # Shared utilities (fetchRenderedHtml, …)
│   ├── news.ts           # News functions
│   ├── schedule.ts       # Schedule / calendar functions
│   ├── courses.ts        # Course / exam functions
│   ├── account.ts        # Account info / student card functions
│   ├── navigation.ts     # Navigation / notification / interest functions
│   └── health.ts         # Health check / debug functions
├── auth/
│   ├── browser.ts        # Puppeteer browser authentication
│   ├── nextauth.ts       # NextAuth.js session handling
│   └── credentials.ts    # Credential validation and guidance
├── cli/
│   ├── index.ts          # Commander program wiring
│   ├── commands/         # login, news, schedule, courses, profile, health, serve
│   └── formatters/       # Human-readable output formatters
└── mcp/
    └── server.ts         # MCP server (28 tools, 4 resources)

Entwicklung

Skripte

pnpm run build   # Build (esbuild bundle + tsc type declarations)
pnpm run dev     # Watch mode
pnpm run start   # Start MCP server
pnpm run lint    # Lint
pnpm run format  # Format

Sicherheitshinweise

• CLI-Cookies werden unter ~/.nlobby/session gespeichert (im Klartext — schützen Sie diese entsprechend)

• Der MCP-Modus hält alle Authentifizierungs-Token nur im Arbeitsspeicher

• Browser-Automatisierung wird nur zur Authentifizierung verwendet, nicht zum Data Scraping

• Es werden keine sensiblen Daten protokolliert

Lizenz

Dieses Projekt ist unter der MIT-Lizenz lizenziert — siehe die Datei LICENSE für Details.