📖 Multilingual Holy Bible MCP Server v2.0

A high-performance, 100% offline, zero-latency Model Context Protocol (MCP) Server and CLI Database Manager that connects any LLM (Claude 3.7, GPT-4o, Gemini 2.0, DeepSeek-R1, Llama 3.3, Qwen 2.5) to 11,907,047 Biblical verses across 1,081 translations in 800+ languages.

Equipped with the complete MCP Protocol Triad (Tools, Resources, Prompts), dual transport (Stdio + SSE), 100% SQLite-driven architecture (Multi-connection Pool, WAL Mode), Hebrew/Greek Robinson morphology, 344k+ TSK cross-reference graph, Trench's synonyms, and 15-translation parallel corpus diff engine.

📑 Table of Contents

• 🏗️ System Architecture & Data Flow

• ✨ Key Technical Features

• 🌐 Supported Languages & Database Specifications

• 💻 Cross-Platform & Architecture Support

• 🖥️ CLI Database Manager

• 🚀 Quick Start — IDE & Client Configurations

  • 1. Trae IDE

  • 2. Cursor IDE

  • 3. Claude Desktop

  • 4. Claude Code CLI

  • 5. Windsurf / Cline / Roo-Code

  • 6. Remote SSE Mode (Open-WebUI / Ollama / Docker)

• 🛠️ Complete MCP Tools Catalog (28 Tools)

• 📜 MCP Resources & RFC 6570 Templates

• 💬 MCP Prompts Repository (6 Calibrated Workflows)

• ⚙️ Environment Variables & Tuning

• 🧠 Adaptive Model Budgeting & CoT Protocol

• 🔒 Enterprise Security & Reliability

• 🧪 Automated Testing & CI

• 💻 Local Monorepo Setup & Build

• 📄 License

Related MCP server: Aquifer MCP

🏗️ System Architecture & Data Flow

flowchart TD
    subgraph Clients["💻 MCP Clients & AI Hosts"]
        Claude["Claude Desktop / Claude Code"]
        Cursor["Cursor IDE"]
        Trae["Trae IDE"]
        Windsurf["Windsurf / Cline / Roo"]
        RemoteClient["Remote HTTP/SSE Clients"]
        CLI["Holy Bible CLI Manager"]
    end

    subgraph Transport["⚡ Transport Layer"]
        Stdio["StdioServerTransport (JSON-RPC 2.0)"]
        SSE["SseSessionManager (Heartbeat 15s)"]
        Health["HttpHealthServer (Rate-Limited, Port 3001)"]
        Prometheus["/metrics (Prometheus 0.0.4)"]
    end

    subgraph ProtocolTriad["📜 MCP Protocol Triad (Protocol 2025-03-26)"]
        Tools["28 Tools (Zod Validated, O(1) Dispatcher)"]
        Resources["4 Resource Templates (Subscriptions & Singleflight)"]
        Prompts["6 Context-Calibrated Prompts"]
    end

    subgraph CoreEngines["🧠 Core Intelligent Engines"]
        Search["Hybrid Search (FTS5 BM25 + Ukrainian Morphology + RRF)"]
        Morph["Morphology Engine (Greek Robinson + Hebrew WLC + Aramaic)"]
        Graph["Theological Graphology (344k+ TSK Crossrefs Graph)"]
        DiffEngine["Myers LCS Word-by-Word Translation Diff"]
        Budget["Dynamic Token Budget (40/20/20/20 & CoT Protocol)"]
        Workers["Piscina Worker Pool (Multithreaded SHA-256 & Verification)"]
    end

    subgraph DataLayer["🗄️ Storage & Cache Layer (Zero-Latency SQLite)"]
        MainDB[("Main SQLite DB (11.9M Verses, WAL Mode, 30GB MMAP)")]
        DirectivesDB[("Directives DB (13 Tables, Directives & Knowledge Store)")]
        LRUCache[("In-Memory LRU (5,000 slots) & Prepared Stmt Cache")]
        MiniSearchFallback[("MiniSearch In-Memory Fallback (<1.5ms)")]
    end

    Claude --> Stdio
    Cursor --> Stdio
    Trae --> Stdio
    Windsurf --> Stdio
    RemoteClient --> SSE
    CLI --> MainDB

    Stdio --> ProtocolTriad
    SSE --> ProtocolTriad
    Health --> SSE
    Health --> Prometheus

    ProtocolTriad --> CoreEngines
    CoreEngines --> DataLayer

✨ Key Technical Features

1. Complete Protocol Triad with Modern Tool Annotations: Full implementation of MCP Tools (with { readOnlyHint: true, idempotentHint: true } annotations), Resources (with active subscriptions & list_changed / updated notifications), and System Prompts.

