# turath

Cited *ibaroh* — raw, sourced passages — from a corpus of **7,872 classical
Islamic books** (*kitab turats*: fiqh, usul, hadith commentary, tafsir, and
more), pulled through the [Sahifah](https://sahifah.online) API.

You query in Indonesian, English, or Arabic; the corpus is searched in Arabic;
you get back the **original passage** — not a paraphrase — with its full
citation: book, author, table-of-contents path, juz, and page. A *mu'tabar*
filter keeps results to works recognized as authoritative in the tradition.

This repo ships three ways to use it, all built on the same read-only,
revocable Sahifah researcher API key (prefixed `bm_`):

1. A **Claude Code plugin** bundling the `/turath` skill and a remote MCP
   connector.
2. A **`/turath` skill** you can drop into any Claude Code project on its own.
3. A **remote MCP server** (`turath_search`, `get_ibaroh`) for any
   MCP-speaking agent — plus the raw HTTP API underneath it.

> **Adab of naql (the ethic of transmission).** Everything here surfaces what
> the Sahifah corpus *indexed*; it is not a substitute for opening the actual
> kitab. Every result ends with a reminder to verify the quotation against the
> primary source before relying on it — especially for anything bound for a
> fatwa, an argument, or published writing. Where a passage looks truncated or
> OCR-garbled, treat it as uncertain. Where the fuqaha differ, note the
> *khilaf* rather than picking a side. *Allahu a'lam.*

## Getting an API key

Sign in at **[sahifah.online](https://sahifah.online)** and create a key from
the **`/api-keys`** dashboard. Keys are read-only, rate-limited, capped per
user, and revocable at any time. The key is never stored or logged by anything
in this repo — it is read from your environment or passed per-request.

```sh
export SAHIFAH_API_KEY=bm_your_key_here        # bash / zsh
$env:SAHIFAH_API_KEY = "bm_your_key_here"      # PowerShell
```

## 1. Install as a Claude Code plugin

```
/plugin marketplace add dihannahdi/turath
/plugin install turath@sahifah
```

This registers the `/turath` skill and connects the remote MCP server
(`https://sahifah.online/mcp`). Set `SAHIFAH_API_KEY` in your environment first
so the MCP connector can authenticate (see `.mcp.json`).

## 2. Use the `/turath` skill directly

The skill lives in `skills/turath/` and drives a stdlib-only Python script —
no dependencies to install.

```sh
# search for candidate passages
python skills/turath/scripts/turath.py search "hukum zakat fitrah dengan uang" --max 10

# restrict to mu'tabar (authoritative) kitab only
python skills/turath/scripts/turath.py search "penyakit hasad dalam hati" --mutabar-only

# fetch a full passage by the book_id / toc_id printed above
python skills/turath/scripts/turath.py ibaroh 123 456
```

See `skills/turath/SKILL.md` for the full command reference and the adab of
naql the skill carries through its output.

## 3. Remote MCP server

The server is a stateless [Streamable HTTP](https://modelcontextprotocol.io)
MCP server exposing two tools:

- **`turath_search`** — search the corpus; returns each passage's citation,
  book/author, TOC path, page/juz, madhhab, era, and relevance score.
- **`get_ibaroh`** — given a `book_id`/`toc_id` from a search, fetch the full
  passage text and complete citation.

Add it as a Claude connector (or with `claude mcp add`):

```sh
claude mcp add turath --transport http https://sahifah.online/mcp \
  --header "X-Sahifah-Api-Key: bm_your_key_here"
```

The server never hardcodes or stores a key. For each request it resolves the
key to forward from, in order: an `Authorization: Bearer <key>` header, an
`X-Sahifah-Api-Key` / `X-Api-Key` header, or its own `SAHIFAH_API_KEY` env var
(single-tenant fallback). The key is never logged.

### Self-hosting the MCP server

The TypeScript source is in `src/` and is what runs behind
`https://sahifah.online/mcp`. To run your own instance:

```sh
npm install
npm run build      # tsc -> dist/
npm start          # node dist/index.js   (listens on PORT, default 8795)
```

Put a reverse proxy in front for TLS and never expose the raw port publicly.
See the comments in `src/index.ts` and `ecosystem.config.cjs` (PM2) for the
deployment shape. Configuration lives in `.env` (see `.env.example`):
`SAHIFAH_API_BASE` is fixed at startup and never taken from request input.

## Underlying HTTP API

Both the skill and the MCP server sit on the public Sahifah API:

- `POST /api/v1/search` — `{ query, max_results?, mutabar_only?, include_ai? }`,
  auth via `X-API-Key`. `include_ai` defaults to `false` — raw ibaroh first.
- `POST /api/v1/passage` — `{ book_id, toc_id }` → full passage + citation.

## Layout

```
turath/
├── .claude-plugin/
│   ├── plugin.json        # plugin manifest
│   └── marketplace.json   # single-plugin marketplace (name: sahifah)
├── .mcp.json              # remote MCP connector (auto-discovered by the plugin)
├── skills/turath/
│   ├── SKILL.md           # the /turath skill
│   └── scripts/turath.py  # stdlib-only client
├── src/                   # TypeScript MCP server (Express + @modelcontextprotocol/sdk)
├── package.json
├── tsconfig.json
├── ecosystem.config.cjs   # PM2
└── .env.example
```

## Validate before publishing

```sh
claude plugin validate .
```

## License

MIT — see [LICENSE](./LICENSE).