Dokumentation

Maschinchenring ist eine Plattform für lokalen Geräteverleih. Geräte können über den Chat, die Webseite oder direkt über einen MCP-Client (z.B. Claude Desktop) gebucht werden.

Architektur

Ein Node.js-Server (Express + Hono) stellt gleichzeitig eine Astro SSR-Website und einen MCP-Server bereit. Daten werden in einer SQLite-Datenbank (better-sqlite3) gespeichert.

LLM-Client (Claude Desktop, etc.)
    │
    │  OAuth PKCE + MCP Streamable HTTP
    ▼
┌──────────────────────────────────┐
│  Node.js Server (:3000)          │
│  ├── /mcp          MCP-Tools     │
│  ├── /oauth/*      OIDC          │
│  ├── /auth/*       GitHub+Magic  │
│  ├── /buchungen/*  Approve/Reject│
│  ├── /api/*        REST-API      │
│  └── /*            Astro SSR     │
│  SQLite (better-sqlite3)         │
└──────────────────────────────────┘
    │                    │
    │ E-Mail (SES/SMTP)  │ imgproxy
    ▼                    ▼
Owner + Mieter     Bild-CDN

Zugangswege

Webseite

Die Webseite unter / bietet:

MCP-Client (Claude Desktop etc.)

Der MCP-Server ist unter /mcp erreichbar. MCP-Clients authentifizieren sich per OAuth 2.0 PKCE:

  1. Discovery: GET /.well-known/oauth-authorization-server
  2. Registrierung: POST /oauth/register → client_id
  3. Autorisierung: GET /oauth/authorize?... → Login → Auth-Code
  4. Token: POST /oauth/token mit Code + Code-Verifier → access_token
  5. MCP-Calls: Bearer <access_token> an /mcp

Die MCP-Server-URL findet man nach dem Login unter /konto.

Authentifizierung

Zwei Login-Methoden stehen zur Verfügung:

Nach dem Login wird ein JWT (RS256) als Cookie gesetzt (auth_token).

Buchungsfluss

Mieter → create_booking → Status: pending
    │
    ▼  Owner erhält E-Mail mit Approve/Reject-Link
    │
    ├── Approve → /buchungen/:id/approve?token=...
    │   → Status: approved → Mieter-E-Mail (+ Abholadresse)
    │
    └── Reject  → /buchungen/:id/reject?token=...
        → Status: rejected → Mieter-E-Mail

Buchungen können auch per MCP-Tool (approve_booking / reject_booking) oder über die API bestätigt/abgelehnt werden.

Bilder

Bilder werden per POST /images/upload hochgeladen (JWT-Auth, Uploader-Berechtigung erforderlich). Sie landen auf S3/MinIO und werden via imgproxy als optimierte, HMAC-signierte URLs ausgeliefert.

Datenschutz

Wichtig: Die Abholadresse (Owner-Adresse) erscheint niemals öffentlich. Sie wird ausschließlich nach Buchungsbestätigung per E-Mail an den Mieter übermittelt.

Tech-Stack