2. Zero-Latency SQLite Architecture:

   • High-concurrency Multi-connection Pool (better-sqlite3) in WAL Mode.

   • Zero-Copy Memory-Mapped I/O: PRAGMA mmap_size = 2147483648 (2 GB) for instant page reads directly from OS memory.

   • Multi-threaded Execution: PRAGMA threads = 4 and PRAGMA synchronous = NORMAL.

   • SARGable B-Tree Seek Indexing: Sub-millisecond verse lookups (<0.5ms) without table scans.

   • Bounded 64 MB LRU Query Cache: lru-cache with byte-aware tracking, 2,000 entries max, and 10-minute TTL (eliminates RAM leaks).

   • Dedicated data/directives.sqlite database loaded at boot in <5ms.

   • Hot-mounting detection: detects newly downloaded databases in 2.5s with live MCP notification broadcasts.

3. Piscina Multithreading Worker Pool: CPU-intensive operations (multithreaded SHA-256 chunk hashing, integrity inspection, graph analysis) run on lazy on-demand worker threads (minThreads: 0), saving ~80 MB RAM at idle.

4. Scholarly Linguistic Engines:

   • Greek Robinson Parser: Decodes tense, voice, mood, case, number, and gender with dedicated Greek LRU cache.

   • Hebrew & Aramaic WLC Parser: BDB definitions, Strong's Concordance canonical lemmas (CANONICAL_STRONGS_OFFLINE), and Trench's Synonyms distinctions.

   • Myers LCS Word Diff Engine: Token-level alignment comparing translation philosophies (Formal vs Dynamic Equivalence).

5. Hybrid Search with RRF:

   • SQLite FTS5 with BM25 ranking.

   • Ukrainian morphological stemmer with inverted O(1) irregular maps.

   • Reciprocal Rank Fusion (RRF) combining lexical, topical, and theological context.

   • Instant in-memory MiniSearch fallback ($<1.5$ ms).

6. Enterprise Security & DoS Protection:

   • 4 MB Request Payload Limit: Strict body buffering on /messages and /sse with 413 Payload Too Large.

   • Bounded Sliding-Window Rate Limiter: 120 req/min capped at 10,000 IPs with automatic purge.

   • Constant-Time Authentication: crypto.timingSafeEqual prevents timing side-channel attacks on MCP_AUTH_TOKEN.

   • Path Traversal & SSRF Guards: delete-db and verify-db path normalization restricted to bible_database.sqlite*; custom mirrors block loopback and private RFC 1918 subnets.

   • 30-Second Reconnection Grace Period: Transient SSE disconnects do not kill the session, eliminating premature 404s.

   • Enterprise security headers: X-Content-Type-Options: nosniff, X-Frame-Options: DENY, Strict-Transport-Security.

   • 100% Parameterized SQL queries (zero SQL injection surface).

7. Adaptive Context & CoT Budgeting:

   • Auto-calibrates prompt complexity, output word budgets, and Chain-of-Thought thinking budgets for 1B, 3B, 8B, 70B+, and frontier models (Claude 3.7, DeepSeek-R1, GPT-4o, Gemini 2.0).

🌐 Supported Languages & Database Specifications

The offline SQLite database contains canonical biblical corpora across 800+ languages with full OSIS book mapping:

📊 Database Volume Specifications:

• Total Canonical Verses: 11,907,047 verses

• Total Translations: 1,081 translations

• Cross-Reference Edges: 344,000+ Treasury of Scripture Knowledge (TSK) links

• Strong's Dictionary Entries: 8,674 Hebrew and Greek lexical roots with definitions

• Storage Footprint: ~5.88 GB (Single compact SQLite file with FTS5 and WAL mode)

💻 Cross-Platform & Architecture Support

Holy Bible MCP 2.0 is built with pure standard Node.js APIs and pre-compiled native SQLite binaries. It runs seamlessly with 0 configuration across:

• Operating Systems:

  • 🍏 macOS (macOS 12+ Monterey, Ventura, Sonoma, Sequoia)

  • 🐧 Linux (Ubuntu, Debian, Fedora, Arch, Alpine, RHEL)

  • 🪟 Windows (Windows 10, 11, Server via PowerShell / CMD / WSL2)

• CPU Architectures:

  • ⚡ ARM64 / AArch64 (Apple Silicon M1/M2/M3/M4, AWS Graviton, Raspberry Pi 4/5)

  • ⚡ x86_64 / AMD64 (Intel Core / Xeon, AMD Ryzen / EPYC)

Global Database Path Resolution:

1. macOS / Linux: /Users/<user>/.bible-mcp/bible_database.sqlite (or /home/<user>/.bible-mcp/bible_database.sqlite)

2. Windows: C:\Users\<user>\.bible-mcp\bible_database.sqlite (via %USERPROFILE%)

