@udondan/dsbmobile 1.1.0

package/dist/tools/substitutions.js

@@ -0,0 +1,164 @@
+import { z } from 'zod';
+import { CHARACTER_LIMIT, ENV_CLASS } from '../constants.js';
+/**
+ * Registers the get_substitutions tool with the MCP server.
+ *
+ * This tool fetches and parses the actual substitution plan HTML pages,
+ * returning structured substitution entries grouped by class.
+ */
+export function registerSubstitutionsTool(server, client) {
+    server.registerTool('get_substitutions', {
+        title: 'Get DSBmobile Substitution Entries',
+        description: `Fetches and parses the actual substitution plan (Vertretungsplan) pages from DSBmobile,
+returning structured substitution entries for each class.
+
+Returns a list of substitution plans (one per page), each containing:
+- title: Plan name (e.g., "V-Homepage heute - subst_001 (Seite 1)")
+- planDate: Date shown on the plan (e.g., "20.3.2026 Freitag (Seite 1 / 8)")
+- lastUpdated: When the plan was last updated
+- affectedClasses: Comma-separated list of affected class names
+- entries: Array of substitution entries, each with:
+  - className: The class (e.g., "05b", "Q2_Kra")
+  - type: Substitution type (e.g., "Vertretung", "Statt-Vertretung", "Entfall")
+  - period: Lesson period(s) (e.g., "3" or "5 - 6")
+  - originalTeacher: Abbreviation of the absent teacher
+  - substituteTeacher: Abbreviation of the substitute teacher
+  - subject: Subject abbreviation (e.g., "SPO", "ETHI", "E")
+  - originalRoom: Original room
+  - substituteRoom: Substitute room
+  - text: Additional notes
+
+Use this tool when:
+- A user asks "Do I have any substitutions today?"
+- A user wants to know which teacher is substituting for whom
+- A user asks "Is lesson X cancelled?"
+- A user wants to filter substitutions by class name
+
+This tool downloads and parses all plan pages, which may take a few seconds.
+For just the list of plan URLs, use get_timetables instead.
+
+The className parameter is optional. If omitted, the DSB_CLASS environment variable
+is used as the default filter. If neither is set, all classes are returned.
+
+Error handling:
+- Returns an error message if authentication fails (check DSB_USERNAME and DSB_PASSWORD)
+- Returns an error message if the DSBmobile service is unavailable`,
+        inputSchema: z.object({
+            className: z
+                .string()
+                .optional()
+                .describe(`Optional: filter results to a specific class name (e.g. '05b', 'Q2_Kra'). Case-insensitive. Defaults to the DSB_CLASS environment variable if set.`),
+        }),
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
+    }, async ({ className }) => {
+        try {
+            const plans = await client.getSubstitutions();
+            // Use the provided className, fall back to DSB_CLASS env var, or show all
+            const effectiveClass = className ?? process.env[ENV_CLASS];
+            if (plans.length === 0) {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: 'Aktuell sind keine Vertretungspläne auf DSBmobile verfügbar.',
+                        },
+                    ],
+                };
+            }
+            // Apply class filter if provided (explicit param takes priority over env var)
+            const filter = effectiveClass?.toLowerCase();
+            const filtered = filter
+                ? plans.map((plan) => ({
+                    ...plan,
+                    entries: plan.entries.filter((entry) => entry.className.toLowerCase().includes(filter)),
+                }))
+                : plans;
+            const totalEntries = filtered.reduce((sum, p) => sum + p.entries.length, 0);
+            if (filter && totalEntries === 0) {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `Keine Vertretungen für Klasse "${effectiveClass}" gefunden.`,
+                        },
+                    ],
+                };
+            }
+            const output = {
+                planCount: filtered.length,
+                totalEntries,
+                plans: filtered,
+            };
+            const text = formatSubstitutions(filtered, effectiveClass);
+            const finalText = text.length > CHARACTER_LIMIT
+                ? text.slice(0, CHARACTER_LIMIT) +
+                    '\n\n[Response truncated. Use the className filter to narrow results.]'
+                : text;
+            return {
+                content: [{ type: 'text', text: finalText }],
+                structuredContent: output,
+            };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : 'An unexpected error occurred.';
+            return {
+                content: [{ type: 'text', text: message }],
+                isError: true,
+            };
+        }
+    });
+}
+/**
+ * Formats substitution plans as human-readable markdown.
+ */
+function formatSubstitutions(plans, filter) {
+    const lines = [];
+    const totalEntries = plans.reduce((sum, p) => sum + p.entries.length, 0);
+    const heading = filter
+        ? `# Substitutions for class "${filter}" (${totalEntries} entries)`
+        : `# DSBmobile Substitution Plans (${totalEntries} total entries)`;
+    lines.push(heading, '');
+    for (const plan of plans) {
+        if (plan.entries.length === 0)
+            continue;
+        lines.push(`## ${plan.title}`, `**Date**: ${plan.planDate}`, `**Last Updated**: ${plan.lastUpdated}`);
+        if (plan.affectedClasses) {
+            lines.push(`**Affected Classes**: ${plan.affectedClasses}`);
+        }
+        lines.push('');
+        // Group entries by class
+        const byClass = new Map();
+        for (const entry of plan.entries) {
+            const list = byClass.get(entry.className) ?? [];
+            list.push(entry);
+            byClass.set(entry.className, list);
+        }
+        for (const [cls, entries] of byClass) {
+            lines.push(`### Class ${cls}`);
+            for (const substitution of entries) {
+                const teacher = substitution.originalTeacher && substitution.substituteTeacher
+                    ? `${substitution.originalTeacher} → ${substitution.substituteTeacher}`
+                    : substitution.substituteTeacher || substitution.originalTeacher;
+                const room = substitution.originalRoom && substitution.substituteRoom
+                    ? `${substitution.originalRoom} → ${substitution.substituteRoom}`
+                    : substitution.substituteRoom || substitution.originalRoom;
+                const parts = [
+                    `**${substitution.type}**`,
+                    `Period ${substitution.period}`,
+                    substitution.subject && `Subject: ${substitution.subject}`,
+                    teacher && `Teacher: ${teacher}`,
+                    room && `Room: ${room}`,
+                    substitution.text && `Note: ${substitution.text}`,
+                ].filter(Boolean);
+                lines.push(`- ${parts.join(' | ')}`);
+            }
+            lines.push('');
+        }
+    }
+    return lines.join('\n');
+}

