hadith-mcp

hadith-mcp is a Model Context Protocol server for retrieving hadith text and metadata from auditable sources.

The project goal is to give AI assistants and developer tools a strict source layer for the Sunnah: exact references, Arabic text, available English translations, source-attributed grading, and clear provenance. The MCP server should retrieve and cite source material; it should not act as a mufti or generate unsupported religious claims.

V1 Direction

• TypeScript MCP server distributed as a local npm package.
• Read-only SQLite database with FTS5 search.
• Initial target scope: the Six Books.
• Arabic text required for imported hadith.
• English text included when the selected source provides it.
• Grades exposed only when they are source-attributed.
• No model-generated explanation or interpretation returned by MCP tools.

Implemented MCP Tools

• list_collections
• fetch_hadith
• search_hadith
• validate_hadith_reference
• get_hadith_metadata
• get_hadith_grade

See docs/mcp-tools.md for the implemented interface.

See docs/client-setup.md for local MCP client configuration examples.

See docs/v1-build-plan.md for the implementation plan, release gates, and first sprint.

See docs/future-product-plan.md for how this MCP should support a later Quran/Hadith AI product in a separate repository.

Local Development

npm install
npm run typecheck
npm test
npm run build
npm run audit:meeatif-hadith-datasets
npm run build:fixture-sqlite
npm run build:meeatif-sqlite
npm run docs:dev
node packages/hadith-mcp/dist/cli.js
HADITH_MCP_DB_PATH=data/generated/hadith-meeatif.sqlite node packages/hadith-mcp/dist/cli.js

Without HADITH_MCP_DB_PATH, the MCP server runs against synthetic fixture records for schema and client integration tests. The fixture records are not real hadith text and must not be used for religious claims.

The meeAtif audit command writes the active candidate-source report to data/generated/.

The fixture SQLite command writes a synthetic non-release database to data/generated/hadith-fixture.sqlite.

The meeAtif SQLite command writes a local candidate database to data/generated/hadith-meeatif.sqlite and import reports to data/generated/hadith-meeatif-import-report.{json,md} after the project owner accepted the source-chain risk for local v1 import work. Set HADITH_MCP_DB_PATH to this database path to run SQLite-backed MCP tools locally. Generated SQLite artifacts remain ignored by git until a later release decision includes the required data-license notice.

The meeAtif importer uses in-book references as canonical hadith_number values, such as 10:1, rather than simple collection-wide numbers. SQLite-backed lookup also accepts collection-prefixed references such as bukhari:10:1 and source references such as https://sunnah.com/bukhari:603 or bukhari:603 when the source row provides them. Use validate_hadith_reference for suggestions when an exact lookup misses.

The docs website lives in apps/docs and is built with Next.js and Tailwind CSS. During development it runs at http://127.0.0.1:3000 by default. Arabic is the default page at /, with English at /en.

Future Product Direction

The Hadith MCP is intended to become one source layer for a broader Islamic source retrieval product that should live in a separate repository:

• Tafsir MCP handles Quran and tafsir retrieval.
• Hadith MCP handles Sunnah retrieval.
• A public web app can orchestrate both.
• An open-source/open-weight model can provide retrieval-grounded cited answers, using the MCPs as the source of truth.

Current Status

This repository currently contains the project plan, source policy, v1 build plan, a TypeScript MCP server with fixture and SQLite-backed modes, and a local meeAtif import path for candidate SQLite builds.