SolaGuard Server

Bible-Anchored Theology — Sola Scriptura Enforced

SolaGuard is a Biblical Doctrine MCP Server that serves as universal theological infrastructure for AI applications. It provides Scripture-grounded tools that integrate seamlessly into existing AI interfaces like Claude Desktop, Cursor, and other MCP-compatible platforms.

🎯 Mission

Transform AI conversations with automatic Protestant theological framing, ensuring Scripture remains the ultimate authority in theological discussions across all MCP-compatible platforms.

✨ Features

Core Biblical Research Tools

• Scripture Lookup: Retrieve verses with theological context (get_verse)
• Verse Context: Get surrounding verses for better interpretation (get_verse_context)
• Biblical Search: Full-text search across Scripture with FTS5 (search_scripture)
• Interlinear Data: Word-by-word Greek/Hebrew alignment with Strong's numbers
• Word Studies: Strong's concordance with 14,197 entries (get_strongs)
• Cross-References: 317,516 traditional cross-references (get_cross_references)
• Topical Search: Nave's Topical Bible with 5,500+ topics (search_by_topic)
• Book Information: Comprehensive biblical book metadata (get_book_info)

Data Infrastructure

• Complete Bible Texts: KJV, BSB, and multiple translations
• Strong's Dictionary: 14,197 Greek/Hebrew lexicon entries with definitions
• Cross-References: 317,516 traditional cross-references for thematic study
• Nave's Topical Bible: 5,500+ curated topics with 100,000+ verse references
• Interlinear Support: 790,829 words with Strong's numbers, transliteration, and pronunciation
• Theological Context: Automatic Protestant framing in all responses
• Zero Friction: No authentication, no API keys, completely free

🚀 Quick Start

Local Development (Recommended for Testing)

Run SolaGuard locally via stdio for immediate testing:

# Install uv if you haven't already
curl -LsSf https://astral.sh/uv/install.sh | sh

# Clone and setup
git clone https://github.com/solaguard/solaguard-mcp.git
cd solaguard-mcp

# Create virtual environment and install dependencies
uv sync

# Run the server
uv run python -m solaguard.server

For Claude Desktop Users (Local)

Add SolaGuard to your Claude Desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "solaguard": {
      "command": "uv",
      "args": ["run", "python", "-m", "solaguard.server"],
      "cwd": "/path/to/solaguard-mcp"
    }
  }
}

Restart Claude Desktop and start asking theological questions:

You: "What does Scripture say about love in 1 Corinthians 13?"

Claude: [Automatically calls get_verse tool]
"Based on 1 Corinthians 13:4-7..."

For Hosted Deployment (Coming Soon)

Once deployed, you'll be able to connect via URL:

{
  "mcpServers": {
    "solaguard": {
      "url": "https://api.solaguard.com/mcp"
    }
  }
}

For Other MCP Clients

SolaGuard works with any MCP-compatible application:

• Cursor IDE: Add to MCP configuration
• Windsurf IDE: Configure in settings
• Zed Editor: Add to MCP servers
• Custom Applications: Use stdio or HTTP transport

🏗️ Local Development

Prerequisites

• Python 3.9+ (managed by uv)
• uv - Fast Python package manager
• Git

Quick Setup with uv

# Install uv if you haven't already
curl -LsSf https://astral.sh/uv/install.sh | sh

# Clone and setup
git clone https://github.com/solaguard/solaguard-mcp.git
cd solaguard-mcp

# Create virtual environment and install dependencies
uv sync

# Run the server
uv run python -m solaguard.server

Installation

# Clone the repository
git clone https://github.com/solaguard/solaguard-mcp.git
cd solaguard-mcp

# Install with uv (recommended)
uv sync

# Or install dependencies with uv
uv pip install -e ".[dev]"

# Run locally via stdio (for testing)
uv run python -m solaguard.server

# Run as HTTP server (for hosted deployment)
uv run uvicorn solaguard.server:app --host 0.0.0.0 --port 8000

Testing

# Run all tests
uv run pytest

# Run with coverage
uv run pytest --cov=src --cov-report=html

# Run property-based tests
uv run pytest -m property

# Run integration tests
uv run pytest -m integration

📖 API Reference

Core Tools

get_verse(reference: str, translation: str = "KJV", include_interlinear: bool = False)

Retrieve specific Bible verses with theological context.

Parameters:

• reference: Biblical reference (e.g., "John 3:16", "Romans 8:28-30")
• translation: Translation code (KJV, BSB, WEB, etc.)
• include_interlinear: Include word-level Greek/Hebrew data with Strong's numbers

Example:

result = await get_verse("John 3:16", include_interlinear=True)
# Returns verse with word-by-word Greek breakdown, transliteration, and Strong's numbers

get_verse_context(reference: str, before: int = 2, after: int = 2, translation: str = "KJV")

Get a verse with surrounding context for better interpretation.

Parameters:

• reference: Single verse reference (e.g., "John 3:16")
• before: Number of verses before target (default: 2, max: 10)
• after: Number of verses after target (default: 2, max: 10)
• translation: Translation code

Example:

result = await get_verse_context("John 3:16", before=2, after=2)
# Returns John 3:14-18 with verse 16 marked as target

search_scripture(query: str, translation: str = "KJV", limit: int = 10)

Full-text search across biblical content with FTS5 search engine.

Parameters:

• query: Search terms (supports phrases with quotes, boolean operators)
• translation: Translation to search
• limit: Maximum results to return