package/dist/tools/timetables.d.ts

@@ -0,0 +1,9 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { DsbmobileClient } from '../services/dsbmobile.js';
+/**
+ * Registers the get_timetables tool with the MCP server.
+ *
+ * This tool retrieves all available substitution plan (Vertretungsplan) entries
+ * from DSBmobile, including URLs to the HTML plan pages.
+ */
+export declare function registerTimetablesTool(server: McpServer, client: DsbmobileClient): void;

package/dist/tools/timetables.js

@@ -0,0 +1,91 @@
+import { z } from 'zod';
+import { CHARACTER_LIMIT } from '../constants.js';
+/**
+ * Registers the get_timetables tool with the MCP server.
+ *
+ * This tool retrieves all available substitution plan (Vertretungsplan) entries
+ * from DSBmobile, including URLs to the HTML plan pages.
+ */
+export function registerTimetablesTool(server, client) {
+    server.registerTool('get_timetables', {
+        title: 'Get DSBmobile Substitution Plans',
+        description: `Retrieves all available substitution plan (Vertretungsplan) entries from DSBmobile.
+
+Returns a list of substitution plan entries, each with:
+- id: Unique identifier for the plan entry
+- title: Plan name (e.g., "Vertretungen-heute" for today's substitutions)
+- date: Last updated timestamp in DD.MM.YYYY HH:MM format
+- url: URL to the HTML page containing the actual substitution plan table
+- previewUrl: URL to a preview image of the plan (optional)
+
+The substitution plan HTML pages contain the detailed schedule showing which
+classes have substitutions, which teachers are replaced, which rooms are used, etc.
+The HTML format varies by school, so the URL is returned for further processing.
+
+Use this tool when:
+- A user asks "Do I have any substitutions today?"
+- A user wants to check the school's substitution schedule
+- A user asks about teacher absences or room changes
+
+Returns "No substitution plans available" if no plans are currently published.
+
+Error handling:
+- Returns an error message if authentication fails (check DSB_USERNAME and DSB_PASSWORD)
+- Returns an error message if the DSBmobile service is unavailable`,
+        inputSchema: z.object({}).strict(),
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
+    }, async () => {
+        try {
+            const entries = await client.getTimetables();
+            if (entries.length === 0) {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: 'Aktuell sind keine Vertretungspläne auf DSBmobile verfügbar.',
+                        },
+                    ],
+                };
+            }
+            const output = {
+                count: entries.length,
+                timetables: entries,
+            };
+            const text = formatTimetables(entries);
+            const finalText = text.length > CHARACTER_LIMIT
+                ? text.slice(0, CHARACTER_LIMIT) +
+                    '\n\n[Response truncated. Use the plan URLs to access the full content.]'
+                : text;
+            return {
+                content: [{ type: 'text', text: finalText }],
+                structuredContent: output,
+            };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : 'An unexpected error occurred.';
+            return {
+                content: [{ type: 'text', text: message }],
+                isError: true,
+            };
+        }
+    });
+}
+/**
+ * Formats timetable entries as human-readable markdown.
+ */
+function formatTimetables(entries) {
+    const lines = [`# DSBmobile Substitution Plans (${entries.length} available)`, ''];
+    for (const entry of entries) {
+        lines.push(`## ${entry.title}`, `- **ID**: ${entry.id}`, `- **Last Updated**: ${entry.date}`, `- **Plan URL**: ${entry.url}`);
+        if (entry.previewUrl) {
+            lines.push(`- **Preview**: ${entry.previewUrl}`);
+        }
+        lines.push('');
+    }
+    return lines.join('\n');
+}

