Theosis Sefaria Context MCP

A separate, provenance-first MCP service for high-value Sefaria context used in Bible study. It is part of the Theosis ecosystem but is intentionally separate from both the Bible database and the Midrash database.

Related repositories

• theosis-mcp — Bible texts, translations, Christian commentaries, lexicons, and theology; MCP port 8000.

• theosis-midrash — local Jewish Midrash corpus and source links; MCP port 8001.

• theosis-sefaria-context — this repository; selected Targumim, Mishnah, historical context, commentary lookup, lexicons, and Sefaria cache; MCP port 8002.

Related MCP server: Sefaria Jewish Library MCP Server

Current live deployment

• Database: PostgreSQL sefaria_context on CT125

• MCP endpoint: http://192.168.1.130:8002/mcp

• Health: http://192.168.1.130:8002/health

• Service: sefaria-context.service

• Service account: sefaria_context

• Encoding: UTF-8

• Schema migration: 002

• Snapshot: 43 works, 54 editions, 28,689 segments, 54 import manifests

Counts are operational snapshots; use get_context_corpus_summary or /health for current values.

What is local

The local Context tier currently contains:

• Targum Onkelos on the Torah

• Targum Jonathan on the Torah and selected Prophets

• Selected Mishnah: Berakhot, Pesachim, Yoma, Sanhedrin, and Pirkei Avot

• Approved Public Domain Josephus and Philo editions where exact Sefaria metadata matched

The service also provides on-demand, licence-filtered cache lookup for long-tail Sefaria material such as Jastrow, Rashi, and Ibn Ezra. It does not attempt to mirror the whole Sefaria library.

MCP tools

Every result identifies work, reference, edition, language, licence, source URL, retrieval/import time, and SHA-256 hash where available.

Requirements

• PostgreSQL 16+

• UTF-8 database

• Python 3.11+

• asyncpg, psycopg2-binary, MCP Python SDK

• pg_trgm PostgreSQL extension

• Network access to Sefaria API/export sources

Use requirements.lock for deployment and requirements-dev.lock for development/testing.

Fresh installation

sudo -u postgres psql <<'SQL'
CREATE ROLE sefaria_context LOGIN;
CREATE DATABASE sefaria_context OWNER sefaria_context ENCODING 'UTF8' TEMPLATE template0;
SQL
sudo -u postgres psql -d sefaria_context -f schema.sql

python3 -m venv .venv
. .venv/bin/activate
python -m pip install -r requirements.lock
export SEFARIA_CONTEXT_DATABASE_URL='postgresql://sefaria_context@/sefaria_context?host=/var/run/postgresql'

# Migrations require database-admin privileges for DDL.
sudo -u postgres env SEFARIA_CONTEXT_DATABASE_URL=postgresql:///sefaria_context?host=/var/run/postgresql python scripts/migrate.py --status
sudo -u postgres env SEFARIA_CONTEXT_DATABASE_URL=postgresql:///sefaria_context?host=/var/run/postgresql python scripts/migrate.py

Import workflow

The importer queries Sefaria metadata before downloading, rejects unapproved licences, hashes payloads, validates reference uniqueness, and records exact source URLs.

python scripts/sefaria_import.py --onkelos
python scripts/sefaria_import.py --jonathan
python scripts/sefaria_import.py --jonathan-prophets
python scripts/sefaria_import.py --mishnah
python scripts/sefaria_import.py --josephus
python scripts/sefaria_import.py --philo

Approved editions are selected by exact Sefaria API metadata. Unknown, CC-BY-SA, and CC-BY-NC editions are not silently imported into the default local corpus.

Deployment

Use deploy/sefaria-context.service as the systemd template. It runs as the dedicated sefaria_context user, uses systemd sandboxing, and binds to the configured LAN address.

sudo cp deploy/sefaria-context.service /etc/systemd/system/sefaria-context.service
sudo systemctl daemon-reload
sudo systemctl enable --now sefaria-context.service
curl http://127.0.0.1:8002/health

The endpoint has no application authentication. It is intended for a secured home LAN and should use a firewall or authenticated reverse proxy if the network threat model changes.

Hermes Desktop and other clients

Enable theosis_sefaria_context in the dedicated Hermes theosis_ai profile, alongside theosis and theosis_midrash. Start a new profile session after configuration changes.

For another MCP client, add:

http://<host>:8002/mcp

On-demand cache

lookup_sefaria_text retrieves exact Sefaria references outside the local corpus and caches only requested passages. Cache records include edition, licence, source URL, retrieval time, expiry, and SHA-256 hash. Only Public Domain, CC0, and CC-BY editions are cached. Public Domain entries may remain fresh for up to 365 days; CC0/CC-BY entries default to 90 days.

The cache is the preferred path for rare Jastrow, Rashi, Ibn Ezra, Josephus, Philo, and long-tail Sefaria queries. It avoids mirroring the entire library and keeps retrieval bounded.

Documentation

• Architecture — local tier, on-demand cache, source roles, and data flow.

• Live inventory — deployment and corpus snapshot.

• schema.sql — UTF-8 baseline schema.

Schema and migrations

• schema.sql — UTF-8 baseline schema.

• migrations/ — numbered cache/schema migrations.

• scripts/migrate.py — ordered, checksum-tracked migration runner.

The works.role field distinguishes primary texts, rabbinic context, historical context, and other source roles. cache_entries stores remote passages separately from the local corpus.

Licensing and source policy

Sefaria licensing applies to each edition and language independently. The importer records exact licence metadata and rejects unapproved editions. The repository contains code and import definitions, not a bundled database dump or downloaded source corpus. Check Sefaria’s licence guidance before redistributing any cached or imported text.

Development and verification

.venv/bin/pytest -q
.venv/bin/python -m compileall -q scripts tests

GitHub Actions runs tests and compile checks on Python 3.11 and 3.13.