KI-Studentenentwickler-Assistent – MCP-Server

Ein produktionsreifer Model Context Protocol-Server, der einem KI-Assistenten einheitlichen Zugriff auf Ihre GitHub-Issues, Ihre akademischen Fristen (LMS) und einen persönlichen Aufgaben-Tracker bietet – sodass er Fragen wie „Was sollte ich heute arbeiten?“ mit einer echten, priorisierten Antwort beantworten kann.

Erstellt mit Python 3.12+, dem offiziellen MCP Python SDK (v2), FastAPI-ähnlicher Diensttrennung, SQLite und httpx. Vollständig getestet mit gemockten externen APIs – keine echten Anmeldeinformationen erforderlich, um die Suite auszuführen.

Inhaltsverzeichnis

• Projektübersicht

• Funktionen – die MCP-Tools

• Architektur

• Technologie-Stack

• Installation

• Konfiguration

• Server ausführen

• KI-Client verbinden

• Beispielverwendung

• API-Integration

• Datenbank

• Testen

• Sicherheit

• Einschränkungen

• Zukünftige Verbesserungen

• Projektarchitektur

• Demo-Szenario

• Gesprächsthemen für Vorstellungsgespräche

Projektübersicht

Das Problem. Die Arbeit eines Studentenentwicklers lebt an drei voneinander getrennten Orten: Code-Aufgaben in GitHub, Aufgaben und Prüfungen in einem College-LMS und persönliche Todos, die in Notizen verstreut sind. Prioritäten werden aus dem Gedächtnis entschieden, sodass Dinge durchrutschen.

Die Lösung. Ein MCP-Server, der alle drei Quellen als kleine, gut beschriebene, stark typisierte Tools bereitstellt. Ein KI-Assistent liest und denkt über alle gleichzeitig nach: Er kann Ihre zugewiesenen Issues, die Fristen dieser Woche, Ihre anstehenden Aufgaben abrufen, überfällige Elemente erkennen, eine priorisierte Zusammenfassung erstellen – und Systeme mutieren (Issues erstellen/schließen, Aufgaben erstellen, Fristen stapelweise importieren) mit derselben Schnittstelle.

Status. Dies ist eine portfolio-würdige Implementierung eines persönlichen Produktivitätstools. Alles funktioniert durchgängig; die LMS-Integration ist bewusst hinter einer austauschbaren Schnittstelle gemockt (siehe Einschränkungen).

Funktionen – die MCP-Tools

Fünfzehn eng gefasste Tools. Jedes hat einen klaren Namen, eine Beschreibung, die der KI liest, um zu entscheiden, wann es aufgerufen wird, validierte Eingaben und eine vorhersagbare Ausgabe:

GitHub (4 Tools)

LMS / akademische Fristen (3 Tools)

Aufgaben-Tracker (8 Tools)

Alle Tools geben dieselbe JSON-Struktur zurück, sodass ein Agent Ergebnisse zuverlässig parsen kann:

{ "ok": true,  "data": { "...": "..." }, "error": null }
{ "ok": false, "data": null, "error": { "code": "not_found", "message": "..." } }

Architektur

flowchart TB
    subgraph Host["AI Client (e.g. Claude Desktop)"]
        Agent["Assistant / Agent"]
    end
    subgraph MCP["MCP Protocol (stdio)"]
        S["MCPServer (mcp SDK v2)"]
    end
    subgraph App["app/"]
        Tools["tools/ · 15 thin tool functions"]
        Services["services/ · GitHub · LMS · Task"]
        Repo["TaskRepository"]
        DB[("SQLite")]
        Mock["MockLMSService"]
    end
    Ext["GitHub REST API v3"]
    Agent -->|tools/list · tools/call · server/discover| S
    S --> Tools
    Tools --> Services --> Repo --> DB
    Services --> Ext
    Services --> Mock

Die goldene Regel in dieser Codebasis: Die MCP-Schicht ist nur Adapter. Jede Tool-Funktion validiert Eingaben über ihre Typsignatur, ruft einen Dienst auf und gibt das Ergebnis aus. Keine Geschäftslogik lebt in Tool-Funktionen.

Technologie-Stack

Installation

Voraussetzungen: Python 3.12+ und git. (Das MCP SDK selbst benötigt ≥3.10; dieses Projekt zielt auf 3.12.)

Windows (PowerShell)