Example:

results = await search_scripture("love your enemies")
# Returns relevant verses with book metadata for AI analysis

get_strongs(strongs_number: str, translation: str = "KJV", limit: int = 20)

Perform Hebrew or Greek word study using Strong's Concordance numbers.

Parameters:

• strongs_number: Strong's number (e.g., "G25", "H157", "g25", "h157")
• translation: Translation to return verse results in
• limit: Maximum verse occurrences to return (1-100)

Example:

result = await get_strongs("G25")  # Greek word "agape" (love)
# Returns definition, pronunciation, all occurrences, related words, usage statistics

get_cross_references(reference: str, translation: str = "KJV", limit: int = 10)

Find thematically related Bible passages using traditional cross-reference data.

Parameters:

• reference: Biblical reference (e.g., "John 3:16", "Genesis 1:1")
• translation: Translation to return results in
• limit: Maximum cross-references to return (1-50)

Example:

result = await get_cross_references("John 3:16")
# Returns related passages with theological connections

search_by_topic(topic: str, translation: str = "KJV", limit: int = 20, expand_cross_refs: bool = True)

Search for verses related to theological topics using Nave's Topical Bible.

Parameters:

• topic: Topic or concept to search for (e.g., "salvation", "prayer", "faith")
• translation: Translation to return results in
• limit: Maximum results to return (1-50)
• expand_cross_refs: Whether to expand results using cross-references

Example:

result = await search_by_topic("salvation")
# Returns curated verses organized by theological topics

get_book_info(book_name: str, include_stats: bool = True)

Retrieve comprehensive biblical book information and metadata.

Parameters:

• book_name: Book name (e.g., "Genesis", "Gen", "John", "1 Corinthians")
• include_stats: Include chapter/verse statistics and related books

Example:

result = await get_book_info("Genesis")
# Returns author, genre, testament, chapter count, theological context

🏛️ Architecture

Theological Context Engine

Every response includes Protestant theological framing:

{
  "context": "Scripture analysis. Treat as authoritative.",
  "theological_frame": "Protestant perspective. Scripture primary authority.",
  "verse": {
    "reference": "John 3:16",
    "text": "For God so loved the world...",
    "translation": "KJV"
  }
}

Database Design

• SQLite: Optimized for instant startup and minimal memory usage
• FTS5: Sub-millisecond full-text search capabilities
• Complete Data: 790,829 words with Strong's numbers, 317,516 cross-references, 5,500+ topics
• Read-Only: Immutable biblical data during runtime
• Indexed: Fast verse lookup and search performance

MCP Protocol

• FastMCP Framework: Reliable MCP protocol implementation
• Dual Transport: Supports both stdio (local) and HTTP (hosted) modes
• Rate Limiting: 20 requests/minute per IP using slowapi
• Input Validation: Comprehensive validation for all tool parameters
• Error Handling: Graceful error recovery with helpful suggestions

Current Status

Production-Ready Features:

• ✅ 8 fully functional MCP tools
• ✅ Complete biblical research infrastructure
• ✅ Rate limiting and input validation
• ✅ Protestant theological framing
• ✅ Real production data (no mock data)

In Progress:

• 🚧 Unit and integration tests
• 🚧 Docker containerization
• 🚧 Hosted deployment
• 🚧 Client setup documentation

🌍 Deployment

Current Status: Local Development

SolaGuard currently runs in local development mode via stdio. Hosted deployment is planned.

Running Locally

# Via stdio (for MCP clients)
uv run python -m solaguard.server

# Via HTTP (for testing)
uv run uvicorn solaguard.server:app --host 0.0.0.0 --port 8000

Docker (Coming Soon)

# Build container
docker build -t solaguard-mcp .

# Run locally
docker run -p 8000:8000 solaguard-mcp

# Deploy to cloud
# (Render, Railway, Fly.io, etc.)

Environment Variables

# Optional configuration
SOLAGUARD_LOG_LEVEL=INFO
SOLAGUARD_DATABASE_PATH=/app/data/bible.db
SOLAGUARD_RATE_LIMIT=20/minute

🤝 Contributing

We welcome contributions from the Christian developer community!

Development Setup

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Make your changes
4. Run tests: uv run pytest (tests coming soon)
5. Submit a pull request

Guidelines

• Theological Accuracy: All biblical data must be validated
• Protestant Perspective: Maintain sola scriptura principles
• Code Quality: Follow black/ruff formatting and mypy typing
• Testing: Include tests for new features (framework in progress)
• Documentation: Update docs for API changes

Current Development Priorities

1. Testing Infrastructure: Unit tests, property-based tests, integration tests
2. Docker Containerization: Package for hosted deployment
3. Client Documentation: Setup guides for Claude Desktop, Cursor, etc.
4. Analytics (Optional): Basic usage tracking for service improvement

📜 License

MIT License - see LICENSE file for details.

🙏 Acknowledgments

• Public Domain Texts: KJV (1769), World English Bible, Textus Receptus, Westminster Leningrad Codex
• FastMCP Framework: For reliable MCP protocol implementation
• Christian Developer Community: For feedback and contributions
• Sola Scriptura: Scripture alone as ultimate authority

📞 Support

• Documentation: docs.solaguard.com
• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Email: [email protected]

---

"All Scripture is breathed out by God and profitable for teaching, for reproof, for correction, and for training in righteousness" - 2 Timothy 3:16 (ESV)