# Sefaria API MCP

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![npm version](https://badge.fury.io/js/sefaria-api-mcp.svg)](https://www.npmjs.com/package/sefaria-api-mcp)

MCP (Model Context Protocol) server for accessing the Sefaria API - the largest open-source database of Jewish texts.

## Features

This MCP provides AI agents with full access to:
- **Tanakh** (Torah, Neviim, Ketuvim)
- **Talmud** (Bavli and Yerushalmi)
- **Mishnah** and other Rabbinic texts
- **Commentaries** (Rashi, Tosafot, etc.)
- **Topics** and cross-references
- **Search** across the entire library
- **Calendar** integration for daily readings

## Installation

### From GitHub

```bash
git clone https://github.com/davad00/sefaria-api-mcp.git
cd sefaria-api-mcp
npm install
npm run build
```

### From npm (coming soon)

```bash
npm install -g sefaria-api-mcp
```

### For ClawHub

This MCP includes a Claw skill in the `skills/` directory. Install via ClawHub or manually:

```bash
# Clone and install
git clone https://github.com/davad00/sefaria-api-mcp.git
cd sefaria-api-mcp
npm install
npm run build
```

## Quick Start

### Running the MCP Server

```bash
npm start
```

### Configure in Your MCP Client

Add to your MCP configuration file:

```json
{
  "mcpServers": {
    "sefaria": {
      "command": "node",
      "args": ["path/to/sefaria-api-mcp/dist/index.js"]
    }
  }
}
```

### Using the Claw Skill

The included skill provides helper tools:
- `connect` - Start the MCP server
- `use` - Show example usage patterns

## Example Queries

```javascript
// Get Genesis 1:1
{
  "name": "get_text",
  "arguments": { "tref": "Genesis 1:1" }
}

// Search for "love"
{
  "name": "search",
  "arguments": { "q": "love", "limit": 5 }
}

// Parse references from text
{
  "name": "find_refs",
  "arguments": { "text": "As it says in Shabbat 31a about lighting candles" }
}

// Get today's Torah readings
{
  "name": "get_calendars"
}

// Explore related content
{
  "name": "get_related",
  "arguments": { "tref": "Genesis 1:1" }
}
```

## API Tools

### Text Retrieval
| Tool | Description |
|------|-------------|
| `get_text` | Get text by reference (e.g., 'Genesis 1:1', 'Shabbat 2b') |
| `get_text_v1` | Legacy v1 text endpoint |
| `get_random_text` | Get random text segment |
| `get_manuscripts` | Get manuscript variants |

### Search & Discovery
| Tool | Description |
|------|-------------|
| `search` | Full-text search across library |
| `find_refs` | Parse text to find Sefaria references |
| `get_toc` | Table of contents (all available texts) |
| `get_category` | Texts in a specific category |

### Related Content
| Tool | Description |
|------|-------------|
| `get_related` | All related content (links, sheets, topics) |
| `get_links` | Cross-references to other sources |
| `get_topics` | Topic details |
| `get_all_topics` | List all topics |
| `get_ref_topic_links` | Topics linked to a reference |

### Lookup
| Tool | Description |
|------|-------------|
| `get_index` | Text metadata (structure, versions) |
| `get_shape` | Text structure |
| `get_lexicon` | Hebrew word definitions |
| `get_versions` | Available translations |

## Configuration

To use this MCP in your system, configure the connection:

```json
{
  "mcpServers": {
    "sefaria": {
      "command": "node",
      "args": ["path/to/SefariaApiMcp/dist/index.js"]
    }
  }
}
```

## Example Usage

```javascript
// Get Genesis 1:1
{
  "name": "get_text",
  "arguments": { "tref": "Genesis 1:1" }
}

// Search for "love"
{
  "name": "search",
  "arguments": { "q": "love", "limit": 5 }
}

// Parse references
{
  "name": "find_refs",
  "arguments": { "text": "As it says in Shabbat 31a about lighting candles" }
}

// Get today's readings
{
  "name": "get_calendars"
}

// Explore related content
{
  "name": "get_related",
  "arguments": { "tref": "Genesis 1:1" }
}
```


## Contributing

Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

## License

MIT License - see [LICENSE](LICENSE) for details.

## Links

- [Sefaria API Documentation](https://developers.sefaria.org/)
- [Model Context Protocol](https://modelcontextprotocol.io/)
- [ClawHub](https://clawhub.ai/)

## Support

- Open an issue on GitHub for bugs or feature requests
- Check the [Sefaria API docs](https://developers.sefaria.org/) for API details
- Join the discussion on ClawHub

## Acknowledgments

Built on top of the [Sefaria API](https://www.sefaria.org/) - the free living library of Jewish texts.