mcp_asvb by codemonkeying - MCP Server

📖 ASVB Bible MCP Server

American Standard Version Bible Server for Model Context Protocol

A comprehensive, high-performance MCP server that provides seamless access to the complete American Standard Version Bible through standardized tools for verse retrieval, chapter access, and advanced search capabilities.

🌟 Features

📚 Complete Bible Access

66 Books: Full Old and New Testament coverage
31,000+ Verses: Complete American Standard Version text
Fast Retrieval: Optimized database with sub-10ms verse lookup
Flexible References: Support for book names, abbreviations, and ranges

🔍 Advanced Search

Full-Text Search: Powered by SQLite FTS5 with Porter stemming algorithm
Intelligent Word Matching: Automatically finds word variations and related terms
Boolean Queries: Support for AND, OR, NOT operators with complex expressions
Phrase Matching: Exact phrase searches with quotes
Wildcard Search: Use asterisk (*) for partial word matching
Testament Filtering: Search within Old Testament, New Testament, or both
Relevance Scoring: Results ranked by match quality and relevance

🛠️ MCP Tools

get_verse - Retrieve specific verses
get_chapter - Get complete chapters
get_verse_range - Retrieve verse ranges
search_bible - Full-text search
search_by_topic - Topic-based search
get_book_info - Book information and statistics
list_books - List all Bible books
get_random_verse - Random verse selection
health_check - Server health monitoring
get_readme - Documentation access

⚡ Performance & Reliability

High Performance: 1000+ requests/second capability
Connection Pooling: Efficient database connection management
Caching: LRU cache for frequently accessed content
Error Handling: Comprehensive error handling with detailed logging
MCP Compliance: Fully compliant with MCP server standards

🚀 Quick Start

Prerequisites

Python 3.10 or higher
MCP Bridge project (parent directory)
50MB available disk space

Installation

Navigate to the ASVB directory:
```
cd servers/asvb
```
Run the setup script:
```
./setup_asvb_server.sh
```
Discover and register the server:
```
cd ../..
./discovery.sh
```
Restart MCP Bridge services:
```
./restart_services.sh
```

Test the installation:

curl -H "Authorization: Bearer your-key-here" \
     http://localhost:8000/asvb/health_check

🎉 That's it! Your ASVB Bible server is now accessible via HTTP and SSE.

🔧 Available Tools

📖 `get_verse`

Retrieve a specific Bible verse by book, chapter, and verse number.

Parameters:

book (str): Book name or abbreviation (e.g., "Genesis", "Gen")
chapter (int): Chapter number
verse (int): Verse number

Example:

curl -X POST \
  -H "Authorization: Bearer your-key-here" \
  -H "Content-Type: application/json" \
  -d '{"book": "John", "chapter": 3, "verse": 16}' \
  http://localhost:8000/asvb/get_verse

Response:

{
  "success": true,
  "data": {
    "reference": "John 3:16",
    "text": "For God so loved the world, that he gave his only begotten Son...",
    "book": "John",
    "abbreviation": "John",
    "chapter": 3,
    "verse": 16,
    "testament": "New",
    "word_count": 26
  }
}

📄 `get_chapter`

Retrieve an entire chapter with all its verses.

Parameters:

book (str): Book name or abbreviation
chapter (int): Chapter number

Example:

curl -X POST \
  -H "Authorization: Bearer your-key-here" \
  -H "Content-Type: application/json" \
  -d '{"book": "Psalms", "chapter": 23}' \
  http://localhost:8000/asvb/get_chapter

🔍 `search_bible`

Perform full-text search across the Bible.

Parameters:

query (str): Search terms or phrase
limit (int, optional): Maximum results (default: 10, max: 50)
testament (str, optional): "Old", "New", or null for both
book (str, optional): Specific book to search within

Example:

curl -X POST \
  -H "Authorization: Bearer your-key-here" \
  -H "Content-Type: application/json" \
  -d '{"query": "love your neighbor", "limit": 5}' \
  http://localhost:8000/asvb/search_bible

Advanced Search Examples:

# Exact phrase search
{"query": "\"love your neighbor\""}

# Boolean search with multiple terms
{"query": "love AND neighbor AND heart"}

# Find word variations with wildcards
{"query": "faith*"}  # Finds: faith, faithful, faithfulness

