Metadata-Version: 2.4
Name: wideholy-mcp
Version: 0.1.1
Summary: Unified MCP server for WideHoly — cross-religion scripture search, verse comparison, and commentary for AI assistants.
Project-URL: Homepage, https://wideholy.com
Project-URL: Repository, https://github.com/wideholy/wideholy-mcp
Author: WideHoly
License-Expression: MIT
License-File: LICENSE
Keywords: ai-tools,bible,cross-religion,gita,mcp,model-context-protocol,quran,religion,scripture,sutra,torah,verse-comparison,wideholy
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Religion
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27
Requires-Dist: mcp>=1.0
Provides-Extra: all
Requires-Dist: widebible[mcp]; extra == 'all'
Requires-Dist: widegita[mcp]; extra == 'all'
Requires-Dist: widequran[mcp]; extra == 'all'
Requires-Dist: widesutra[mcp]; extra == 'all'
Requires-Dist: widetorah[mcp]; extra == 'all'
Provides-Extra: bible
Requires-Dist: widebible[mcp]; extra == 'bible'
Provides-Extra: dev
Requires-Dist: mypy>=1.15; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.11; extra == 'dev'
Provides-Extra: gita
Requires-Dist: widegita[mcp]; extra == 'gita'
Provides-Extra: quran
Requires-Dist: widequran[mcp]; extra == 'quran'
Provides-Extra: sutra
Requires-Dist: widesutra[mcp]; extra == 'sutra'
Provides-Extra: torah
Requires-Dist: widetorah[mcp]; extra == 'torah'
Description-Content-Type: text/markdown

# wideholy-mcp

