Saxophone Society by Marjan Markelj: Developer Portal

Öffentliche Schnittstellen der Saxophone Society by Marjan Markelj: REST API, OpenAPI und MCP-Server für KI-Assistenten. Aktuelle Programme und öffentliche Ratgeber mit Quellen. Keine Preise, privaten Daten oder automatischen Anmeldungen.

Erster REST-Aufruf

Ohne Anmeldung oder API-Schlüssel: Dieses Beispiel liest die aktuelle Academy. Quellen in sources für Aussagen verlinken.

curl -sS 'https://marjanmarkelj.de/wp-json/saxsoc/v1/programs/academy'

Aktuelle Antwortform, aus denselben Programmdaten wie der Endpunkt:

{
    "schemaVersion": "1.0",
    "updatedAt": "2026-09-13T17:43:43+00:00",
    "sources": [
        {
            "url": "https://marjanmarkelj.de/saxophon-lernen-erwachsene/",
            "title": "Saxophone Society Academy"
        }
    ],
    "id": "academy",
    "name": "Saxophone Society Academy",
    "audience": "Erwachsene Anfänger und Wiedereinsteiger",
    "summary": "16 wöchentliche Module innerhalb von 6 Monaten Begleitung.",
    "durationMonths": 6,
    "moduleCount": 16,
    "performanceChecks": 4,
    "features": [
        "Onboarding-Modul vor Beginn",
        "16 Module, jeweils ein Modul pro Woche",
        "Anschließend Freischaltung der Song Library",
        "4 individuelle Performance Checks",
        "Wöchentliche Online-Live-Sessions in der Gruppe",
        "Optionale individuelle 1:1-Sessions möglich; keine feste Inklusivzahl zugesagt",
        "Lebenslanger Community-Zugang einschließlich Community Challenges, Events und Webinaren; keine Zusage lebenslangen individuellen Coachings oder Zugriffs auf alle Kursinhalte"
    ],
    "url": "https://marjanmarkelj.de/saxophon-lernen-erwachsene/"
}

Weitere reine Leseabfragen: GET /programs listet Programme als Array, GET /search?query=Noten&limit=3 liefert ein Objekt mit query, results und sources. GET /next-step?intent=consultation nennt available und url. Nur bei available=true einen bestätigten Link empfehlen.

curl -sS --get 'https://marjanmarkelj.de/wp-json/saxsoc/v1/search' --data-urlencode 'query=Noten' --data 'limit=3'

MCP verbinden

Streamable HTTP mit MCP 2025-11-25. An den MCP-Auskunfts-Endpunkt POST senden, mit Content-Type: application/json und Accept: application/json, text/event-stream. Zustandslos ohne Sitzungs-ID. Nach initialize die Benachrichtigung notifications/initialized senden, dann tools/list und tools/call. Ab dann MCP-Protocol-Version: 2025-11-25 mitsenden. Kein GET-SSE-Kanal.

{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
        "protocolVersion": "2025-11-25",
        "capabilities": {},
        "clientInfo": {
            "name": "saxsoc-example",
            "version": "1.0.0"
        }
    }
}
{
    "jsonrpc": "2.0",
    "method": "notifications/initialized"
}
{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/list",
    "params": {}
}

Aktuelle Werkzeuge des Auskunftsservers:

Ein Academy-Aufruf mit dem info-Werkzeug:

{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
        "name": "saxsoc-geo-info",
        "arguments": {
            "topic": "program",
            "program": "academy"
        }
    }
}

Die JSON-RPC-Antwort enthält result.content mit Textblöcken (type=text, text enthält JSON mit den Programmdaten und sources) sowie isError. Bei isError=true keine erfolgreiche Auskunft behaupten. Der Dokumentserver bietet saxsoc-geo-documents, saxsoc-geo-document und saxsoc-geo-search für öffentliche Inhalte.

NLWeb Teilprofil 0.55

POST /ask (alternativ /wp-json/saxsoc/v1/nlweb/ask) mit diesem JSON-Body und Content-Type: application/json:

curl -sS 'https://marjanmarkelj.de/ask' -H 'Content-Type: application/json' --data '{"query":{"text":"Academy"},"prefer":{"mode":"list","streaming":false},"meta":{"version":"0.55"}}'

Die Antwort enthält _meta.version=0.55 und results mit @type=WebPage, name, url, description und sources. mode=summarize ergänzt in results einen SearchSummary-Eintrag mit text, sources und nextStep. Nur conversational_search, keine Kontextspeicherung und keine LLM-Generierung. prefer.streaming=true liefert begrenzte SSE-Events start, result und complete mit JSON-Daten. Hosting-Pufferung bei der Live-Abnahme prüfen.

Fehler und Grenzen

REST-Fehler sind JSON-Objekte mit code, message und data.status. Beispiel für GET /programs/unbekannt:

{
    "code": "invalid_program",
    "message": "Unbekanntes Programm.",
    "data": {
        "status": 404
    }
}

400: ungültige Eingabe; 404: unbekanntes Programm oder Dokument; 429: Anfragelimit erreicht, Retry-After beachten. MCP verwendet zusätzlich JSON-RPC-Fehler bzw. isError in Werkzeugantworten, NLWeb liefert bei Fehlern _meta und error.code/error.message. REST- und MCP-Fragen: maximal 500 Zeichen; NLWeb-Fragen: maximal 300 Zeichen; Ratgebersuche: maximal 300 Zeichen und zehn Suchtreffer; Protokoll-Body maximal 16 KB. Fremde Origin-Header werden mit 403 abgelehnt. 120 Protokollrequests je Minute pro anonymem Netzwerkzugang; insgesamt 240 Anfragen je Minute für die öffentliche Schnittstelle. Die Grenzen sind Schutz vor Missbrauch, keine Anmeldung. RateLimit-Policy, RateLimit (IETF-Entwurf) und X-RateLimit-* beschreiben das gemeinsame Budget. nextStep.available=false bedeutet: kein bestätigter Anmeldelink. Die Agentenansicht der Startseite ist unter ?mode=agent erreichbar. WebMCP ergänzt unterstützte Browser; normale Seiten bleiben ohne diese Erweiterung nutzbar.