package/dist/types.d.ts

@@ -0,0 +1,106 @@
+/**
+ * TypeScript interfaces for DSBmobile API data structures
+ */
+/**
+ * Raw item structure returned by the DSBmobile API.
+ * ConType determines how data is encoded:
+ * - 2: Data is in Childs array (nested items)
+ * - 4: Detail contains a link to an HTML web page
+ * - 5: Detail contains plain text
+ * - 6: Detail contains a link to an image/file
+ */
+export interface DsbItem {
+    Id: string;
+    Date: string;
+    Title: string;
+    Detail: string;
+    Tags: string;
+    ConType: number;
+    Prio: number;
+    Index: number;
+    Childs: DsbItem[];
+    Preview: string;
+}
+/**
+ * A processed timetable/substitution plan entry
+ */
+export interface TimetableEntry {
+    /** Unique identifier */
+    id: string;
+    /** Plan name (e.g., "Vertretungen-heute") */
+    title: string;
+    /** Last updated date in DD.MM.YYYY HH:MM format */
+    date: string;
+    /** URL to the HTML plan page */
+    url: string;
+    /** URL to the preview image (if available) */
+    previewUrl?: string;
+}
+/**
+ * A processed news/announcement entry
+ */
+export interface NewsEntry {
+    /** Unique identifier */
+    id: string;
+    /** News headline */
+    title: string;
+    /** News content or URL */
+    detail: string;
+    /** Publication date in DD.MM.YYYY HH:MM format */
+    date: string;
+    /** Associated tags */
+    tags: string;
+}
+/**
+ * A single substitution entry parsed from a timetable HTML page
+ */
+export interface SubstitutionEntry {
+    /** Class name (e.g., "05b") */
+    className: string;
+    /** Type of substitution (e.g., "Vertretung", "Statt-Vertretung", "Entfall") */
+    type: string;
+    /** Lesson period(s) (e.g., "3" or "5 - 6") */
+    period: string;
+    /** Original teacher abbreviation */
+    originalTeacher: string;
+    /** Substitute teacher abbreviation */
+    substituteTeacher: string;
+    /** Subject */
+    subject: string;
+    /** Original room */
+    originalRoom: string;
+    /** Substitute room */
+    substituteRoom: string;
+    /** Additional notes */
+    text: string;
+}
+/**
+ * A fully parsed substitution plan page
+ */
+export interface SubstitutionPlan {
+    /** Plan title including date (e.g., "V-Homepage heute - subst_001") */
+    title: string;
+    /** Date string from the plan (e.g., "20.3.2026 Freitag (Seite 1 / 8)") */
+    planDate: string;
+    /** Last updated timestamp */
+    lastUpdated: string;
+    /** URL the plan was fetched from */
+    url: string;
+    /** Affected classes */
+    affectedClasses: string;
+    /** All substitution entries */
+    entries: SubstitutionEntry[];
+}
+/**
+ * A processed document entry
+ */
+export interface DocumentEntry {
+    /** Unique identifier */
+    id: string;
+    /** Document name */
+    title: string;
+    /** Download URL */
+    url: string;
+    /** Upload date in DD.MM.YYYY HH:MM format */
+    date: string;
+}

package/dist/types.js