# Complex Boolean expressions
{"query": "wisdom OR understanding OR knowledge"}

# Exclude terms with NOT operator
{"query": "peace NOT war"}

# Testament-specific search
{"query": "salvation", "testament": "New"}

# Book-specific search
{"query": "faith", "book": "Hebrews"}

# Combine filters for precise results
{"query": "prayer*", "testament": "Old", "limit": 20}

🧠 Intelligent Search Features

Porter Stemming Algorithm: The search engine automatically finds related word forms and variations:

Searching for "love" also finds: loved, loves (tested: 383 results)
Searching for "pray" also finds: prayed, praying (tested: 379 results)
Searching for "faith"* finds: faith, faithful, faithfulness (tested: 347 results)

Bidirectional Stemming (Important!): Porter stemming works in both directions - any word form finds all related forms:

"love" → 383 results (finds: love, loved, loving, loves)
"loved" → 383 results (finds: love, loved, loving, loves)
"loving" → 383 results (finds: love, loved, loving, loves)
All searches return identical result sets because they map to the same root stem

Verified Search Capabilities:

Root Word Detection: Porter stemming finds word variations automatically
Bidirectional Matching: Search any word form to find all related forms
Wildcard Search: Use asterisk () for partial matching (e.g., "faith")
Exact Word Matching: Each term searches independently (shepherd ≠ pastor)
Boolean Operators: AND, OR, NOT for complex queries

Real Search Examples (Tested):

# Basic stemming - finds word variations
{"query": "love"}     # Returns: love, loved, loves (383 results)
{"query": "pray"}     # Returns: pray, prayed, praying (379 results)

# Wildcard search - finds partial matches
{"query": "faith*"}   # Returns: faith, faithful, faithfulness (347 results)

# Boolean operators - verified working
{"query": "love AND neighbor"}        # Both terms required (13 results)
{"query": "wisdom OR understanding"}  # Either term matches (404 results)
{"query": "peace NOT war"}           # Excludes war from peace (406 results)
{"query": "faith AND hope AND love"} # All three required (3 results)

# Specific terms - separate searches
{"query": "shepherd"} # Returns: shepherd, shepherds (94 results)
{"query": "pastor"}   # Returns: pastors (1 result - separate from shepherd)

📊 `get_book_info`

Get detailed information about a specific Bible book.

Example:

curl -X POST \
  -H "Authorization: Bearer your-key-here" \
  -H "Content-Type: application/json" \
  -d '{"book": "Genesis"}' \
  http://localhost:8000/asvb/get_book_info

📚 `list_books`

List all books in the Bible with optional filtering.

Example:

curl -X POST \
  -H "Authorization: Bearer your-key-here" \
  -H "Content-Type: application/json" \
  -d '{"testament": "New", "include_stats": true}' \
  http://localhost:8000/asvb/list_books

🎲 `get_random_verse`

Get a random Bible verse with optional filtering.

Example:

curl -X POST \
  -H "Authorization: Bearer your-key-here" \
  -H "Content-Type: application/json" \
  -d '{"testament": "New"}' \
  http://localhost:8000/asvb/get_random_verse

🔌 Integration Examples

n8n Workflow

{
  "nodes": [
    {
      "name": "Get Bible Verse",
      "type": "n8n-nodes-base.httpRequest",
      "parameters": {
        "url": "http://localhost:8000/asvb/get_verse",
        "method": "POST",
        "headers": {
          "Authorization": "Bearer your-key-here"
        },
        "body": {
          "book": "Proverbs",
          "chapter": 3,
          "verse": 5
        }
      }
    }
  ]
}

Python Client

import requests

class ASVBClient:
    def __init__(self, base_url="http://localhost:8000", api_key="your-key-here"):
        self.base_url = base_url
        self.headers = {"Authorization": f"Bearer {api_key}"}
    
    def get_verse(self, book, chapter, verse):
        response = requests.post(
            f"{self.base_url}/asvb/get_verse",
            headers=self.headers,
            json={"book": book, "chapter": chapter, "verse": verse}
        )
        return response.json()
    
    def search_bible(self, query, limit=10):
        response = requests.post(
            f"{self.base_url}/asvb/search_bible",
            headers=self.headers,
            json={"query": query, "limit": limit}
        )
        return response.json()

