@udondan/dsbmobile 1.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Daniel Schroeder
+
+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.

package/README.md

@@ -0,0 +1,251 @@
+# @udondan/dsbmobile
+
+Node.js-Paket für den Zugriff auf [DSBmobile](https://www.dsbmobile.de) – die digitale Schulkommunikationsplattform für Vertretungspläne, Neuigkeiten und Dokumente. Es kapselt die DSBmobile-API und bietet drei Schnittstellen über einen gemeinsamen Kern:
+
+- **SDK** – importierbare `DsbmobileClient`-Klasse für Node.js-Projekte
+- **CLI** – `dsbmobile`-Befehl für das Terminal
+- **MCP-Server** – `dsbmobile mcp` stellt alle Funktionen als Tools für KI-Assistenten bereit
+
+## Inhalt
+
+- [Installation](#installation)
+- [Konfiguration](#konfiguration)
+- [SDK](#sdk)
+- [CLI](#cli)
+- [MCP-Server](#mcp-server)
+- [Verfügbare MCP-Tools](#verfügbare-mcp-tools)
+- [Entwicklung](#entwicklung)
+- [Lizenz](#lizenz)
+
+## Installation
+
+```bash
+# Globale Installation (empfohlen für CLI-Nutzung)
+npm install -g @udondan/dsbmobile
+
+# Ohne Installation direkt nutzen
+DSB_USERNAME=benutzername DSB_PASSWORD=passwort npx @udondan/dsbmobile mcp
+```
+
+## Konfiguration
+
+Die Zugangsdaten werden über Umgebungsvariablen übergeben:
+
+| Variable       | Pflicht | Beschreibung                                                                                        |
+| -------------- | ------- | --------------------------------------------------------------------------------------------------- |
+| `DSB_USERNAME` | ✅      | DSBmobile-Benutzername bzw. -ID                                                                     |
+| `DSB_PASSWORD` | ✅      | DSBmobile-Passwort                                                                                  |
+| `DSB_CLASS`    | ❌      | Standard-Klassenfilter für `get_substitutions` (z. B. `07b`). Kann pro Aufruf überschrieben werden. |
+
+## SDK
+
+```bash
+npm install @udondan/dsbmobile
+```
+
+```ts
+import { DsbmobileClient } from '@udondan/dsbmobile';
+
+const client = new DsbmobileClient({
+  username: process.env.DSB_USERNAME!,
+  password: process.env.DSB_PASSWORD!,
+});
+
+// Vertretungsplan abrufen
+const plans = await client.getSubstitutions();
+
+// Timetable-Einträge (Plan-URLs) abrufen
+const timetables = await client.getTimetables();
+
+// Neuigkeiten abrufen
+const news = await client.getNews();
+
+// Dokumente abrufen
+const documents = await client.getDocuments();
+```
+
+### Exportierte Typen
+
+```ts
+import type {
+  DsbmobileConfig,
+  SubstitutionPlan,
+  SubstitutionEntry,
+  TimetableEntry,
+  NewsEntry,
+  DocumentEntry,
+  DsbItem,
+} from '@udondan/dsbmobile';
+```
+
+## CLI
+
+```bash
+# Vertretungspläne als JSON ausgeben
+dsbmobile substitutions
+
+# Nur eine bestimmte Klasse (überschreibt DSB_CLASS)
+dsbmobile substitutions --class 07b
+
+# Timetable-Einträge (Plan-URLs) als JSON ausgeben
+dsbmobile timetables
+
+# Neuigkeiten als JSON ausgeben
+dsbmobile news
+
+# Dokumente als JSON ausgeben
+dsbmobile documents
+
+# MCP-Server über stdio starten
+dsbmobile mcp
+```
+
+## MCP-Server
+
+### Einrichtung in Claude Code
+
+```bash
+claude mcp add dsbmobile -- npx @udondan/dsbmobile mcp
+```
+
+Anschließend die Zugangsdaten in der MCP-Konfiguration hinterlegen (`~/.claude.json` oder `.claude/settings.json`):
+
+```json
+{
+  "mcpServers": {
+    "dsbmobile": {
+      "command": "npx",
+      "args": ["@udondan/dsbmobile", "mcp"],
+      "env": {
+        "DSB_USERNAME": "benutzername",
+        "DSB_PASSWORD": "passwort",
+        "DSB_CLASS": "07b"
+      }
+    }
+  }
+}
+```
+
+### Einrichtung in Claude Desktop
+
+**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "dsbmobile": {
+      "command": "npx",
+      "args": ["@udondan/dsbmobile", "mcp"],
+      "env": {
+        "DSB_USERNAME": "benutzername",
+        "DSB_PASSWORD": "passwort",
+        "DSB_CLASS": "07b"
+      }
+    }
+  }
+}
+```
+
+### Einrichtung in anderen MCP-Clients
+
+```json
+{
+  "command": "npx",
+  "args": ["@udondan/dsbmobile", "mcp"],
+  "env": {
+    "DSB_USERNAME": "benutzername",
+    "DSB_PASSWORD": "passwort",
+    "DSB_CLASS": "07b"
+  }
+}
+```
+
+## Verfügbare MCP-Tools
+
+### `get_timetables`
+
+Gibt alle verfügbaren Vertretungsplan-Einträge zurück.
+
+**Rückgabe**: Liste von Plan-Einträgen, jeweils mit:
+
+- `id`: Eindeutige ID
+- `title`: Planname (z. B. „V-Homepage heute - subst_001 (Seite 1)")
+- `date`: Zeitstempel der letzten Aktualisierung im Format `TT.MM.JJJJ HH:MM`
+- `url`: Link zur HTML-Planseite mit der Vertretungstabelle
+- `previewUrl`: Link zu einem Vorschaubild (optional)
+
+### `get_substitutions`
+
+Lädt und parst alle Vertretungsplan-Seiten und gibt strukturierte Einträge zurück.
+
+**Parameter**:
+
+- `className` (optional): Klassenfilter, z. B. `07b` oder `Q2_Kra`. Groß-/Kleinschreibung wird ignoriert. Standardmäßig wird `DSB_CLASS` verwendet, falls gesetzt.
+
+**Rückgabe**: Liste von Plänen, jeweils mit:
+
+- `title`: Planname
+- `planDate`: Datum laut Plan (z. B. „20.3.2026 Freitag (Seite 1 / 8)")
+- `lastUpdated`: Zeitstempel der letzten Aktualisierung
+- `affectedClasses`: Kommagetrennte Liste betroffener Klassen
+- `entries`: Liste der Vertretungseinträge, jeweils mit:
+  - `className`: Klasse (z. B. `07b`, `Q2_Kra`)
+  - `type`: Art der Vertretung (z. B. `Vertretung`, `Statt-Vertretung`, `Entfall`)
+  - `period`: Stunde(n) (z. B. `3` oder `5 - 6`)
+  - `originalTeacher`: Kürzel der vertretenen Lehrkraft
+  - `substituteTeacher`: Kürzel der vertretenden Lehrkraft
+  - `subject`: Fachkürzel (z. B. `SPO`, `ETHI`, `E`)
+  - `originalRoom`: Ursprünglicher Raum
+  - `substituteRoom`: Ausweichraum
+  - `text`: Zusätzliche Hinweise
+
+### `get_news`
+
+Ruft alle Neuigkeiten und Ankündigungen von DSBmobile ab.
+
+**Rückgabe**: Liste von Nachrichten, jeweils mit `id`, `title`, `detail`, `date`, `tags`.
+
+### `get_documents`
+
+Listet alle verfügbaren Dokumente und Dateien auf.
+
+**Rückgabe**: Liste von Dokumenten, jeweils mit `id`, `title`, `url`, `date`.
+
+## Sicherheit
+
+- **CLI und MCP-Server**: Zugangsdaten werden ausschließlich über Umgebungsvariablen übergeben und nie im Code hinterlegt
+- **SDK**: Zugangsdaten werden explizit als `DsbmobileConfig`-Objekt im Konstruktor übergeben – nie hartcodiert oder aus Umgebungsvariablen gelesen
+- Zugangsdaten erscheinen weder in Logs noch in Fehlermeldungen
+- Es werden keine sensiblen Daten auf der Festplatte gespeichert
+- Der Server ist schreibgeschützt – er kann keine Daten auf DSBmobile verändern
+
+## Entwicklung
+
+```bash
+# Repository klonen
+git clone https://github.com/udondan/dsbmobile-mcp.git
+cd dsbmobile-mcp
+
+# Abhängigkeiten installieren
+bun install
+
+# TypeScript kompilieren
+bun run build
+
+# Im Watch-Modus kompilieren
+bun run dev
+
+# MCP-Server starten
+DSB_USERNAME=benutzername DSB_PASSWORD=passwort node dist/cli.js mcp
+
+# Tests ausführen
+bun run test
+
+# Lint
+bun run lint
+```
+
+## Lizenz
+
+MIT

package/dist/cli.d.ts

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+/**
+ * DSBmobile CLI
+ *
+ * Usage:
+ *   dsbmobile mcp                           Start the MCP server (stdio)
+ *   dsbmobile substitutions [--class name]  Fetch substitution plans as JSON
+ *   dsbmobile timetables                    Fetch timetable entries as JSON
+ *   dsbmobile news                          Fetch news entries as JSON
+ *   dsbmobile documents                     Fetch documents as JSON
+ *
+ * Environment variables:
+ *   DSB_USERNAME   DSBmobile username/ID (required)
+ *   DSB_PASSWORD   DSBmobile password (required)
+ *   DSB_CLASS      Default class filter for substitutions (optional)
+ */
+export {};

package/dist/cli.js

@@ -0,0 +1,94 @@
+#!/usr/bin/env node
+/**
+ * DSBmobile CLI
+ *
+ * Usage:
+ *   dsbmobile mcp                           Start the MCP server (stdio)
+ *   dsbmobile substitutions [--class name]  Fetch substitution plans as JSON
+ *   dsbmobile timetables                    Fetch timetable entries as JSON
+ *   dsbmobile news                          Fetch news entries as JSON
+ *   dsbmobile documents                     Fetch documents as JSON
+ *
+ * Environment variables:
+ *   DSB_USERNAME   DSBmobile username/ID (required)
+ *   DSB_PASSWORD   DSBmobile password (required)
+ *   DSB_CLASS      Default class filter for substitutions (optional)
+ */
+import { createRequire } from 'node:module';
+import { Command } from 'commander';
+import { DsbmobileClient } from './services/dsbmobile.js';
+import { startMcpServer } from './mcp.js';
+import { ENV_CLASS, ENV_PASSWORD, ENV_USERNAME } from './constants.js';
+const { version } = createRequire(import.meta.url)('../package.json');
+function loadClient() {
+    const username = process.env[ENV_USERNAME];
+    const password = process.env[ENV_PASSWORD];
+    const missing = [!username && ENV_USERNAME, !password && ENV_PASSWORD].filter((v) => typeof v === 'string');
+    if (missing.length > 0) {
+        console.error(`Error: Required environment variables not set: ${missing.join(', ')}\n` +
+            `  export ${ENV_USERNAME}=your_username\n` +
+            `  export ${ENV_PASSWORD}=your_password`);
+        process.exit(1);
+    }
+    return new DsbmobileClient({ username: username, password: password });
+}
+function print(data) {
+    console.log(JSON.stringify(data, undefined, 2));
+}
+const program = new Command();
+program
+    .name('dsbmobile')
+    .description('CLI and MCP server for DSBmobile — access German school substitution plans')
+    .version(version);
+program
+    .command('mcp')
+    .description('Start the DSBmobile MCP server over stdio')
+    .action(async () => {
+    const client = loadClient();
+    await startMcpServer(client);
+});
+program
+    .command('substitutions')
+    .description('Fetch substitution plans (Vertretungspläne) as JSON')
+    .option('--class <name>', `Filter by class name (e.g. 05b). Defaults to ${ENV_CLASS} env var.`)
+    .action(async (options) => {
+    const client = loadClient();
+    const plans = await client.getSubstitutions();
+    const filter = (options.class ?? process.env[ENV_CLASS])?.toLowerCase();
+    const result = filter
+        ? plans.map((plan) => ({
+            ...plan,
+            entries: plan.entries.filter((entry) => entry.className.toLowerCase().includes(filter)),
+        }))
+        : plans;
+    print(result);
+});
+program
+    .command('timetables')
+    .description('Fetch timetable entries (plan URLs) as JSON')
+    .action(async () => {
+    const client = loadClient();
+    print(await client.getTimetables());
+});
+program
+    .command('news')
+    .description('Fetch news and announcements as JSON')
+    .action(async () => {
+    const client = loadClient();
+    print(await client.getNews());
+});
+program
+    .command('documents')
+    .description('Fetch available documents as JSON')
+    .action(async () => {
+    const client = loadClient();
+    print(await client.getDocuments());
+});
+try {
+    await program.parseAsync(process.argv);
+}
+catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(message.startsWith('Error:') ? message : `Error: ${message}`);
+    process.exit(1);
+}

package/dist/constants.d.ts

@@ -0,0 +1,21 @@
+/**
+ * DSBmobile API constants
+ */
+/** Base URL for the DSBmobile Mobile API */
+export declare const DSB_API_BASE_URL = "https://mobileapi.dsbcontrol.de";
+/** Bundle ID used to identify the DSBmobile app */
+export declare const DSB_BUNDLE_ID = "de.heinekingmedia.dsbmobile";
+/** DSBmobile app version to report */
+export declare const DSB_APP_VERSION = "35";
+/** OS version to report (Android API level) */
+export declare const DSB_OS_VERSION = "22";
+/** Request timeout in milliseconds */
+export declare const REQUEST_TIMEOUT_MS = 30000;
+/** Maximum response size in characters before truncation */
+export declare const CHARACTER_LIMIT = 25000;
+/** Environment variable name for DSBmobile username */
+export declare const ENV_USERNAME = "DSB_USERNAME";
+/** Environment variable name for DSBmobile password */
+export declare const ENV_PASSWORD = "DSB_PASSWORD";
+/** Environment variable name for the default class filter */
+export declare const ENV_CLASS = "DSB_CLASS";

package/dist/constants.js

@@ -0,0 +1,21 @@
+/**
+ * DSBmobile API constants
+ */
+/** Base URL for the DSBmobile Mobile API */
+export const DSB_API_BASE_URL = 'https://mobileapi.dsbcontrol.de';
+/** Bundle ID used to identify the DSBmobile app */
+export const DSB_BUNDLE_ID = 'de.heinekingmedia.dsbmobile';
+/** DSBmobile app version to report */
+export const DSB_APP_VERSION = '35';
+/** OS version to report (Android API level) */
+export const DSB_OS_VERSION = '22';
+/** Request timeout in milliseconds */
+export const REQUEST_TIMEOUT_MS = 30_000;
+/** Maximum response size in characters before truncation */
+export const CHARACTER_LIMIT = 25_000;
+/** Environment variable name for DSBmobile username */
+export const ENV_USERNAME = 'DSB_USERNAME';
+/** Environment variable name for DSBmobile password */
+export const ENV_PASSWORD = 'DSB_PASSWORD';
+/** Environment variable name for the default class filter */
+export const ENV_CLASS = 'DSB_CLASS';

package/dist/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * @udondan/dsbmobile — SDK entry point.
+ *
+ * @example
+ * ```ts
+ * import { DsbmobileClient } from '@udondan/dsbmobile';
+ *
+ * const client = new DsbmobileClient({ username: 'user', password: 'pass' });
+ * const substitutions = await client.getSubstitutions();
+ * ```
+ */
+export { DsbmobileClient, parseSubstitutionHtml } from './services/dsbmobile.js';
+export type { DsbmobileConfig } from './services/dsbmobile.js';
+export type { DsbItem, TimetableEntry, NewsEntry, SubstitutionEntry, SubstitutionPlan, DocumentEntry, } from './types.js';

package/dist/index.js

@@ -0,0 +1,12 @@
+/**
+ * @udondan/dsbmobile — SDK entry point.
+ *
+ * @example
+ * ```ts
+ * import { DsbmobileClient } from '@udondan/dsbmobile';
+ *
+ * const client = new DsbmobileClient({ username: 'user', password: 'pass' });
+ * const substitutions = await client.getSubstitutions();
+ * ```
+ */
+export { DsbmobileClient, parseSubstitutionHtml } from './services/dsbmobile.js';

package/dist/mcp.d.ts

@@ -0,0 +1,2 @@
+import type { DsbmobileClient } from './services/dsbmobile.js';
+export declare function startMcpServer(client: DsbmobileClient): Promise<void>;

package/dist/mcp.js

@@ -0,0 +1,18 @@
+import { createRequire } from 'node:module';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { registerDocumentsTool } from './tools/documents.js';
+import { registerNewsTool } from './tools/news.js';
+import { registerSubstitutionsTool } from './tools/substitutions.js';
+import { registerTimetablesTool } from './tools/timetables.js';
+const { version } = createRequire(import.meta.url)('../package.json');
+export async function startMcpServer(client) {
+    const server = new McpServer({ name: 'dsbmobile', version });
+    registerTimetablesTool(server, client);
+    registerSubstitutionsTool(server, client);
+    registerNewsTool(server, client);
+    registerDocumentsTool(server, client);
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error('DSBmobile MCP server running via stdio');
+}

package/dist/services/dsbmobile.d.ts

@@ -0,0 +1,81 @@
+import type { DocumentEntry, NewsEntry, SubstitutionPlan, TimetableEntry } from '../types.js';
+export interface DsbmobileConfig {
+    username: string;
+    password: string;
+}
+/**
+ * Client for the DSBmobile Mobile API.
+ *
+ * Accepts explicit credentials via {@link DsbmobileConfig} and provides
+ * methods to fetch timetables, news, documents, and substitution plans.
+ *
+ * The authentication token is cached in memory for the session lifetime.
+ */
+export declare class DsbmobileClient {
+    private readonly username;
+    private readonly password;
+    private readonly http;
+    private token;
+    constructor(config: DsbmobileConfig);
+    /**
+     * Authenticates with DSBmobile and caches the token.
+     * The token is stable per username, so it can be cached indefinitely.
+     *
+     * @throws Error if credentials are invalid or the request fails
+     */
+    private authenticate;
+    /**
+     * Ensures a valid token is available, authenticating if necessary.
+     */
+    private ensureAuthenticated;
+    /**
+     * Fetches all available substitution plan (Vertretungsplan) entries.
+     *
+     * @returns Array of timetable entries with URLs to HTML plan pages
+     * @throws Error if authentication fails or the request fails
+     */
+    getTimetables(): Promise<TimetableEntry[]>;
+    /**
+     * Fetches all news and announcements.
+     *
+     * @returns Array of news entries
+     * @throws Error if authentication fails or the request fails
+     */
+    getNews(): Promise<NewsEntry[]>;
+    /**
+     * Fetches all available documents.
+     *
+     * @returns Array of document entries with download URLs
+     * @throws Error if authentication fails or the request fails
+     */
+    getDocuments(): Promise<DocumentEntry[]>;
+    /**
+     * Parses raw DSBmobile timetable items into structured TimetableEntry objects.
+     * Timetables have ConType=2 with children that contain the actual plan URLs.
+     * The parent item holds the descriptive title; children are individual pages.
+     */
+    private parseTimetables;
+    /**
+     * Parses raw DSBmobile news items into structured NewsEntry objects.
+     */
+    private parseNews;
+    /**
+     * Fetches and parses all substitution plan pages, returning structured entries.
+     * This fetches the actual HTML content of each timetable page and parses the
+     * substitution table into structured data.
+     *
+     * @returns Array of parsed substitution plans (one per HTML page)
+     * @throws Error if authentication fails or the request fails
+     */
+    getSubstitutions(): Promise<SubstitutionPlan[]>;
+    /**
+     * Parses raw DSBmobile document items into structured DocumentEntry objects.
+     */
+    private parseDocuments;
+}
+/**
+ * Parses the HTML content of a DSBmobile substitution plan page.
+ * The HTML is generated by Untis and has a consistent structure.
+ * Exported for unit testing.
+ */
+export declare function parseSubstitutionHtml(html: string, title: string, lastUpdated: string, url: string): SubstitutionPlan;