cd "C:\Users\ASUS\mcp project"
python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
pip install -r requirements.txt

Falls Activate.ps1 durch die Ausführungsrichtlinie blockiert wird:

Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass

macOS / Linux

cd mcp-project
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
pip install -r requirements.txt

Konfiguration

Kopieren Sie die Platzhalterdatei und füllen Sie Ihre Werte ein:

cp .env.example .env     # Windows:  copy .env.example .env

GitHub-Token erstellen → GitHub → Einstellungen → Entwicklereinstellungen → Persönliche Zugriffstoken → Fein abgestimmte Token → Neues Token generieren → nur die benötigten Repositories auswählen → nur Issues: Lesen und Schreiben gewähren.

⚠️ .env ist in git ignoriert. Niemals committen. .env.example enthält nur Platzhalter.

Server ausführen

1. Datenbank initialisieren und Demodaten einspielen

python -m scripts.seed_demo

Dies erstellt data/tasks.db und fügt einige realistische Demo-Aufgaben ein (eine absichtlich überfällig).

2. MCP-Server ausführen

python -m app.server

Der Server startet über stdio (Standard für Desktop-MCP-Clients) und läuft, bis er gestoppt wird.

Entwicklung & Debugging

Das SDK enthält eine CLI und einen interaktiven Inspektor:

mcp dev app/server.py        # launch + open the MCP Inspector in a browser
mcp run app/server.py        # run the server (same behavior as python -m app.server)

KI-Client verbinden

Lokale MCP-Server laufen über stdio: Der KI-Client startet Ihren Serverprozess und kommuniziert über stdin/stdout mit ihm. Das Konfigurationsformat ist der mcpServers-Block des Clients.

Claude Desktop (Windows)

Bearbeiten Sie %APPDATA%\Claude\claude_desktop_config.json (öffnen über Einstellungen → Entwickler → Konfiguration bearbeiten), vollständig beenden und neu starten:

{
  "mcpServers": {
    "ai-student-assistant": {
      "command": "C:\\Users\\ASUS\\mcp project\\.venv\\Scripts\\python.exe",
      "args": ["C:\\Users\\ASUS\\mcp project\\app\\server.py"]
    }
  }
}

Anforderungen:

• Absolute Pfade – Claude Desktop übernimmt nicht Ihren Shell-PATH oder Ihr Arbeitsverzeichnis.

• Verwenden Sie where python / where git, um den genauen Interpreterpfad zu bestätigen.

• Nach dem Speichern Claude Desktop vollständig neu starten, dann im Menü für Verbindungen/Nachrichtenbox nach dem Server und seinen Tools suchen.

• Logs bei Fehlern: %APPDATA%\Claude\logs\mcp*.log.

Alternativen

• MCP Inspector (keine Konfiguration): mcp dev app/server.py bietet eine GUI, um jedes Tool manuell aufzurufen – ideal für Demos.

• Cursor – .cursor/mcp.json verwendet die identische mcpServers-Struktur.

• Der Server ist transportunabhängig: Derselbe MCPServer kann später über Streamable HTTP bereitgestellt werden (siehe Zukünftige Verbesserungen).

Beispielverwendung

Benutzer: Welche GitHub-Issues sind derzeit offen?

Der Agent ruft get_open_issues auf (kein Repository → Issues, die Ihnen zugewiesen sind), und fasst dann zusammen:

