piazza-mcp

piazza-mcp ist ein lokaler, schreibgeschützter MCP-Server zum Durchsuchen und Lesen konfigurierter Piazza-Diskussionen.

Der Server verwendet das von der Community entwickelte Paket piazza-api und Piazzas unveröffentlichte interne Endpunkte. Es handelt sich nicht um eine offizielle Piazza-Integration und sie kann brechen, wenn Piazza seine Website ändert. Halten Sie die Anforderungslimits konservativ und bestätigen Sie, dass diese Zugriffsmethode für Ihr Konto und Ihre Einrichtung akzeptabel ist.

Anforderungen

• Python 3.10 bis 3.14.

• uv für die Verwaltung von Abhängigkeiten und Umgebungen.

• MCP Python SDK 1.x. Der Server verwendet die v1 Low-Level-Server-Dekorator-API und deklariert mcp>=1.28.1,<2.

Werkzeuge

• list-piazza-courses: listet konfigurierte Kurse auf, die für das Konto zugänglich sind.

• list-piazza-posts: gibt begrenzte Zusammenfassungen der letzten Beiträge für einen Kurs zurück.

• get-piazza-post: gibt einen begrenzten normalisierten Thread zurück.

• search-piazza-posts: durchsucht einen konfigurierten Kurs und gibt begrenzte Zusammenfassungen zurück.

Alle Werkzeuge sind schreibgeschützt. Kursbezogene Aufrufe sind auf IDs in PIAZZA_COURSES beschränkt. Der zurückgegebene Beitragstext ist begrenzter Klartext und wird als nicht vertrauenswürdiger benutzergenerierter Inhalt gekennzeichnet. Der Server veröffentlicht keine Beiträge, antwortet nicht, bearbeitet nicht, lädt keine Anhänge herunter, legt keine Teilnehmerlisten offen und führt keine Dozentenoperationen aus.

list-piazza-posts akzeptiert einen limit von 1 bis 25 und einen offset von 0 bis 500. Fordern Sie eine weitere Seite nur an, wenn die vorherige Antwort truncated: true meldet. Suchanfragen akzeptieren eine Abfrage von höchstens 200 Zeichen und geben höchstens 25 Ergebnisse zurück. Antworten werden 60 Sekunden lang im Speicher zwischengespeichert; nach einem Aktualisierungsfehler können veraltete zwischengespeicherte Daten zurückgegeben werden.

Konfiguration

Kopieren Sie die geschwärzte Vorlage und halten Sie die resultierende Datei privat:

cp .env.example .env
chmod 600 .env

PIAZZA_EMAIL="student@example.edu"
PIAZZA_PASSWORD="replace-with-your-password"
PIAZZA_COURSES='{"abc123":"CMSC 132","xyz789":"CMSC 216"}'

PIAZZA_COURSES ordnet Piazza-Kurs-IDs Anzeigenamen zu. Eine Kurs-ID ist der Wert nach /class/ in einer Piazza-Kurs-URL. Prozessumgebungsvariablen haben Vorrang vor .env. Wenn Sie ein installiertes Wheel außerhalb dieses Checkouts ausführen, stellen Sie die Variablen über die Prozessumgebung bereit.

Committen Sie niemals .env, fügen Sie keine Anmeldeinformationen in Eingabeaufforderungen ein und nehmen Sie keine Anmeldeinformationen, Cookies, Kurs-IDs oder Beitragsinhalte in Protokolle auf. Konten, die ein rein institutionelles SSO erfordern, unterstützen möglicherweise nicht den E-Mail-/Passwort-Ablauf, der vom inoffiziellen Paket verwendet wird.

Ausführen und Registrieren

uv sync --locked
uv run --frozen piazza-mcp

Registrieren Sie den Checkout mit Codex:

codex mcp add piazza-mcp \
  -- uv --directory /absolute/path/to/piazza_mcp run --frozen piazza-mcp

Die checkout-lokale .env wird verzögert geladen, wenn das erste Piazza-Werkzeug aufgerufen wird. Sie können die Registrierung aktualisieren mit:

./scripts/update_mcp_server.sh

Starten Sie den MCP-Client neu, nachdem Sie den Werkzeugkatalog geändert haben.

Projektstruktur

src/piazza_mcp/
  server.py              MCP protocol boundary and dispatch
  config/
    env.py               lazy checkout-local .env loading
    piazza.py            credentials and course allowlist
  mcp_schemas/
    piazza.py            structured-output contracts
  mcp_tools/
    piazza.py            tool descriptions, inputs, and annotations
  models/
    piazza.py            bounded Piazza data structures
  services/piazza/
    client.py            timeout-bound unofficial API adapter
    normalizer.py        HTML cleanup and response normalization
    profiler.py          privacy-safe aggregate shape diagnostics
    service.py           allowlisting, limits, caching, and serialization
    factory.py           lazy configured service construction
tests/
  config/
  mcp_schemas/
  mcp_tools/
  server/
  services/piazza/

Entwicklung

Der datenschutzsichere Inspektor lädt höchstens fünf Zusammenfassungen und einen vollständigen Thread und gibt dann aggregierte Schlüssel-, Typ- und Verschachtelungszahlen aus, ohne Beitragswerte zu drucken:

uv run --frozen python scripts/inspect_piazza_shapes.py

Er stellt weiterhin Live-Anfragen. Führen Sie ihn nur aus, wenn Sie ausdrücklich auf das konfigurierte Piazza-Konto zugreifen möchten.

Führen Sie die Offline-Verifizierungssuite aus:

uv lock --check
uv run --frozen pytest -q
uv run --frozen python -m compileall -q src/piazza_mcp tests scripts
uv build

Debuggen Sie den Server mit MCP Inspector:

npx @modelcontextprotocol/inspector \
  uv --directory /absolute/path/to/piazza_mcp run --frozen piazza-mcp