Paxaver MCP Server

KI-orientierter Adapter über die Paxaver Schul-Community-Plattform. Implementiert das Model Context Protocol (MCP) auf Cloudflare Workers mit RS256-JWT-Validierung, Capability-first-Autorisierung und Streamable-HTTP-Transport.

Was das ist

Der Paxaver-MCP-Server ermöglicht es KI-Assistenten (ChatGPT, Claude, Perplexity und jedem MCP-kompatiblen Client), im Namen eines Paxaver-Benutzers zu handeln: Mittagsmenü prüfen, Mittagessen bestellen, Guthaben aufladen, sich für Spendenaktionen registrieren, an eine Schule spenden, sich ehrenamtlich engagieren und – für Schuladministratoren – Restaurants, Menüpunkte, Veranstaltungen und Tagesbestellungen verwalten.

Es ist ein dünner Adapter. Er enthält keine Geschäftslogik und greift nie direkt auf die Datenbank, Stripe oder E-Mail zu. Jede Aktion wird über eine Cloudflare-Service-Binding an die private Paxaver-Backend-API delegiert (gleiche Region, kein öffentlicher Netzwerk-Hop). Die einzigen Aufgaben des MCP-Servers sind:

• MCP-Protokollbehandlung (JSON-RPC 2.0, Streamable HTTP)

• RS256-JWT-Validierung über JWKS vom zentralen Paxaver-Auth-Worker

• Capability-Richtlinie und Rollen-Gating pro Tool

• Bereinigtes, benutzersicheres Fehler-Mapping

Die Authentifizierung wird vom Paxaver-Auth-Worker (auth.paxaver.com) übernommen, der als OAuth-2.0-/OIDC-Autorisierungsserver dient. Der MCP-Server validiert die resultierenden RS256-JWTs und leitet sie an das Backend weiter. Der MCP-Server selbst ist kein Autorisierungsserver.

Related MCP server: IIITH Mess MCP

Architektur

┌───────────────┐     MCP (Streamable HTTP)      ┌──────────────────────┐
│   AI Client   │ ─────────────────────────────▶ │   Paxaver MCP Worker │
│ ChatGPT/Claude│ ◀───────────────────────────── │  (this repo)         │
│  /Perplexity  │     RS256 JWT + JSON-RPC 2.0   │  Hono + jose         │
└───────────────┘                                └──────────┬───────────┘
                                                            │
                                          Cloudflare service binding
                                          (PAXAVER_API, same region)
                                                            │
                                                            ▼
                                                 ┌──────────────────────┐
                                                 │  Paxaver API Worker  │
                                                 │  (private backend)   │
                                                 │  D1 · Stripe · SES   │
                                                 └──────────────────────┘

Der MCP-Worker bindet niemals D1, Stripe oder SES. Das Service-Binding trägt ein kurzlebiges JWT (120s TTL, Audience paxaver-internal), dem das Backend als internen Aufruf vertraut, während die Aktion weiterhin dem authentifizierten Paxaver-Benutzer zugeordnet wird. Siehe docs/architecture.md für das vollständige Bild.

Schnellstart

Installation

npm install @paxaver/mcp

Lokale Entwicklung

# 1. Install dependencies (Node >= 22)
npm install

# 2. Configure local secrets
cp .dev.vars.example .dev.vars   # then fill in JWT_SECRET, OAUTH_STATE_SECRET, ...

# 3. Run the worker locally (Miniflare)
npm run dev

# 4. Typecheck, lint, and test
npm run typecheck
npm run lint
npm test

Der lokale Entwicklungsserver startet auf http://localhost:8787. Discovery-Endpunkte befinden sich unter /.well-known/; der MCP-Endpunkt ist POST /mcp.

Hinweis: Die lokale Entwicklung ohne das PAXAVER_API-Service-Binding fällt auf authentifiziertes HTTPS gegen API_BASE_URL zurück (Standard: http://localhost:8787). Für vollständige Integrationstests führen Sie den Paxaver-Backend-Worker lokal aus und richten Sie API_BASE_URL darauf aus.

Bereitstellung

Zwei Umgebungen, jeweils ein separater Worker mit eigener benutzerdefinierter Domäne:

Der Produktions-Worker bedient sowohl CA- als auch US-Benutzer über einen einzigen Endpunkt (mcp.paxaver.com). Die Benutzerregion wird aus dem JWT-Anspruch tenant_id ermittelt, und der Worker leitet über Service-Bindings (PAXAVER_API_CA, PAXAVER_API_US) an das richtige regionale Backend weiter. Die Währung wird durch die Schule des Benutzers bestimmt, nicht durch den MCP-Endpunkt.

npm run deploy:staging   # wrangler deploy --env staging
npm run deploy:prod      # wrangler deploy --env production

Geheimnisse müssen mit wrangler secret put --env production gesetzt werden: JWT_SECRET, OAUTH_STATE_SECRET, GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET, CHATGPT_VERIFY_TOKEN. Siehe docs/deployment.md.

Werkzeuge

Der Server stellt 31 Werkzeuge bereit, die in sechs Kategorien gruppiert sind. Die Sichtbarkeit in tools/list wird nach den Rollen des Aufrufers gefiltert; jeder Aufruf wird vor dem Versand erneut autorisiert, und das Backend prüft erneut den Zugriff auf Datenebene (Defense-in-Depth).

Finanzielle und destruktive Werkzeuge sind gekennzeichnet und erfordern eine Benutzerbestätigung. Vollständige Referenz: docs/tools.md. Autorisierungsrichtlinie: docs/authorization.md.

Dokumentation

Technologie-Stack

• Laufzeit: Cloudflare Workers (compatibility_date: 2026-08-01, nodejs_compat)

• Framework: Hono v4

• JWT: jose v6 (RS256 via JWKS)

• Protokoll: MCP 2025-06-18, Streamable HTTP

• Auth: RS256-JWT-Validierung über zentralen Auth-Worker (auth.paxaver.com)

• Build/Deployment: Wrangler v4

• Test: Vitest v2 (Workers-Pool + Node-Pool)

Lizenz

Apache-2.0. Urheberrecht (c) 2026 Smartoire. Siehe LICENSE.