Sie haben 2 offene Issues, die Ihnen zugewiesen sind: „Fix login bug“ (#1, bug) und „Add CI pipeline“ (#2).

Benutzer: Welche Aufgaben sind in den nächsten 7 Tagen fällig?

Der Agent ruft get_upcoming_deadlines mit start/end auf, berechnet ab heute:

Diese Woche fällig: Quiz 3 (Mathe, 12. Aug.), Projektvorschlag-Entwurf (ENG101, 11. Aug.), Graph Traversal Assignment (CS101, 13. Aug.).

Benutzer: Erstelle Aufgaben für diese Aufgaben.

Der Agent ruft create_tasks_from_deadlines auf (der Server berücksichtigt bereits die Deduplizierung über source/source_id, sodass ein erneuter Aufruf nie Duplikate erzeugt):

3 Aufgaben erstellt. 0 übersprungen (keine Duplikate).

Benutzer: An welchen Aufgaben sollte ich zuerst arbeiten?

Der Agent ruft get_workload_summary und get_overdue_tasks auf, wägt dann Priorität und Fälligkeitsdaten ab:

Zuerst: „Fix flaky test in the CI pipeline“ (ÜBERFÄLLIG, hoch). Dann: Projektvorschlag-Entwurf (morgen fällig), Quiz 3 (in 2 Tagen fällig)...

API-Integration

GitHub

• Endpunkte: GET /issues (Ihnen zugewiesen), GET|POST /repos/{owner}/{repo}/issues, GET|PATCH /repos/{owner}/{repo}/issues/{number}.

• Authentifizierung: Authorization: Bearer <GITHUB_TOKEN>. Anonymer Zugriff ist für öffentliche Repos erlaubt; bei 401 wird ein klarer Fehler „Authentifizierung erforderlich“ zurückgegeben.

• Ratenbegrenzungen: 403 mit x-ratelimit-remaining: 0 und 429 werden auf einen rate_limited-Fehler abgebildet.

• Pull Requests: Der Issues-Endpunkt gibt auch PRs zurück; diese werden über den Schlüssel pull_request herausgefiltert.

• Alle Netzwerk-/Timeout-/Fehlerzustände werden in domänenspezifische Ausnahmen übersetzt (siehe Sicherheit).

LMS

Für dieses Projekt wurde keine legitime/zugängliche College-LMS-API angenommen, daher läuft das LMS hinter einer kleinen Schnittstelle (LMSService) mit einer realistischen Mock-Implementierung (MockLMSService), die:

• einen Kurskatalog mit Fälligkeitsdaten relativ zum heutigen Tag befüllt,

• Kurse validiert (unbekannter Kurs → not_found),

• Daten und Bereiche validiert (falsche Eingabe → invalid_input).

Später einen echten Anbieter hinzufügen = dieselbe Schnittstelle implementieren + LMS_PROVIDER=real setzen. Es wurden keine geschützten Seiten gescrapt; nichts umgeht die Authentifizierung. Der Mock verhält sich wie ein echter Dienst, sodass der Rest der App ohne Änderungen getestet werden kann.

Datenbank

SQLite-Datei unter DATABASE_PATH (Standard: data/tasks.db), eine Tabelle im MVP:

CREATE TABLE tasks (
    id          INTEGER PRIMARY KEY AUTOINCREMENT,
    title       TEXT    NOT NULL,
    description TEXT,
    status      TEXT    NOT NULL DEFAULT 'pending'
                    CHECK (status IN ('pending','completed')),
    priority    TEXT    NOT NULL DEFAULT 'medium'
                    CHECK (priority IN ('low','medium','high','urgent')),
    due_date    TEXT,                      -- ISO-8601 (date or timestamp)
    source      TEXT,                      -- 'github' | 'lms' | NULL
    source_id   TEXT,                      -- e.g. GitHub issue number
    source_url  TEXT,
    created_at  TEXT NOT NULL,
    updated_at  TEXT NOT NULL
);

CREATE INDEX idx_tasks_status    ON tasks(status);
CREATE INDEX idx_tasks_due_date  ON tasks(due_date);
CREATE INDEX idx_tasks_priority  ON tasks(priority, due_date);

CREATE UNIQUE INDEX uq_tasks_source ON tasks(source, source_id)
    WHERE source IS NOT NULL AND source_id IS NOT NULL;

Warum jede Entscheidung wichtig ist:

• Partieller eindeutiger Index auf (source, source_id) – SQLite behandelt NULL-Werte in einem regulären UNIQUE als unterschiedlich, was doppelte Importe durchlassen und mehrere „persönliche“ (quellenlose) Aufgaben verbieten würde. Der partielle Index mit WHERE source IS NOT NULL macht Importe auf Datenbankebene idempotent, genau dort, wo es hingehört. Dadurch ist create_task_from_issue / create_tasks_from_deadlines bei wiederholtem Aufruf sicher.

• status/priority als TEXT + CHECK – SQLite hat keine Enums; der CHECK sorgt für Integrität, während Python-enum.Enums die Werte für Typsicherheit spiegeln.

• ISO-8601-UTC-Zeitstempel als sortierbare Zeichenketten – lexikografische Ordnung == chronologische Ordnung, keine Zeitzonen-Mehrdeutigkeit, JSON-freundlich.

• source + source_id + source_url bewahren die Herkunft, sodass eine Aufgabe immer auf das Issue oder die Aufgabe zurückverfolgt werden kann, von der sie stammt.

Tests

pytest          # runs the whole suite: mocked GitHub, mock LMS, SQLite tasks, MCP client

Umfang (tests/):

MCP-Tools werden gegen eine echte Protokollverbindung mit dem In-Memory-Client des SDKs getestet (async with Client(server)) – dasselbe Muster wie FastAPIs TestClient. Kein Subprozess, kein Port, keine Anmeldedaten.

Sicherheit

• Geheimnisse leben nur in Umgebungsvariablen (.env ist in .gitignore; .env.example hat Platzhalter).

• Prinzip der geringsten Rechte: ein feingranularer GitHub-PAT, beschränkt auf Issues Lesen & Schreiben in bestimmten Repos – niemals voller repo-Umfang.

• Kein Protokollieren von Geheimnissen: ein Redacting-Filter entfernt Authorization-Werte aus Logs; und da der Server nichts auf stdout ausgibt (Logging geht an stderr), bleibt der stdio-Protokollstrom sauber.

• Eingabevalidierung: Pydantic an der Tool-Grenze + Domänenvalidierung in Services.

• Parametrisierte SQL über SQLAlchemy – keine zeichenkettenbasierten Abfragen.

• Kontrollierte Fehlerweitergabe: Die KI erhält strukturierte Fehler (code, message); rohe Stacktraces gehen nur in Server-Logs.

• Minimale Client-Exposition: Das .env-Token wird vom Serverprozess gelesen, nicht über die Client-Konfiguration weitergegeben.

Siehe auch die intervieworientierte Diskussion in Interview-Gesprächspunkte.

Einschränkungen

Ehrliche Vorbehalte, bewusst:

• LMS ist gemockt. LMS_PROVIDER=mock ist der einzige Anbieter. Ein echter API-Adapter, exportierter Kalender oder eine andere autorisierte Datenquelle muss hinzugefügt werden, um ihn zu ersetzen (austauschbar über die LMSService-Schnittstelle).

• SQLite ist Einzelbenutzer. Keine Nebenläufigkeitsgarantien, kein Netzwerkzugriff, keine Backend-Replikation. Bewusst für einen persönlichen Assistenten.

• Noch kein OAuth / kein HTTP-Transport. Das GitHub-Token ist ein statisches Geheimnis; der Server läuft über stdio. Für lokale persönliche Nutzung in Ordnung; für entfernte/gehostete Nutzung wären OAuth und Streamable HTTP erforderlich.

• Die Issue-Erstellung unterstützt keine explizite Zuweisung oder Body-Markdown über Freitext hinaus – bewusst klein gehalten.

• Ein-Stunden-Granularität bei Fälligkeiten – keine Zeitzonenkonvertierung; Daten werden in der vom Benutzer angegebenen ISO-8601-Form verglichen.

• Importe beschreiben veränderliche Quellobjekte als Schnappschüsse: Wenn ein GitHub-Issue später bearbeitet wird, wird eine bereits erstellte Aufgabe nicht aktualisiert (ein beabsichtigtes Verhalten, kein Fehler).

Zukünftige Verbesserungen

• Echter LMSService-Adapter (offizielle API oder .ics-Kalenderexport)

• Google-Kalender-Integration für Fälligkeiten

• Slack/Teams-Benachrichtigungen für überfällige Aufgaben

• PostgreSQL-Backend (Repository abstrahiert dies bereits)

• OAuth für GitHub + Streamable-HTTP-Transport + Docker-Bereitstellung

• Aufgabenverlauf/Prüftabelle; Issue-Updates synchronisieren Aufgaben neu

• Umfangreichere Agenten-Workflows (automatische Triage, wöchentlicher „Standup“-Bericht)

Projektarchitektur

Schichten in Abhängigkeitsreihenfolge:

app/tools       MCP adapters — type-hinted params, docstrings as descriptions, guard() → {ok, data, error}
app/services    GitHubService · LMSService (mock) · TaskService — business logic + cross-service workflows
app/database    Database (engine/session) · TaskRepository (all SQL)
app/models      SQLAlchemy ORM (Task) · Pydantic schemas (TaskCreate/Out, GitHubIssue, Deadline)
app/config.py   validated env config
app/exceptions  domain error hierarchy → AI-readable codes

Abhängigkeitsinjektion: app/server.py ist die Kompositionswurzel – sie baut Konfiguration → Datenbank → Services → MCPServer auf und registriert Tool-Funktionen mit den benötigten Services. Nichts ist global; Tests setzen denselben Graphen mit Fakes zusammen.

Fehlerfluss: Tool → Service → Repository/API löst eine StudentAssistantError aus → guard() gibt {ok: false, error: {code, message}} zurück. Unerwartete Ausnahmen werden protokolliert (stderr) und als generische internal_error-Meldung zurückgegeben.

Demo-Szenario

1. Erstellen Sie ein feingranulares GitHub-Token und setzen Sie GITHUB_TOKEN in Ihrer .env.

2. Befüllen Sie die Aufgabendatenbank: python -m scripts.seed_demo (erstellt ein paar Aufgaben, eine überfällig).

3. Starten Sie den Server: python -m app.server (oder mcp dev app/server.py, um den Inspector zu starten).

4. Verbinden Sie Claude Desktop / Inspector mit dem Server.

5. Fragen Sie: „Was muss ich diese Woche erledigen?“ → Der Agent ruft get_workload_summary auf, kombiniert offene GitHub-Issues + anstehende Fälligkeiten + ausstehende/überfällige Aufgaben und gibt eine priorisierte Antwort.

6. Fragen Sie: „Erstelle Aufgaben für alle diese Woche fälligen Aufgaben.“ → Der Agent ruft create_tasks_from_deadlines auf.

7. Überprüfen Sie in der Datenbank:

   sqlite3 data/tasks.db "SELECT title, due_date, source FROM tasks ORDER BY due_date;"

   → Neue Zeilen erscheinen mit source = 'lms', eine pro Fälligkeit. Führen Sie dieselbe Frage erneut aus, und das Tool meldet skipped anstatt zu duplizieren.

Interview-Gesprächspunkte

Seien Sie bereit, diese Entscheidungen zu verteidigen:

1. Warum MCP? Es ist ein standardisiertes Protokoll, sodass ein Server mit jedem KI-Client funktioniert; Tools werden entdeckt (tools/list), aufgerufen (tools/call) und dem Modell beschrieben – Benennung und Beschreibungen sind ein UX-Vertrag für LLMs.

2. Warum das aktuelle MCP SDK v2? Das SDK hat FastMCP in MCPServer umbenannt und bedient jetzt beide Protokollrevisionen (2025 und 2026-07-28) aus einem Prozess; pip install mcp installiert v2. Auf der gepflegten Linie (nicht v1-Wartung) aufzubauen, ist die vertretbare Wahl.

3. Dünne MCP-Schicht / Serviceschicht. Tool-Funktionen sind Adapter; die Logik lebt in Services hinter Schnittstellen. Dadurch sind GitHub, LMS und Aufgaben austauschbar und ohne Netzwerk testbar.

4. Partieller eindeutiger Index für Idempotenz. Erklären Sie, warum SQLite einen partiellen Index für (source, source_id) benötigt und wie er create_task_from_issue/create_tasks_from_deadlines als kleine, begründete Demo von SQL-Tiefe sicher macht.

5. GitHub 403-Mehrdeutigkeit. Verboten vs. ratenbegrenzt wird über den Antwortheader x-ratelimit-remaining unterschieden – eine echte API-Integrations-Feinheit, keine Folklore.

6. Tokens mit geringsten Rechten. Feingranularer PAT mit nur Issues: Read & Write vs. ein klassisches repo-Scope-Token. Kennen Sie das „Warum“ auswendig.

7. Fehlertaxonomie. Eine Ausnahmehierarchie, abgebildet auf stabile, KI-lesbare Codes, wobei Stacktraces auf Logs beschränkt sind. Zuverlässigkeit ist ein Designziel, kein nachträglicher Einfall.

8. Testen der Protokollschicht. In-Memory-Client(server) bedeutet, dass die MCP-Verdrahtung genau so getestet wird, wie ein Client sie verwendet.

9. Ehrliche Abgrenzung. Das LMS ist explizit gemockt; SQLite ist Einzelbenutzer – „persönliches Produktivitätstool“, kein Anspruch auf ein Enterprise-Mehrbenutzerprodukt.

Lizenz

MIT – siehe LICENSE. Copyright (c) 2026 Mahendra Vattikuti.