@@ -0,0 +1,4 @@
+/**
+ * TypeScript interfaces for DSBmobile API data structures
+ */
+export {};

package/dist/utils/errors.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Converts an API error into a human-readable, actionable error message.
+ * Credentials are never included in error messages.
+ */
+export declare function handleApiError(error: unknown): string;
+/**
+ * Creates an error message for authentication failure (empty token response).
+ */
+export declare function createAuthError(): string;

package/dist/utils/errors.js

@@ -0,0 +1,50 @@
+import { AxiosError } from 'axios';
+/**
+ * Converts an API error into a human-readable, actionable error message.
+ * Credentials are never included in error messages.
+ */
+export function handleApiError(error) {
+    if (error instanceof AxiosError) {
+        if (error.response) {
+            switch (error.response.status) {
+                case 401: {
+                    return 'Error: Authentication failed. Please verify your credentials are correct.';
+                }
+                case 403: {
+                    return 'Error: Access denied. Your account may not have permission to access this resource.';
+                }
+                case 404: {
+                    return 'Error: Resource not found. The DSBmobile API endpoint may have changed.';
+                }
+                case 429: {
+                    return 'Error: Rate limit exceeded. Please wait a moment before making more requests.';
+                }
+                case 500:
+                case 502:
+                case 503:
+                case 504: {
+                    return 'Error: DSBmobile service is temporarily unavailable. Please try again later.';
+                }
+                default: {
+                    return `Error: API request failed with status ${error.response.status}. Please try again.`;
+                }
+            }
+        }
+        else if (error.code === 'ECONNABORTED' || error.code === 'ETIMEDOUT') {
+            return 'Error: Request timed out. The DSBmobile service may be slow or unavailable. Please try again.';
+        }
+        else if (error.code === 'ENOTFOUND' || error.code === 'ECONNREFUSED') {
+            return 'Error: Cannot connect to DSBmobile. Please check your internet connection and try again.';
+        }
+    }
+    if (error instanceof Error) {
+        return `Error: ${error.message}`;
+    }
+    return 'Error: An unexpected error occurred. Please try again.';
+}
+/**
+ * Creates an error message for authentication failure (empty token response).
+ */
+export function createAuthError() {
+    return 'Error: Authentication failed. DSBmobile rejected the provided credentials. Please verify your credentials are correct.';
+}

package/package.json

@@ -0,0 +1,82 @@
+{
+  "name": "@udondan/dsbmobile",
+  "version": "1.1.0",
+  "description": "SDK, CLI, and MCP server for DSBmobile — access German school substitution plans (Vertretungspläne)",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/udondan/dsbmobile-mcp.git"
+  },
+  "author": {
+    "name": "Daniel Schroeder",
+    "email": "deemes79@googlemail.com",
+    "url": "https://udondan.com/"
+  },
+  "license": "MIT",
+  "funding": {
+    "type": "github",
+    "url": "https://github.com/sponsors/udondan"
+  },
+  "keywords": [
+    "mcp",
+    "mcp-server",
+    "cli",
+    "sdk",
+    "dsbmobile",
+    "vertretungsplan",
+    "school",
+    "substitution-plan"
+  ],
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "dsbmobile": "dist/cli.js"
+  },
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "start": "node dist/cli.js mcp",
+    "pretest": "tsc",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit -p tsconfig.lint.json",
+    "lint": "eslint src/ tests/",
+    "lint:fix": "eslint --fix src/ tests/",
+    "format": "prettier --write src/ tests/",
+    "format:check": "prettier --check src/ tests/",
+    "markdownlint": "markdownlint-cli2 '**/*.md' '#node_modules' '#.claude' '#.vibe' '#CHANGELOG.md'"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "1.29.0",
+    "axios": "1.16.1",
+    "commander": "14.0.3",
+    "zod": "4.4.3"
+  },
+  "devDependencies": {
+    "@eslint/js": "10.0.1",
+    "@modelcontextprotocol/inspector": "0.21.2",
+    "@types/node": "22.0.0",
+    "eslint": "10.4.0",
+    "eslint-config-prettier": "10.1.8",
+    "eslint-plugin-prettier": "5.5.5",
+    "eslint-plugin-unicorn": "64.0.0",
+    "prettier": "3.8.3",
+    "typescript": "6.0.3",
+    "typescript-eslint": "8.59.4",
+    "markdownlint-cli2": "0.22.1",
+    "vitest": "4.1.7"
+  }
+}