# Nakafa Entwicklerressourcen > For AI agents: use [llms.txt](https://nakafa.com/llms.txt) for the site index. Markdown versions are available by appending `.md` to content URLs or sending `Accept: text/markdown`. URL: https://nakafa.com/de/developers Source: https://raw.githubusercontent.com/nakafaai/aksara/11c10d705985738d79e314865fa46c0cd824756b/packages/corpus/pages/developers/de.mdx Nutze Nakafas öffentliche REST API, den OpenAPI Vertrag, den MCP Server und das Kommandozeilenprogramm für verlässliche Bildungsabläufe. --- # 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`](https://github.com/nakafaai/nakafa.com/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`](https://github.com/nakafaai/nakafa.com/blob/2fae54fec31b7cd630a56933b613fa5b9504695a/packages/backend/convex/routes/agent/api.ts) REST, [`route.ts`](https://github.com/nakafaai/nakafa.com/blob/2fae54fec31b7cd630a56933b613fa5b9504695a/packages/backend/convex/routes/agent/mcp/route.ts) MCP, [`document.ts`](https://github.com/nakafaai/nakafa.com/blob/2fae54fec31b7cd630a56933b613fa5b9504695a/packages/backend/agent/openapi/document.ts) erzeugt OpenAPI und [`program.ts`](https://github.com/nakafaai/nakafa.com/blob/2fae54fec31b7cd630a56933b613fa5b9504695a/packages/cli/src/program.ts) besitzt die CLI Befehlsoberfläche. ## Öffentliche REST API Die kanonische API Basis ist [https://api.nakafa.com/v1](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. File: search.sh ```bash curl "https://api.nakafa.com/v1/search?query=lineare%20gleichungen&locale=de&limit=5" ``` ## OpenAPI und Fehler Der [Nakafa OpenAPI 3.1 Vertrag](https://api.nakafa.com/openapi.json) 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. File: problem.json ```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](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. File: mcp.http ```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. File: nakafa-cli.sh ```bash 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 - [Entwicklerseite](https://nakafa.com/de/developers) - [Agent-Anweisungen](https://nakafa.com/skill.md) - [Zentraler Agent-Index](https://nakafa.com/llms.txt) - [OpenAPI 3.1](https://api.nakafa.com/openapi.json)