3. Custom Env: Set BIBLE_DB_PATH=/path/to/bible_database.sqlite to override globally.

💡 Hot-Mounting Support: If your IDE is already running when you execute download-db, the server automatically detects the new database on disk within 2.5s and hot-mounts it without restarting the IDE.

🖥️ CLI Database Manager

Manage the offline 5.88 GB SQLite Bible database directly from your terminal across any OS. The database is stored globally in ~/.bible-mcp/ and shared across all your IDEs (Trae, Cursor, Claude Desktop, Claude Code) with zero duplicate storage.

CLI Options & Flags:

# Force fresh download or overwrite existing corrupted files
npx @grizlizora/holy-bible-mcp download-db --force

# Perform deep multithreaded SHA-256 validation via Piscina Worker Pool
npx @grizlizora/holy-bible-mcp verify-db --checksum

# Specify a custom target directory
npx @grizlizora/holy-bible-mcp download-db --dir /Volumes/ExternalSSD/bible-data

# Delete database without interactive confirmation (CI/CD / automated scripts)
npx @grizlizora/holy-bible-mcp delete-db --yes

🚀 Quick Start — IDE & Client Configurations

1. Trae IDE

Add to .trae/trae.mcp.json or Global Settings:

{
  "mcpServers": {
    "holy-bible-mcp": {
      "command": "npx",
      "args": ["-y", "@grizlizora/holy-bible-mcp"],
      "env": {
        "MODES_CONTROL": "on",
        "WARMTH_CONTROL": "on",
        "SHOW_METRICS": "on",
        "DEFAULT_MODE": "auto",
        "DEFAULT_WARMTH": "80"
      },
      "autoApprove": [
        "ask_holy_bible",
        "build_biblical_context",
        "search_keyword",
        "search_scripture_hybrid",
        "search_semantic",
        "search_topic",
        "find_scriptures_by_life_situation",
        "get_verse",
        "get_chapter_context",
        "get_parallel_verses",
        "compare_translations_diff",
        "get_translation_metadata",
        "get_interlinear_verse",
        "get_strongs_definition",
        "get_strongs_etymology",
        "analyze_greek_hebrew_word",
        "get_commentary",
        "get_cross_references",
        "find_thematic_scripture_chain",
        "get_prophecy_fulfillment_pairs",
        "set_relevance_sensitivity",
        "set_response_mode",
        "set_show_metrics",
        "get_p2p_swarm_status",
        "get_mcp_capabilities",
        "get_model_recommendations",
        "extract_vector_context",
        "sanitize_scripture_markdown"
      ]
    }
  }
}

2. Cursor IDE

Add to .cursor/mcp.json:

{
  "mcpServers": {
    "holy-bible-mcp": {
      "command": "npx",
      "args": ["-y", "@grizlizora/holy-bible-mcp"],
      "env": {
        "MODES_CONTROL": "on",
        "WARMTH_CONTROL": "on",
        "SHOW_METRICS": "on",
        "DEFAULT_MODE": "auto",
        "DEFAULT_WARMTH": "80"
      }
    }
  }
}

3. Claude Desktop

Add to claude_desktop_config.json:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "holy-bible-mcp": {
      "command": "npx",
      "args": ["-y", "@grizlizora/holy-bible-mcp"],
      "env": {
        "MODES_CONTROL": "on",
        "WARMTH_CONTROL": "on",
        "SHOW_METRICS": "on",
        "DEFAULT_MODE": "auto",
        "DEFAULT_WARMTH": "80"
      }
    }
  }
}

4. Claude Code CLI

claude mcp add holy-bible-mcp -- npx -y @grizlizora/holy-bible-mcp

5. Windsurf / Cline / Roo-Code

Add to your extension MCP settings:

{
  "mcpServers": {
    "holy-bible-mcp": {
      "command": "node",
      "args": ["/path/to/holy-bible/build/index.js"]
    }
  }
}

6. Remote SSE & Cloud Deployment (Render / Open-WebUI / Ollama / Docker)

🌐 Live Cloud Service (Render)

Holy Bible MCP 2.0 is deployed and live in the cloud:

• Primary URL: https://holy-bible-vgaf.onrender.com

• Remote SSE Endpoint: https://holy-bible-vgaf.onrender.com/sse

• Streamable MCP Endpoint: https://holy-bible-vgaf.onrender.com/mcp

• Health / Status: https://holy-bible-vgaf.onrender.com/health

• Prometheus Metrics: https://holy-bible-vgaf.onrender.com/metrics

• Smithery Server Card: https://holy-bible-vgaf.onrender.com/server-card.json

💻 Self-Hosted Remote SSE Service

Run the server on your own server or Docker container:

# Start server in remote SSE mode on port 3001
MCP_TRANSPORT=sse MCP_PORT=3001 MCP_AUTH_TOKEN="your-secure-token" npx @grizlizora/holy-bible-mcp