# Usage
client = ASVBClient()
verse = client.get_verse("John", 3, 16)
print(verse["data"]["text"])

results = client.search_bible("faith hope love")
for result in results["data"]["results"]:
    print(f"{result['reference']}: {result['text']}")

JavaScript/Node.js Client

class ASVBClient {
    constructor(baseUrl = 'http://localhost:8000', apiKey = 'your-key-here') {
        this.baseUrl = baseUrl;
        this.headers = { 'Authorization': `Bearer ${apiKey}` };
    }
    
    async getVerse(book, chapter, verse) {
        const response = await fetch(`${this.baseUrl}/asvb/get_verse`, {
            method: 'POST',
            headers: { ...this.headers, 'Content-Type': 'application/json' },
            body: JSON.stringify({ book, chapter, verse })
        });
        return response.json();
    }
    
    async searchBible(query, limit = 10) {
        const response = await fetch(`${this.baseUrl}/asvb/search_bible`, {
            method: 'POST',
            headers: { ...this.headers, 'Content-Type': 'application/json' },
            body: JSON.stringify({ query, limit })
        });
        return response.json();
    }
}

// Usage
const client = new ASVBClient();
const verse = await client.getVerse('Philippians', 4, 13);
console.log(verse.data.text);

⚙️ Configuration

Environment Variables

# Debug and logging
ASVB_DEBUG=0                    # Enable debug mode (0/1)
ASVB_LOG_LEVEL=INFO            # Log level (DEBUG/INFO/WARNING/ERROR)

# Database settings
ASVB_DATABASE_PATH=data/bible.db    # Database file path
ASVB_CACHE_SIZE=1000               # LRU cache size

# Performance settings
ASVB_MAX_SEARCH_RESULTS=50         # Maximum search results
ASVB_CONNECTION_POOL_SIZE=5        # Database connection pool size

Configuration File (`.env`)

# Copy example configuration
cp .env.example .env

# Edit configuration
nano .env

📊 Performance Characteristics

Response Times

Single Verse Lookup: < 10ms average
Chapter Retrieval: < 50ms average
Search Queries: < 100ms average (simple terms)
Complex Boolean Search: < 200ms average
Wildcard Search: < 150ms average
Book Information: < 5ms average

Search Performance

Index Size: ~31,000 searchable verses with full-text indexing
Porter Stemming: Real-time word variation matching
Relevance Ranking: Advanced scoring algorithm for result quality
Search Cache: LRU caching for frequently searched terms
Concurrent Search: Multiple simultaneous search queries supported

Throughput

Concurrent Requests: 100+ simultaneous users
Verses per Second: 1000+ requests/second
Search Queries: 50+ requests/second
Complex Searches: 25+ requests/second

Resource Usage

Memory: 30-50 MB typical usage (includes search index)
Database Size: ~10 MB (includes FTS5 search index)
Search Index: ~3 MB additional for full-text search
Startup Time: < 5 seconds (includes index loading)

🔍 Troubleshooting

Common Issues

Server Won't Start

# Check Python version
python3 --version  # Should be 3.10+

# Check virtual environment
source venv/bin/activate
which python  # Should point to venv

# Check dependencies
pip list | grep mcp

Database Issues

# Check database file
ls -la data/bible.db

# Rebuild database
rm data/bible.db
python data_import.py

# Test database
sqlite3 data/bible.db "SELECT COUNT(*) FROM books;"  # Should return 66

Search Not Working

# Check FTS5 support
sqlite3 data/bible.db "SELECT * FROM search_index LIMIT 1;"

# Rebuild search index
sqlite3 data/bible.db "DELETE FROM search_index; INSERT INTO search_index SELECT * FROM verses;"

Performance Issues

# Check database optimization
sqlite3 data/bible.db "PRAGMA optimize;"

# Monitor memory usage
ps aux | grep asvb

# Check logs
tail -f ../../logs/asvb_server.log

Debug Mode

Enable debug mode for detailed logging:

export ASVB_DEBUG=1
python server.py

🧪 Testing

Manual Testing

# Test basic functionality
curl -H "Authorization: Bearer key" http://localhost:8000/asvb/health_check

