# Turath MCP

[![npm version](https://img.shields.io/npm/v/turath-mcp.svg)](https://www.npmjs.com/package/turath-mcp)
[![turath-sdk](https://img.shields.io/npm/v/turath-sdk.svg?label=powered%20by&color=blue)](https://www.npmjs.com/package/turath-sdk)
[![license](https://img.shields.io/npm/l/turath-mcp.svg)](LICENSE)

An [MCP](https://modelcontextprotocol.io) (Model Context Protocol) server that
gives AI clients fast, accurate access to the books and resources of
[turath.io](https://turath.io) — authors, book metadata, parsed pages, full book
dumps, and catalog search — over **stdio** and **Streamable HTTP**.

Every request is routed through the [turath-sdk](https://www.npmjs.com/package/turath-sdk)
package to the turath.io API. The AI handles the natural language; the server
returns the exact data from turath.io, attributed with a `source` block.

## Features

- 🔌 **MCP compatible** — Claude Desktop, Claude Web, ChatGPT, Cursor, VS Code, and others.
- 🌐 **Two transports** — stdio for local integrations, Streamable HTTP for remote/hosted.
- 🔍 **Five tools** — author biographies, book metadata + indexes, full book files, parsed pages, and catalog search with filters.
- 📖 **Accurate results** — every answer comes from turath.io via `turath-sdk`; no LLM in the loop.
- 🛡️ **Hardened HTTP** — host allow-list, per-IP rate limit, body cap, session reaper, `/health`.
- 🗄️ **Offline-friendly cache** — turath.io responses cached in memory (and optionally on disk) for 30 days.

## Install

```bash
# Run the server locally (stdio)
npx -y turath-mcp
```

## Documentation

Detailed docs live under [`docs/`](docs/index.md):

- [Tools reference](docs/tools.md) — every tool, its schema, response shape, and examples.
- [Integrations](docs/integrations.md) — Claude Desktop, Claude Web, ChatGPT, Cursor, and others.
- [Architecture](docs/architecture.md) — internals: transports, API client, caching, HTTP hardening.
- [Development](docs/development.md) — build, test, add a new tool, deploy.

## Quick start (stdio)

```bash
npx -y turath-mcp
```

This runs the server over stdio. Use it with Claude Desktop, Cursor, or any
other MCP client that supports the stdio transport.

## Quick start (HTTP)

```bash
npx -y turath-mcp --http
# → "Turath MCP HTTP server listening on http://0.0.0.0:4000/"
```

Point your MCP client at `http://localhost:4000/`. The server also exposes
`GET /health` for status checks. Configure with `PORT`, `HOST`, and the
`MCP_*` variables documented in [docs/architecture.md](docs/architecture.md).

## Quick start (Docker)

```bash
docker compose up --build
# → "Turath MCP HTTP server listening on http://0.0.0.0:4000/"
```

## Requirements

- Node.js 22+ (required by `turath-sdk`)
- npm, pnpm, or yarn (project is `yarn@1.22.22`)
- Network access to `api.turath.io` and `files.turath.io` (all five tools are remote calls)

## License

MIT — see [LICENSE](LICENSE).

## Contact

Email: [contact@adelpro.us.kg](mailto:contact@adelpro.us.kg)