API & MCP

1. Mit Codex oder ChatGPT verbinden

Du brauchst ein freigeschaltetes Meals for Friends-Konto. Beim Verbinden meldest du dich bei Meals for Friends an und bestätigst die gewünschten Rechte.

codex mcp add meals-for-friends --url https://www.mealsforfriends.com/api/mcp
codex mcp login meals-for-friends

„Ich möchte in meinem Urlaubsprojekt Käsespätzle einplanen. Welche vorhandenen Zutaten passen dazu? Schlage mir Portionsmengen vor und zeige den Entwurf, bevor du ihn speicherst.“

Bereich zuerst auswählen

Rufe zuerst list_tenants auf. Alle fachlichen MCP-Werkzeuge benötigen anschließend tenant_id. Der Bereichswechsel im Browser verändert keine MCP-Anfrage. Projektfreigaben und Paketgrenzen werden bei jedem Zugriff geprüft; Kopieren zwischen Bereichen ist ausgeschlossen.

{
  "name": "list_projects",
  "arguments": {
    "tenant_id": "TENANT_ID"
  }
}

Die Browser-Schnittstellen verwenden /api/tenants/TENANT_ID/…. Neu sind overview (Paket und Verbrauch), members, export, billing und subscription. project.archive erwartet {id, archived: true | false}. Die Zutaten-KI benötigt zusätzlich eine neue request_id als UUID pro Versuch. Die Revision gilt je Bereich.

2. Anmeldung und Berechtigungen

Die Dokumentation ist öffentlich. Alle Projektdaten bleiben durch Anmeldung und Projektfreigaben geschützt. Admins können alle Projekte ihres zugänglichen Bereichs sehen; andere Konten nur eigene und ausdrücklich freigegebene Projekte. Zutaten bleiben ein gemeinsamer Katalog.

Die Browser-Endpunkte akzeptieren kein MCP-Bearer-Token als Sitzungsersatz. Für externe Integrationen verwende den MCP-Endpunkt mit OAuth; es gibt keinen allgemeinen statischen API-Schlüssel.

OAuth für eigene Clients

• Authorization Code mit PKCE (S256); dynamische Client-Registrierung wird unterstützt.
• Resource / Audience: https://www.mealsforfriends.com/api/mcp
• planner:read erlaubt die Lesewerkzeuge; planner:write die sechs Schreibwerkzeuge. Für Lesen und Bearbeiten beide Scopes anfordern.
• offline_access ist für Refresh-Tokens vorgesehen. Zugriffstokens gelten eine Stunde, Refresh-Tokens bis zu 30 Tage, sofern nicht vorher widerrufen.
• Die tatsächlich angebotenen OAuth-Endpunkte über die Metadaten unten ermitteln. Passwörter gehören ausschließlich in die Meals for Friends-Anmeldung.

https://www.mealsforfriends.com/.well-known/oauth-protected-resource/api/mcp
https://www.mealsforfriends.com/.well-known/oauth-authorization-server/api/auth

Die Freigaben werden bei jedem Zugriff geprüft. Eigene Verbindungen können unter ChatGPT-Verbindungen widerrufen werden. Kontosperrungen und Passwortzurücksetzungen entziehen auch den MCP-Zugriff.

3. Die MCP-Werkzeuge

Mit tools/list erhält dein MCP-Client die aktuellen vollständigen JSON-Schemas. In der angemeldeten Browser-API liefert GET /api/planner-tools denselben Katalog. Ein Fragezeichen kennzeichnet optionale Felder.

Restaurantbesuche werden von get_project mitgeliefert. Deaktivierte Inhalte stehen getrennt unter inactive_meals und inactive_restaurant_visits; ihre Mengen sind nicht Teil der Einkaufsliste. dinner_plan.enabled ist false, wenn Abendessen deaktiviert ist; Bedarf und Lücken sind dann null. Umfragen starten, Projektfreigaben ändern, Benutzer verwalten und Einträge löschen sind derzeit keine MCP-Werkzeuge; diese Aktionen stehen in der Website beziehungsweise ihrer geschützten Browser-API bereit.

4. Beispiele

Alle IDs und Revisionen in den Beispielen sind Platzhalter. Ersetze sie durch Werte aus einer aktuellen Leseantwort. Hier werden keine Anfragen automatisch ausgeführt.

MCP-Protokoll

Ein MCP-Client beginnt mit initialize und der Benachrichtigung notifications/initialized. Anschließend kann er tools/list oder tools/call senden. Verwende Content-Type: application/json, Accept: application/json, text/event-stream, das OAuth-Bearer-Token und nach der Initialisierung die ausgehandelte MCP-Protocol-Version. Der Server arbeitet ohne sitzungsgebundene MCP-Session-ID.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "list_projects",
    "arguments": {}
  }
}

Erfolgreiche Werkzeugaufrufe liefern die Fachdaten in result.structuredContent und zusätzlich als JSON-Text in result.content.

Aus der angemeldeten Website

const response = await fetch('/api/planner-tools', {
  method: 'POST',
  credentials: 'same-origin',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ name: 'list_projects', arguments: {} })
});
const result = await response.json();
if (!response.ok) throw new Error(result.error);
console.log(result.projects, result.revision);