# Test verse retrieval
curl -X POST -H "Authorization: Bearer key" -H "Content-Type: application/json" \
     -d '{"book":"Genesis","chapter":1,"verse":1}' \
     http://localhost:8000/asvb/get_verse

# Test search
curl -X POST -H "Authorization: Bearer key" -H "Content-Type: application/json" \
     -d '{"query":"love","limit":3}' \
     http://localhost:8000/asvb/search_bible

Automated Testing

# Run unit tests
cd servers/asvb
python -m pytest tests/

# Run integration tests
../../test_http_bridge.sh
../../test_sse_bridge.sh

📈 Monitoring & Health

Health Check Endpoint

The server provides comprehensive health information:

curl -H "Authorization: Bearer your-key-here" \
     http://localhost:8000/asvb/health_check

Response includes:

Server status and uptime
Database statistics (books, verses, size)
Performance metrics (response times, cache hit rates)
System information (memory usage, log paths)

Logging

All server activity is logged to:

Development: logs/asvb_server.log
Production: ../../logs/asvb_server.log

Log levels: DEBUG, INFO, WARNING, ERROR, CRITICAL

🔒 Security

Data Security

Read-Only Access: Database is accessed in read-only mode
No Sensitive Data: Bible text is public domain
Input Validation: All inputs are validated and sanitized
SQL Injection Prevention: Parameterized queries only

Access Control

Bearer Token Authentication: Required for all API access
Rate Limiting: Handled by MCP Bridge
Error Sanitization: No internal details exposed in errors

📚 Bible Content Information

Translation

Version: American Standard Version (1901)
Copyright: Public Domain
Language: English
Text Source: Standard ASV text file

Statistics

Total Books: 66 (39 Old Testament, 27 New Testament)
Total Chapters: ~1,189
Total Verses: ~31,000
Total Words: ~783,000

Book Coverage

Old Testament: Genesis through Malachi New Testament: Matthew through Revelation

🤝 Contributing

We welcome contributions to improve the ASVB Bible MCP Server!

Development Setup

# Clone and setup
git clone <repository>
cd servers/asvb
./setup_asvb_server.sh

# Install development dependencies
source venv/bin/activate
pip install pytest black flake8 mypy

# Run tests
python -m pytest tests/

Code Standards

Type Hints: All functions must have type hints
Docstrings: Comprehensive documentation required
Testing: Unit tests for all new features
Formatting: Use Black for code formatting
Linting: Pass Flake8 linting

📄 License

The ASVB Bible MCP Server code is released under the MIT License.

The American Standard Version Bible text is in the Public Domain and free for any use.

🙏 Acknowledgments

American Standard Version: Public domain Bible translation
MCP Protocol: Model Context Protocol specification
FastMCP: Python MCP server framework
SQLite: Embedded database engine
MCP Bridge: Universal MCP server bridge

📖 ASVB Bible MCP Server - Bringing Scripture to the Digital Age

Made with ❤️ for the MCP community

codemonkeying/mcp_asvb

📖 ASVB Bible MCP Server

🌟 Features

📚 Complete Bible Access

🔍 Advanced Search

🛠️ MCP Tools

⚡ Performance & Reliability

🚀 Quick Start

Prerequisites

Installation

🔧 Available Tools

📖 get_verse

📄 get_chapter

🔍 search_bible

🧠 Intelligent Search Features

📊 get_book_info

📚 list_books

🎲 get_random_verse

🔌 Integration Examples

n8n Workflow

Python Client

JavaScript/Node.js Client

⚙️ Configuration

Environment Variables

Configuration File (.env)

📊 Performance Characteristics

Response Times

Search Performance

Throughput

Resource Usage

🔍 Troubleshooting

Common Issues

Server Won't Start

Database Issues

Search Not Working

Performance Issues

Debug Mode

🧪 Testing

Manual Testing

Automated Testing

📈 Monitoring & Health

Health Check Endpoint

Logging

🔒 Security

Data Security

Access Control

📚 Bible Content Information

Translation

Statistics

Book Coverage

🤝 Contributing

Development Setup

Code Standards

📄 License

🙏 Acknowledgments

📖 `get_verse`

📄 `get_chapter`

🔍 `search_bible`

📊 `get_book_info`

📚 `list_books`

🎲 `get_random_verse`

Configuration File (`.env`)