tafsir-mcp: Instructions file for Claude Code

Tafsir MCP Server

📍 اقرأ STATE.md (في الجذر) أولًا للحالة الحيّة (الإصدار المنشور، الصورة، العمل الجاري). هذا الملف للقواعد والعادات الثابتة.

Project Overview

MCP server providing scholarly, certified access to the Quran with 5 classical Arabic tafsirs (Tabari, Ibn Kathir, Baghawi, Saadi, Muyassar), word-level grammatical analysis (i'rab, sarf, root), qira'at variants, asbab al-nuzool, and surah statistics. Sponsored by Tafsir Center for Quranic Studies (https://tafsir.net). Religious content — accuracy is paramount.

Sponsoring Organization

This project is sponsored by Tafsir Center for Quranic Studies (مركز تفسير للدراسات القرآنية, https://tafsir.net). The Quranic database is reviewed and certified by the Center's scholars.

Tech Stack

• Python 3.12 with FastMCP (mcp[cli] >= 1.27.0)
• SQLite 3 + FTS5 for full-text search
• Pydantic v2 for input validation (strict mode)
• pyarabic for Arabic text normalization

Critical Rules (NEVER VIOLATE)

1. No content generation. Tools return data verbatim from the database. Never summarize, paraphrase, or "improve" religious text.
2. Always attribute. Every tafsir response includes a source field with author name, book title, death year.
3. Strict input validation. Every tool parameter uses Pydantic Field with constraints (e.g., surah: int = Field(ge=1, le=114)).
4. Parametrized SQL only. Use ? placeholders. Never f-string SQL.
5. All Quranic ayah counts MUST validate against 6236 total ayahs and 114 surahs.

FastMCP Parameter Pattern (Critical Bug Avoidance)

NEVER write param: int = Field(ge=1, le=114, default=1) in tool/prompt functions. The Field() object becomes the default value (FieldInfo) instead of the integer — silent bug.

ALWAYS use Annotated with a separate Python default:

# ✅ CORRECT
from typing import Annotated
param: Annotated[int, Field(ge=1, le=114)] = 1

# ❌ WRONG — passes FieldInfo to SQLite, causes ProgrammingError
param: int = Field(ge=1, le=114, default=1)

Required params (no default): param: Annotated[int, Field(ge=1, le=114)] — no = value.