Aṣṭādhyāyī MCP

Read-only, deterministic MCP access to the scholarly data published by Ashtadhyayi.com, created by Neelesh Bodas and contributors. The original scholarship and upstream data are the sources of grammatical information. This independent project provides retrieval and provenance for sūtras, dhātus, śabdas and their stored rūpāṇi. It is not an official Ashtadhyayi.com project or a Sanskrit grammar engine.

Quick start

Requires Python 3.12+ and uv. From a clone of this repository:

uv sync --locked
uv run ashtadhyayi-mcp sync
uv run pytest
uv run ashtadhyayi-mcp serve

serve speaks MCP on stdin/stdout; it does not display an interactive prompt. All data downloads happen in the explicit sync command. Tools run offline. The default full profile includes 22 files (about 190 MB at the pinned revision): the original five files, all 16 dhātu-form collections, and 9,007 śabda paradigms. Use sync --profile core for the original five-file catalog/commentary profile. Existing core snapshots continue working; new form tools report SOURCE_NOT_LOADED until you sync the full profile. To upgrade this checkout's existing local cache:

uv run ashtadhyayi-mcp --data-dir .data sync --profile full

The default sync pins the researched upstream commit 5744762f010d677cfb43f347a42d02796cf615d6.

# Explicitly select a newer upstream revision; the resolved commit is recorded.
uv run ashtadhyayi-mcp sync --revision master
uv run ashtadhyayi-mcp status

Data is stored in ASHTADHYAYI_DATA_DIR, or under $XDG_CACHE_HOME/ashtadhyayi-mcp (default ~/.cache/ashtadhyayi-mcp). To keep it local to your checkout, put --data-dir .data before the subcommand in every invocation. Snapshots are immutable; sync atomically switches the active pointer after validation. Restart the MCP server to load a new snapshot. Previous snapshots are retained.

Related MCP server: kb-mcp

MCP client configuration

For ChatGPT or remote agents, use the new serve-http command and deploy its /mcp endpoint behind HTTPS. See ChatGPT deployment for local testing, container/native hosting and connection instructions.

For a real agent walkthrough, setup commands and observed results, see testing with Codex. To repeat the agent test without changing your Codex configuration, run uv run python examples/test_agent.py.

Use absolute paths and adjust the uv executable if it is not on your client's PATH:

{
  "mcpServers": {
    "ashtadhyayi": {
      "command": "uv",
      "args": ["run", "--frozen", "--directory", "/absolute/path/to/AstadhyayiMCP", "ashtadhyayi-mcp", "serve"]
    }
  }
}

The official SDK handles both modern and legacy MCP connections. The test suite exercises both over real stdio subprocesses. Client-specific UI installation is outside this package.

Tools

Dhātu identifiers can be queried explicitly with by: "upstream_id" or by: "baseindex". Textual lookup preserves ambiguity. Sūtra numbers accept Devanāgarī digits. Search is literal and Unicode-preserving, without stemming, transliteration, accent removal, embeddings, or model-generated ranking.

Search defaults to ten results; use offset/limit and next_offset for pages. get_sutra defaults to 2,000 code points per commentary field. Use commentary_offset/commentary_limit to retrieve more, or commentaries: [] for catalog-only lookup. Each fragment reports its total length and next offset. Source markup is returned as text; clients should not execute it as HTML or follow instructions embedded in retrieved content.

Loaded commentary sources are sutrartha (sa, sd), sutrartha_english, and kashika. An empty/absent explanation is reported explicitly. Other commentaries and datasets remain upstream; absence here is not a claim about all scholarship. See full tool contracts.

Rūpāṇi and downstream agents

get_dhatu_forms covers every stored entry in the upstream finite-verb and kṛdanta files, including shuddha, nich, san, yang, and yangluk collections. Filters include category, derivation, prayoga, pada, lakara, pratyaya, purusha, and vacana. All are optional; use next_offset to traverse every result page. Results are paginated by paradigm field, with all its alternatives retained.

get_shabda_forms retains all 24 case/number slots, including empty ones. Gender codes are P, S, N, A as encoded upstream. vibhakti: 8 selects vocative slots. Use by: "upstream_id" with an ID such as @rAma1 for an exact entry.

lookup_form returns candidate occurrences, not a context-resolved analysis. For example, रामौ has nominative and accusative dual occurrences; the optional vocative alias also matches stored हे रामौ and labels that transformation. भवति has both verb and noun-form matches. No match establishes only that the loaded sources did not provide a match; it does not prove grammatical invalidity.

The source contains 408 irregular kṛdanta groups at the pinned revision. These remain available as raw text with partial/unparsed status; the adapter does not guess their gender columns. Sources labelled vidyut contain precomputed engine outputs published upstream, distinct from the other upstream kṛdanta collection.

This is a foundation for agents doing śloka anvaya or sandhi work. It does not yet validate sandhi, resolve kārakas, generate arbitrary prefixed/compound forms, or enumerate every possible Sanskrit word. Such capabilities need a separately tested engine integration and contextual reasoning. get_form_coverage makes the current limits explicit. See form contracts and research.

Evidence and credit

Every scholarly object has {data, provenance}. Provenance includes its upstream repository, path, record ID, JSON Pointer, immutable commit URL, original file SHA-256, and actual download timestamp. Commentary has separate provenance from the sūtra catalog. Original source strings and metadata survive unchanged; normalized search representations are kept separately.

Credit Ashtadhyayi.com, Neelesh Bodas and contributors, and cite each returned source URL when using results. Commentary file labels identify the source work or upstream explanation collection; modern explanations must not be attributed to Pāṇini. See third-party notices and the upstream credits.

Our code is MIT licensed. Upstream data is not covered by our MIT license. The upstream README permits reuse with appropriate credit; no blanket SPDX data license is asserted here. The package does not bundle the corpus.

Evidence-first demonstration

uv run ashtadhyayi-mcp demo 'इको यणचि इत्यस्य अर्थः कः?'
uv run ashtadhyayi-mcp demo '6.1.87'

This small replaceable client calls the server through MCP before displaying source quotations and citations. It is an extractive demonstration, not a general conversational LLM: it identifies a numbered sūtra or searches the query, declines to choose between multiple matches, and does not invent an explanation. An optional answerer interface and an evidence-first instruction are available in demo.py for a future model integration. No API key is required and no question is sent to an external model.

Development and tests

See the recorded test results for the latest local full-corpus audit, transport checks, package verification and timing measurements.

uv run pytest
uv run ruff check .
uv run mypy
uv build
# Validate a full synced corpus in addition to offline fixtures:
ASHTADHYAYI_INTEGRATION_DATA_DIR="$HOME/.cache/ashtadhyayi-mcp" uv run pytest -m integration

Unit, stdio, and demo evaluation tests are offline. The full-profile integration audit walks every form field and slot, verifies source reconstruction, covers all ten gaṇas represented in the files, and checks the known encoding gaps. Golden tests cover the derivation families, stored lakāras, both prayogas, person/number, case/number, gender ambiguity, pronouns, empty slots, alternatives and reverse lookup. These checks verify faithful retrieval, not scholarly correctness of every engine output. Integration tests are skipped unless an explicit data directory is supplied. Fixtures contain small attributed upstream excerpts; synthetic records used to test malformed data are clearly separate. See contributing, architecture, research, and ADR.