MCP 服务器

turath-mcp

MCP server that gives AI clients fast, accurate access to turath.io's books and resources, with tools for author biographies, book metadata, full texts, parsed pages, and catalog search over stdio or HTTP.

README

Turath MCP

An MCP (Model Context Protocol) server that gives AI clients fast, accurate access to the books and resources of 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 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

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

Documentation

Detailed docs live under docs/:

Tools reference — every tool, its schema, response shape, and examples.
Integrations — Claude Desktop, Claude Web, ChatGPT, Cursor, and others.
Architecture — internals: transports, API client, caching, HTTP hardening.
Development — build, test, add a new tool, deploy.

Quick start (stdio)

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)

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.

Quick start (Docker)

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)