# Sumber Daya Pengembang Nakafa

> 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/id/developers
Source: https://raw.githubusercontent.com/nakafaai/aksara/11c10d705985738d79e314865fa46c0cd824756b/packages/corpus/pages/developers/id.mdx

Gunakan REST API publik, kontrak OpenAPI, server MCP, dan klien baris perintah Nakafa untuk alur pendidikan yang andal.

---

# Sumber Daya Pengembang Nakafa

Terakhir diperbarui: 27 Agustus 2026

Nakafa menyediakan akses publik yang dapat dibaca mesin ke materi belajar multibahasa dan referensi Quran dengan rentang terbatas. Antarmuka ini cocok untuk agen dan aplikasi yang memerlukan input bertipe, kegagalan yang dapat diprediksi, dan referensi konten kanonis. Semua akses bersifat baca-saja, tidak memerlukan akun Nakafa, serta tidak membuka data pelajar privat, pembelian, atau tindakan akun.

## Implementasi terverifikasi

Antarmuka publik ini telah diverifikasi langsung terhadap commit Nakafa [`2fae54fec31b7cd630a56933b613fa5b9504695a`](https://github.com/nakafaai/nakafa.com/commit/2fae54fec31b7cd630a56933b613fa5b9504695a): indeks REST dan kontrak OpenAPI mengembalikan identitas rilis yang sama, bridge MCP kanonis menyelesaikan penemuan protokol, dan `nakafa-cli@0.1.0` tersedia dari npm.

Pada revisi tersebut, [`api.ts`](https://github.com/nakafaai/nakafa.com/blob/2fae54fec31b7cd630a56933b613fa5b9504695a/packages/backend/convex/routes/agent/api.ts) memiliki REST, [`route.ts`](https://github.com/nakafaai/nakafa.com/blob/2fae54fec31b7cd630a56933b613fa5b9504695a/packages/backend/convex/routes/agent/mcp/route.ts) memiliki MCP, [`document.ts`](https://github.com/nakafaai/nakafa.com/blob/2fae54fec31b7cd630a56933b613fa5b9504695a/packages/backend/agent/openapi/document.ts) menghasilkan OpenAPI, dan [`program.ts`](https://github.com/nakafaai/nakafa.com/blob/2fae54fec31b7cd630a56933b613fa5b9504695a/packages/cli/src/program.ts) memiliki permukaan perintah CLI.

## REST API publik

Alamat dasar API kanonis adalah [https://api.nakafa.com/v1](https://api.nakafa.com/v1). Mulai dari indeks layanan dan gunakan pencarian untuk menemukan hasil yang relevan. Ambil hasil melalui ID konten hanya jika hasil tersebut memuat `markdown_url`. Hasil katalog try-out tanpa `markdown_url` hanya untuk sitasi dan menautkan URL aplikasi kanonisnya. API juga menyediakan taksonomi terbitan dan referensi ayat Quran dengan rentang yang jelas.

- `GET /v1`: identitas layanan dan tautan penemuan
- `GET /v1/health`: kesehatan layanan
- `GET /v1/search`: pencarian berdasarkan kueri, bagian, bahasa, limit, dan offset
- `GET /v1/content?ref=...`: pengambilan ID konten atau URL kanonis yang tepat
- `GET /v1/taxonomy`: taksonomi terbitan
- `GET /v1/quran/{surah}`: pengambilan rentang ayat bertipe

Pencarian mengembalikan 10 hasil secara bawaan dan menerima maksimum 50 hasil per permintaan. Gunakan `offset`, `has_more`, dan `next_offset` untuk melanjutkan kumpulan hasil tanpa menebak. Klien sebaiknya membatasi anggaran hingga 120 permintaan per 60 detik dari satu IP dan menangani respons HTTP 429 dengan jeda bertahap.

File: search.sh
```bash
curl "https://api.nakafa.com/v1/search?query=persamaan%20linear&locale=id&limit=5"
```

## OpenAPI dan kegagalan

[Kontrak OpenAPI 3.1 Nakafa](https://api.nakafa.com/openapi.json) menjelaskan setiap operasi publik, input, respons, dan contoh. Penambahan yang kompatibel tetap berada di `v1`. Perubahan yang merusak kontrak memerlukan jalur mayor baru.

Kegagalan API yang berasal dari Convex menggunakan RFC 9457 Problem Details dengan media type `application/problem+json`. Setiap respons memuat `code` yang stabil, `detail` yang mudah dipahami, `resolution` yang dapat dikerjakan, dan `request_id` yang dapat ditelusuri. HTTP 429 dari Vercel Firewall dapat menghentikan permintaan sebelum mencapai Convex, sehingga klien harus memperlakukannya sebagai pengecualian milik platform dan mencoba lagi dengan jeda bertahap.

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

Endpoint MCP kanonis berada di [https://nakafa.com/mcp](https://nakafa.com/mcp). Gunakan MCP ketika agen sudah mendukung penemuan tool dan pemanggilan tool terstruktur. Gunakan REST untuk integrasi HTTP biasa atau klien yang dibuat dari OpenAPI. Kedua antarmuka menjalankan kapabilitas yang sama di Convex dan memverifikasi publikasi Aksara bertanda tangan yang sama.

Server menyediakan empat tool baca-saja:

- `nakafa_search_content`
- `nakafa_get_content`
- `nakafa_get_taxonomy`
- `nakafa_get_quran_reference`

Klien modern menggunakan Streamable HTTP. Protokol `2026-07-28` menggantikan siklus `initialize` lama dengan `server/discover` dan envelope `_meta` pada setiap permintaan. Klien terlebih dahulu menemukan revisi yang didukung, lalu membuat daftar atau memanggil tool dengan envelope yang sama. Nakafa menerima revisi protokol yang didokumentasikan ini dan melaporkan semua revisi yang didukung melalui penemuan. Identitas dan kapabilitas server berasal dari respons `server/discover`. Endpoint stateless Nakafa tidak menyediakan manifest `GET` terpisah.

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":{}}}}
```

## Baris perintah

Paket resmi untuk Node 24 bernama `nakafa-cli`, dengan executable `nakafa`. CLI memanggil REST API publik dan mencetak JSON ringkas secara bawaan. Tambahkan `--pretty` untuk keluaran yang mudah dibaca atau `--api-base` saat memverifikasi endpoint API kompatibel yang berjalan secara lokal atau dihosting secara mandiri.

File: nakafa-cli.sh
```bash
npm install --global nakafa-cli
nakafa search persamaan linear
nakafa quran 1 --from-verse 1 --to-verse 7 --pretty
nakafa mcp
```

CLI mempertahankan JSON Problem Details pada standard error dan menggunakan kategori exit bukan nol yang stabil untuk kegagalan pemanggilan, API, serta jaringan atau server.

## Penemuan yang dapat dibaca mesin

- [Halaman developer](https://nakafa.com/id/developers)
- [Petunjuk agen](https://nakafa.com/skill.md)
- [Indeks agen utama](https://nakafa.com/llms.txt)
- [OpenAPI 3.1](https://api.nakafa.com/openapi.json)