[![PyPI](https://img.shields.io/pypi/v/wideholy-mcp)](https://pypi.org/project/wideholy-mcp/)
[![Python](https://img.shields.io/pypi/pyversions/wideholy-mcp)](https://pypi.org/project/wideholy-mcp/)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)

Unified MCP server for **WideHoly** -- cross-religion scripture search, verse comparison, verse of the day, religious calendar, and commentary for AI assistants. Access 236,866 scripture records across 5 world religions through a single MCP server that aggregates tools from all WideHoly religion packages.

Built on the [WideHoly](https://wideholy.com) platform -- a cross-religion hub aggregating [WideBible](https://widebible.com), [WideQuran](https://widequran.com), [WideTorah](https://widetorah.com), [WideGita](https://widegita.com), and [WideSutra](https://widesutra.com) into a unified scripture search with comparison tools, shared topics, and a religious calendar.

> **Explore the interactive tools at [wideholy.com](https://wideholy.com)** -- [Compare Verses](https://wideholy.com/developers/), [Religious Calendar](https://wideholy.com/developers/), [Cross-Religion Topics](https://wideholy.com/topics/)

## Table of Contents

- [Install](#install)
- [Configuration](#configuration)
  - [Claude Desktop](#claude-desktop)
  - [Cursor](#cursor)
  - [Windsurf](#windsurf)
- [Available Tools](#available-tools)
  - [Hub Tools (9)](#hub-tools-9)
  - [Per-Religion Tools](#per-religion-tools)
- [Usage Examples](#usage-examples)
- [How It Works](#how-it-works)
- [WideHoly Family](#wideholy-family)
- [License](#license)

## Install

```bash
# Hub server only (9 cross-religion tools)
pip install wideholy-mcp

# With specific religion tools
pip install "wideholy-mcp[bible]"
pip install "wideholy-mcp[quran]"
pip install "wideholy-mcp[torah,gita,sutra]"

# All religion tools
pip install "wideholy-mcp[all]"
```

The hub server provides 9 cross-religion tools out of the box. Installing per-religion extras adds religion-specific tools (e.g. Bible cross-references, Quran tafsir lookup, Torah Talmud search) that are dynamically registered on the hub server.

## Configuration

### Claude Desktop

Add to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "wideholy": {
      "command": "uvx",
      "args": ["--from", "wideholy-mcp[all]", "python", "-m", "wideholy_mcp.server"]
    }
  }
}
```

### Cursor

Add to `.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "wideholy": {
      "command": "uvx",
      "args": ["--from", "wideholy-mcp[all]", "python", "-m", "wideholy_mcp.server"]
    }
  }
}
```

### Windsurf

Add to `~/.windsurf/mcp.json`:

```json
{
  "mcpServers": {
    "wideholy": {
      "command": "uvx",
      "args": ["--from", "wideholy-mcp[all]", "python", "-m", "wideholy_mcp.server"]
    }
  }
}
```

## Available Tools

### Hub Tools (9)

These tools are always available, regardless of which extras are installed.

| Tool | Description |
|------|-------------|
| `verse_of_the_day` | Get curated daily verse for any religion (bible, quran, torah, gita, sutra) |
| `random_verse` | Random verse from one or all 5 religions |
| `compare_verses` | Side-by-side verse comparison -- same religion or cross-religion |
| `search_all` | Search topics, people, and glossary terms across all religions |
| `cross_religion_topic` | Thematic comparison across religions (creation, love, prayer, etc.) |
| `get_commentary` | Scholarly commentary -- Quran tafsir, Torah Rashi, Gita commentaries |
| `get_calendar` | Religious holidays, fasts, festivals across all 5 traditions |
| `search_suggest` | Autocomplete suggestions for scripture search |
| `list_religions` | List all 5 religions with scripture stats and site URLs |

### Per-Religion Tools

When you install per-religion extras, their specialized tools are dynamically registered on the hub server with a religion prefix. Tools gracefully degrade -- if a package is not installed, its tools are simply not available.

| Extra | Package | Example Tools |
|-------|---------|---------------|
| `bible` | [widebible](https://pypi.org/project/widebible/) | `bible_search_verses`, `bible_get_book`, `bible_cross_references` |
| `quran` | [widequran](https://pypi.org/project/widequran/) | `quran_search_ayahs`, `quran_get_surah`, `quran_tafsir` |
| `torah` | [widetorah](https://pypi.org/project/widetorah/) | `torah_search_verses`, `torah_get_book`, `torah_talmud_search` |
| `gita` | [widegita](https://pypi.org/project/widegita/) | `gita_get_chapter`, `gita_get_verse`, `gita_search` |
| `sutra` | [widesutra](https://pypi.org/project/widesutra/) | `sutra_list_collections`, `sutra_list_figures`, `sutra_search_sutra` |

## Usage Examples

Once configured, ask your AI assistant:

- "What is the verse of the day from the Quran?"
- "Compare Genesis 1:1 with the opening of the Quran"
- "What do different religions say about creation?"
- "Show me the religious calendar for April 2026"
- "Get commentary on Quran Al-Fatihah verse 1"
- "Search for verses about compassion across all religions"
- "List all available religions and their scripture counts"
- "Find Buddhist figures related to compassion"

### Cross-Religion Topics

The `cross_religion_topic` tool supports 10 universal themes:

| Topic | Description |
|-------|-------------|
| creation | Origin of the universe and humanity |
| prayer | Communication with the divine |
| love | Divine and human love |
| afterlife | Death, judgment, and eternal life |
| compassion | Mercy, kindness, and empathy |
| fasting | Spiritual discipline and abstinence |
| forgiveness | Repentance and divine pardon |
| gratitude | Thankfulness and praise |
| justice | Righteousness and moral law |
| wisdom | Knowledge, understanding, and truth |

## How It Works

`wideholy-mcp` follows the hub-and-spoke pattern:

1. **Hub tools** (9) make HTTP requests to the [WideHoly API](https://wideholy.com/api/v1/) for cross-religion functionality
2. **Per-religion tools** are dynamically imported from installed packages at startup
3. Each per-religion tool is re-registered on the hub server with a religion prefix (e.g. `sutra_list_collections`)
4. If a religion package is not installed, its tools are silently skipped -- no errors

This means you can start with just the hub (`pip install wideholy-mcp`) and add religion-specific tools later as needed.

## WideHoly Family

| Site | Domain | Focus |
|------|--------|-------|
| WideBible | [widebible.com](https://widebible.com) | 66 books, 124K verses, 6 translations, commentaries |
| WideQuran | [widequran.com](https://widequran.com) | 114 surahs, 31K ayahs, tafsir, hadith collections |
| WideTorah | [widetorah.com](https://widetorah.com) | 24 Tanakh books, 63 Talmud tractates, Rashi commentary |
| WideGita | [widegita.com](https://widegita.com) | 18 chapters, 6,800 verses, Sanskrit, multiple commentaries |
| WideSutra | [widesutra.com](https://widesutra.com) | 5 collections, 5,326 texts, Pali/Sanskrit traditions |
| **WideHoly** | [**wideholy.com**](https://wideholy.com) | **Cross-religion hub -- comparison, calendar, unified search** |

| Package | PyPI | Description |
|---------|------|-------------|
| wideholy | [PyPI](https://pypi.org/project/wideholy/) | Python SDK -- API client, CLI, embedded MCP server |
| **wideholy-mcp** | [PyPI](https://pypi.org/project/wideholy-mcp/) | **Unified MCP hub -- 9 tools + per-religion aggregation** |
| widebible | [PyPI](https://pypi.org/project/widebible/) | Bible SDK -- verses, people, places, cross-references |
| widequran | [PyPI](https://pypi.org/project/widequran/) | Quran SDK -- ayahs, surahs, tafsir, hadith |
| widetorah | [PyPI](https://pypi.org/project/widetorah/) | Torah SDK -- Tanakh, Talmud, Rashi commentary |
| widegita | [PyPI](https://pypi.org/project/widegita/) | Gita SDK -- chapters, verses, Sanskrit, commentaries |
| widesutra | [PyPI](https://pypi.org/project/widesutra/) | Sutra SDK -- collections, figures, concepts, traditions |

## Learn More About World Scriptures

- **Scripture**: [WideBible](https://widebible.com/) · [WideQuran](https://widequran.com/) · [WideTorah](https://widetorah.com/) · [WideGita](https://widegita.com/) · [WideSutra](https://widesutra.com/)
- **Reference**: [Cross-Religion Topics](https://wideholy.com/topics/) · [Religious Calendar](https://wideholy.com/developers/)
- **Study**: [Verse Comparison](https://wideholy.com/developers/) · [Commentary](https://wideholy.com/developers/)
- **Tools**: [Search](https://wideholy.com/) · [Developer Docs](https://wideholy.com/developers/)
- **API**: [Developer Docs](https://wideholy.com/developers/) · [OpenAPI Spec](https://wideholy.com/api/schema/)

## License

MIT License. See [LICENSE](LICENSE) for details.