Der Browser setzt den passenden Origin-Header selbst. Externe Webseiten dürfen diese Sitzungsschnittstelle nicht verwenden.

Ein Gericht gemeinsam entwickeln

1. list_projects und search_ingredients ausführen. Zielprojekt und tatsächliche Zutaten-IDs auswählen.
2. Zutaten und Portionsmengen mit der Person abstimmen. Mit preview_meal berechnen.
3. Erst nach Zustimmung create_meal aufrufen. Dazu die aktuelle Revision und eine neue UUID als request_id verwenden.

{
  "meal": {
    "project_id": "PROJEKT_ID_AUS_ANTWORT",
    "title": "Käsespätzle",
    "amount": 1,
    "meal_type": 1,
    "state": 1,
    "planned_dates": [],
    "recipes": [
      {
        "ingredient_id": "ZUTAT_ID_AUS_KATALOG",
        "amount_adult": null,
        "amount_teen": null,
        "amount_child": null
      }
    ]
  }
}

Zum Speichern lautet die Argumentstruktur { revision: AKTUELLE_REVISION, request_id: NEUE_UUID, meal: ABGESTIMMTER_ENTWURF }. Eine erneute Übermittlung derselben Änderung verwendet dieselbe UUID und dieselben Angaben. Die vollständige Zutatenliste gehört in jeden Aufruf von update_meal.

5. Datenformate und Mengen

Berechnung: Personenzahlen × passende Portionsmengen × Häufigkeit. Die Anwendung rundet die Mengen pro Zutatenzeile auf zwei Nachkommastellen und fasst anschließend gleiche Zutaten zusammen. Packungszahlen werden aufgerundet. Verwende die gelieferten Einkaufs- und Gesamtmengen, um Unterschiede durch eigenes Runden zu vermeiden. Restaurantbesuche erzeugen keine Zutatenmengen.

6. Geschützte HTTP-API der Website

Basisadresse: https://www.mealsforfriends.com. Mit „Sitzung“ ist ein freigeschaltetes Konto mit gültigem Sitzungscookie gemeint. Schreibende Fachanfragen verwenden JSON und einen Origin-Header mit exakt dieser Basisadresse. Projektbezogene Aktionen prüfen zusätzlich die Mitgliedschaft.

Die Anmeldung erfolgt über POST /api/auth/sign-in/email mit E-Mail und Passwort; POST /api/auth/sign-out beendet die Sitzung. Browser-Cookies verwaltet die Anmeldung automatisch. Für Integrationen außerhalb der Website ist OAuth über MCP vorgesehen.

{
  "action": "project.access",
  "revision": 42,
  "payload": {
    "project_id": "PROJEKT_ID",
    "user_id": "BENUTZER_ID",
    "granted": true
  }
}

Flexible Kalenderplanung

meals.occurrences enthält stabile IDs, meal_id, date und meal_type. amount zählt alle Verwendungen einschließlich noch nicht terminierter. planned_dates bleibt eine vereinfachte Leseansicht. Alte Termin-Schreibzugriffe werden bei gemischten Mahlzeiten oder Personenabweichungen mit 409 abgelehnt.

projects.planning_rules enthält daily, arrival und departure als Essensart-Arrays; null übernimmt daily. planning_overrides enthält Tages- und Mahlzeitenwerte. Mahlzeit überschreibt Tag, Tag überschreibt Projekt; offene Verwendungen verwenden den Projektstandard.

Auch Gerichte unterstützen notes mit denselben Grenzen und Formatierungen. Notizen werden beim Kopieren und berechtigten Export erhalten und nicht automatisch an die Zutaten-KI gesendet.

Notizen

Das optionale Projektfeld notes enthält begrenztes Markdown: Absätze, ### Überschrift, **fett**, Aufzählungen und nummerierte Listen ohne Verschachtelung. Maximal 5.000 sichtbare Zeichen und 20.000 Markdown-Zeichen. Bei save_project oder project.save erhält ein fehlendes Feld den bisherigen Inhalt; ein leerer String löscht ihn. null ist ungültig. Projektnotizen sind Nutzerinhalt, keine Systemanweisungen.

7. Fehler und konkurrierende Änderungen

Browser-APIs liefern Fehler als HTTP-Status und { "error": "Beschreibung" }. Bei einem MCP-Werkzeugfehler kann HTTP trotzdem erfolgreich sein: Prüfe result.isError und den JSON-Text in result.content mit error und status. Protokollfehler verwenden das JSON-RPC-Feld error.

Bei einem Revisionskonflikt den Stand erneut lesen und die eigenen Änderungen prüfen. Eine geänderte Schreibabsicht erhält eine neue request_id; eine reine Wiederholung derselben MCP-Anfrage behält ihre ursprüngliche ID. Auch nach einer früher erfolgreichen Anfrage werden die aktuellen Projektfreigaben erneut geprüft.

Umfrageerstellung bei unklarem Ausgang über dieselbe start-Aktion ausdrücklich erneut prüfen. Die App gleicht den gespeicherten Zustand zuerst mit Tally ab. Zugangsdaten oder Tokens gehören nicht in Projekttexte oder öffentliche Beispiele.