Connect your remote client to http://localhost:3001/sse (or your Render URL) with Authorization header Bearer your-secure-token.

🛠️ Complete MCP Tools Catalog (28 Tools)

All tools use Zod schemas with runtime coercion, lenient argument normalization, and $O(1)$ dispatching.

🌟 1. Master & Context Tools

🔍 2. Search & Retrieval Tools

📖 3. Verse & Chapter Tools

🏛️ 4. Morphology & Original Languages Tools

⚓ 5. Theological & Graphology Tools

⚙️ 6. System & Adaptive Configuration Tools

📜 MCP Resources & RFC 6570 Templates

Access biblical content via standard RFC 6570 URIs with Singleflight de-duplication and LRU caching:

💬 MCP Prompts Repository (6 Calibrated Workflows)

⚙️ Environment Variables & Tuning

🧠 Adaptive Model Budgeting & CoT Protocol

The server dynamically profiles the connected AI model and adjusts prompts according to model capacity:

[Tier 1: <4B]    ──> Compact context (<4k), strict token budget, no CoT thinking block
[Tier 1.5: 4-8.5B] ──> Balanced context (<8k), medium detail, 500 chars CoT
[Tier 2: 8.5-35B]  ──> Comprehensive context (<16k), deep detail, 1,500 chars CoT
[Tier 3: 35B+]   ──> Maximum context (32k+), unrestricted deep exegesis, 6,000+ chars CoT

The 4-Part Canonical Trajectory:

When responding to worldview, ethical, and life questions, prompts enforce the canonical structure:

1. 📖 Сутність та якір (Core Essence & Anchor) — Primary scripture foundation.

2. ⚙️ Духовний механізм (Internal Mechanism) — How divine truth operates internally.

3. 🌿 Практичний вияв (Practical Manifestation) — Real-world daily application.

4. 🕊️ Вічний плід (Ultimate Fruit) — Eternal redemptive significance.

🔒 Enterprise Security & Reliability

• 4 MB Request Payload Limit: Strict body buffering on /messages and /sse with 413 Payload Too Large to prevent memory-exhaustion DoS attacks.

• Bounded Sliding-Window IP Rate Limiter: 120 requests/minute per client IP, strictly capped at 10,000 tracked IPs with periodic purge to prevent IP-spoofing memory inflation.

• Constant-Time Timing-Safe Token Validation: crypto.timingSafeEqual prevents timing side-channel attacks on secret MCP_AUTH_TOKEN keys.

• Path Traversal & SSRF Defense: CLI delete-db and verify-db commands strictly resolve and restrict target paths to bible_database.sqlite*. Custom download mirrors enforce HTTPS and block private/loopback IP spaces (127.0.0.0/8, 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, 169.254.0.0/16, ::1).

• 30-Second Reconnection Grace Period: Transient SSE disconnects do not instantly destroy client sessions, eliminating 404 Session Not Found errors during brief network pauses.

• Enterprise HTTP Headers: HSTS (max-age=31536000), X-Frame-Options: DENY, X-Content-Type-Options: nosniff, Referrer-Policy: no-referrer, and X-XSS-Protection.

• Process Exception Boundaries: Process-level handlers for unhandledRejection, uncaughtException, and graceful shutdown on SIGINT / SIGTERM.

• Online Fallback Cascade: Automatic graceful fallback to online scripture providers and CANONICAL_STRONGS_OFFLINE lexicon if the local 5.88 GB database is downloading or missing.

🧪 Automated Testing & CI

The project maintains an exhaustive suite of 101 tests across 22 test files executed via Vitest:

# Run the complete test suite
npm test

# Run tests in watch mode during development
npm run test:watch

# Run test coverage analysis
npm run test:coverage

Verified Test Categories:

• E2E IPC Subprocess: Real child process spawn executing JSON-RPC 2.0 over standard OS pipes.

• E2E HTTP/SSE Lifecycle: Real TCP network handshake, multi-session broadcast, and disconnect cleanup.

• Morphology Suite: Greek Robinson parser, Hebrew WLC, and Aramaic morphology decoding.

• Token Budget & Model Matrix: Reasoning adaptation for Claude 3.7, DeepSeek-R1, GPT-4o, and small models.

• Security Suite: Rate limiter sliding window, HTTP security headers, and input sanitization.

💻 Local Monorepo Setup & Build

# 1. Clone the repository
git clone https://github.com/grizlizora/holy-bible-mcp.git
cd holy-bible-mcp

# 2. Install dependencies & build TypeScript
npm install
npm run build

# 3. Run unit & E2E tests
npm test

# 4. (Optional) Download offline 5.88 GB database
npm run db:download

📄 License

Licensed under the MIT License. Free for open-source, commercial, and personal AI integration.