Nakafa Entwicklerressourcen

Zuletzt aktualisiert: 27. August 2026

Nakafa bietet öffentlichen, maschinenlesbaren Zugriff auf mehrsprachige Lernmaterialien und klar begrenzte Quran-Referenzen. Die Schnittstellen eignen sich für Agents und Anwendungen, die typisierte Eingaben, vorhersehbare Fehler und kanonische Inhaltsreferenzen benötigen. Sie sind schreibgeschützt, benötigen kein Nakafa Konto und geben keine privaten Lerndaten, Käufe oder Kontofunktionen frei.

Verifizierte Implementierung

Diese öffentlichen Schnittstellen wurden live gegen den Nakafa Commit 2fae54fec31b7cd630a56933b613fa5b9504695a verifiziert: REST Index und OpenAPI Vertrag liefern dieselbe Release Identität, die kanonische MCP Bridge schließt die Protokollerkennung ab und nakafa-cli@0.1.0 ist über npm verfügbar.

In dieser Revision besitzt api.ts REST, route.ts MCP, document.ts erzeugt OpenAPI und program.ts besitzt die CLI Befehlsoberfläche.

Öffentliche REST API

Die kanonische API Basis ist https://api.nakafa.com/v1. Beginne beim Dienstindex und suche nach einem passenden Inhalt. Rufe ein Ergebnis nur dann über seine Inhalts-ID ab, wenn es markdown_url enthält. Ein Probetest-Katalogergebnis ohne markdown_url dient nur als Quellenangabe und verweist auf seine kanonische Anwendungs-URL. Die API stellt außerdem die veröffentlichte Taxonomie und begrenzte Quran-Versbereiche bereit.

GET /v1: Dienstidentität und Links zur Erkennung
GET /v1/health: Dienststatus
GET /v1/search: Suche nach Begriff, Bereich, Sprache, Limit und Offset
GET /v1/content?ref=...: Abruf einer genauen Inhalts-ID oder kanonischen URL
GET /v1/taxonomy: veröffentlichte Taxonomie
GET /v1/quran/{surah}: Abruf eines typisierten Versbereichs

Die Suche liefert standardmäßig 10 Ergebnisse und akzeptiert höchstens 50 Ergebnisse pro Anfrage. Verwende offset, has_more und next_offset, um eine Ergebnismenge ohne Annahmen fortzusetzen. Clients sollten höchstens 120 Anfragen pro 60 Sekunden von einer IP einplanen und HTTP-429-Antworten mit einem Backoff behandeln.

search.sh

curl "https://api.nakafa.com/v1/search?query=lineare%20gleichungen&locale=de&limit=5"

OpenAPI und Fehler

Der Nakafa OpenAPI 3.1 Vertrag beschreibt alle öffentlichen Vorgänge, Eingaben, Antworten und Beispiele. Kompatible Ergänzungen bleiben in v1. Eine inkompatible Änderung benötigt einen neuen Hauptpfad.

Von Convex erzeugte API Fehler verwenden RFC 9457 Problem Details mit dem Medientyp application/problem+json. Jede Antwort enthält einen stabilen code, ein verständliches detail, einen konkreten resolution Hinweis und eine nachverfolgbare request_id. Eine HTTP-429-Antwort der Vercel Firewall kann eine Anfrage stoppen, bevor sie Convex erreicht. Clients müssen diese plattformeigene Ausnahme mit Backoff erneut versuchen.

problem.json

{
"type": "https://nakafa.com/problems/invalid-request",
"title": "Invalid request",
"status": 400,
"detail": "Unknown query parameter: page.",
"instance": "/v1/search",
"code": "INVALID_REQUEST",
"resolution": "Use only these query parameters: limit, locale, offset, query, section.",
"request_id": "request-example"
}

Model Context Protocol

Der kanonische MCP Endpunkt ist https://nakafa.com/mcp. Verwende MCP, wenn ein Agent bereits Tool-Erkennung und strukturierte Tool-Aufrufe unterstützt. Verwende REST für gewöhnliche HTTP-Integrationen oder aus OpenAPI erzeugte Clients. Beide Schnittstellen führen dieselbe Convex-eigene Fähigkeit aus und prüfen dieselbe signierte Aksara-Veröffentlichung.

Der Server stellt vier schreibgeschützte Tools bereit:

nakafa_search_content
nakafa_get_content
nakafa_get_taxonomy
nakafa_get_quran_reference

Moderne Clients verwenden Streamable HTTP. Das Protokoll 2026-07-28 ersetzt den bisherigen initialize-Ablauf durch server/discover und einen _meta-Umschlag in jeder Anfrage. Ein Client ermittelt zuerst die unterstützte Revision und listet oder ruft anschließend Tools mit demselben Umschlag auf. Nakafa akzeptiert diese dokumentierte Protokollrevision und meldet alle unterstützten Revisionen über die Erkennung. Serveridentität und Funktionen stammen aus der server/discover-Antwort. Der zustandslose Nakafa-Endpunkt stellt kein separates GET-Manifest bereit.

mcp.http

POST /mcp HTTP/1.1
Host: nakafa.com
Content-Type: application/json
Accept: application/json, text/event-stream
MCP-Protocol-Version: 2026-07-28
Mcp-Method: server/discover

{"jsonrpc":"2.0","id":1,"method":"server/discover","params":{"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28","io.modelcontextprotocol/clientInfo":{"name":"example-client","version":"1.0.0"},"io.modelcontextprotocol/clientCapabilities":{}}}}

###

POST /mcp HTTP/1.1
Host: nakafa.com
Content-Type: application/json
Accept: application/json, text/event-stream
MCP-Protocol-Version: 2026-07-28
Mcp-Method: tools/list

{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28","io.modelcontextprotocol/clientInfo":{"name":"example-client","version":"1.0.0"},"io.modelcontextprotocol/clientCapabilities":{}}}}

Kommandozeile

Das offizielle Node 24 Paket heißt nakafa-cli und stellt den Befehl nakafa bereit. Es verwendet die öffentliche REST API und schreibt standardmäßig kompaktes JSON. Ergänze --pretty für lesbare Ausgabe oder --api-base, wenn du einen lokalen oder unabhängig betriebenen kompatiblen API Endpunkt prüfst.

nakafa-cli.sh

npm install --global nakafa-cli
nakafa search lineare gleichungen
nakafa quran 1 --from-verse 1 --to-verse 7 --pretty
nakafa mcp

Das Programm erhält Problem-Details-JSON auf dem Standardfehlerkanal und verwendet stabile Exit-Kategorien ungleich null für Aufruf-, API- sowie Netzwerk- oder Serverfehler.

Maschinenlesbare Erkennung