# Bible MCP Server

A Model Context Protocol (MCP) server that provides Bible passage retrieval functionality using the `mcp-weather` core infrastructure.

This server enables AI assistants to access Bible passages from various translations, with support for multiple deployment modes:

- **`--mode stdio`** (default): MCP protocol over stdin/stdout for direct AI assistant integration
- **`--mode mcp`**: MCP protocol over HTTP for networked AI assistant access  
- **`--mode rest`**: Both REST API and MCP protocol over HTTP for maximum flexibility

## Features

The Bible MCP Server provides:

### MCP Tools (for AI assistants)
- `get_passage(passage, version)` - Retrieve Bible passages. Supports multiple passages separated by semicolons (e.g., "John 3:16; Romans 8:28").

### REST API Endpoints
- `GET /health` - Health check
- `GET /info` - Service information
- `POST /passage` - Get Bible passage
- `GET /docs` - OpenAPI documentation (Swagger UI)

### Supported Bible Versions
- ESV (English Standard Version)
- NIV (New International Version)
- KJV (King James Version)
- NASB (New American Standard Bible)
- NKJV (New King James Version)
- NLT (New Living Translation)
- AMP (Amplified Bible)
- MSG (The Message)

## Installation

### Prerequisites
- Python 3.10+
- `uv` package manager

#### Installing uv

**On Linux/macOS:**
```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```

**On Windows:**
```powershell
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
```

Alternatively, you can install uv using pip:
```bash
pip install uv
```

After installation, restart your terminal or run `source ~/.bashrc` (Linux/macOS) or restart your command prompt (Windows).

### Step 1: Install Dependencies

```bash
# From this directory
cd mcp-bible

# Install dependencies
uv sync
```

### Step 2: Configure Environment

```bash
# Copy example configuration
cp .env.example .env

# Edit .env with your settings
vi .env
```

## Usage

The Bible MCP server supports three deployment modes via command-line arguments:

### Mode 1: stdio (Default) - Direct AI Assistant Integration

```bash
# Default mode - MCP over stdin/stdout
uv run mcp-bible

# Explicitly specify stdio mode  
uv run mcp-bible --mode stdio
```

Perfect for direct integration with AI assistants like GitHub Copilot, Claude Desktop, etc.

### Mode 2: mcp - MCP Protocol over HTTP

```bash
# MCP-only server on HTTP (no REST API)
uv run mcp-bible --mode mcp --port 3000 --no-auth
```

Provides MCP protocol over HTTP at `http://localhost:3000/mcp` for networked AI assistant access.

### Mode 3: rest - Full HTTP Server (REST + MCP)

```bash
# Full server with both REST API and MCP protocol
uv run mcp-bible --mode rest --port 3000 --no-auth
```

The server will start at `http://localhost:3000` with:
- MCP endpoint: `http://localhost:3000/mcp`
- REST API: `http://localhost:3000/*`
- API docs: `http://localhost:3000/docs`
- Health check: `http://localhost:3000/health`

### Test the MCP Tools

You can test the MCP tools by connecting GitHub Copilot or using a test client:

```json
// .vscode/mcp.json
{
  "servers": {
    "bible": {
      "type": "http",
      "url": "http://localhost:3000/mcp"
    }
  }
}
```

Then ask Copilot:
- "Show me John 3:16"
- "What does Romans 8 say?"
- "Read Psalm 23 in NIV"

### Test the REST API

```bash
# Health check
curl http://localhost:3000/health

# Get service info
curl http://localhost:3000/info

# Get a Bible passage
curl -X POST "http://localhost:3000/passage" \
  -H "Content-Type: application/json" \
  -d '{
    "passage": "John 3:16",
    "version": "ESV"
  }'

# Get multiple passages
curl -X POST "http://localhost:3000/passage" \
  -H "Content-Type: application/json" \
  -d '{
    "passage": "John 3:16; Romans 8:28; Philippians 4:13",
    "version": "NIV"
  }'

# Get an entire chapter
curl -X POST "http://localhost:3000/passage" \
  -H "Content-Type: application/json" \
  -d '{
    "passage": "Mark 2",
    "version": "ESV"
  }'
```

### CLI Help and Options

```bash
# See all available options
uv run mcp-bible --help

# Usage examples:
uv run mcp-bible                         # stdio mode (default)
uv run mcp-bible --mode stdio            # stdio mode
uv run mcp-bible --mode mcp --port 4000  # MCP-only HTTP on port 4000
uv run mcp-bible --mode rest --port 4000 # REST+MCP HTTP on port 4000
uv run mcp-bible --mode rest --no-auth   # Disable authentication
```

### Environment Variables (Alternative to CLI)

You can also configure the server using environment variables:

```bash
# Alternative: Set environment variables
export MCP_TRANSPORT=http        # stdio or http
export MCP_ONLY=false           # true for MCP-only, false for REST+MCP
export MCP_HOST=0.0.0.0         # Host to bind to
export MCP_PORT=3000            # Port number
export AUTH_ENABLED=false       # Enable/disable authentication

# Then run without arguments
uv run mcp-bible
```

### Test All Modes

Run the comprehensive test suite:

```bash
uv run tests/test_modes.py
```

Or try the interactive curl examples:

```bash
./examples/curl_examples.sh
```

## Project Structure

```
mcp_bible/
├── __init__.py              # Package metadata
├── config.py                # Configuration management (extends mcp-weather core)
├── bible_service.py         # Business logic (Bible API client)
├── service.py               # MCP service wrapper (with automatic feature discovery)
├── server.py                # Server implementation (CLI mode support)
├── features/                # Feature modules (MODULAR PATTERN)
│   ├── __init__.py
│   └── get_passage/         # Get passage feature
│       ├── __init__.py
│       ├── instructions.md  # 📝 Comprehensive documentation (core.utils)
│       ├── models.py        # Feature-specific models
│       ├── tool.py          # MCP tool definition (uses @inject_docstring)
│       └── routes.py        # REST API endpoints (uses load_instruction)
├── shared/                  # Shared models and utilities
│   ├── __init__.py
│   └── models.py            # Base models, error types
├── tests/                   # Test suite
│   └── test_modes.py        # Mode support testing
└── examples/                # Usage examples
    └── curl_examples.sh     # Interactive REST API examples
```

### Core.utils Integration

This project uses the **core.utils pattern** from mcp-weather for dynamic documentation:

- **`instructions.md`**: Comprehensive feature documentation in markdown
- **`@inject_docstring`**: Dynamically injects markdown into MCP tool docstrings
- **`load_instruction`**: Loads markdown for REST API documentation
- **Single source of truth**: Same documentation for both MCP tools and REST endpoints

## How It Works

### Features Pattern (Automatic Discovery)

This server uses **automatic feature discovery** - just like `mcp-weather`!

**Add a new feature in 4 steps:**

1. **Create feature directory**: `features/my_feature/`
2. **Add instructions.md**: Comprehensive documentation in markdown
3. **Add tool.py**: With `register_tool(mcp, service)` function using `@inject_docstring`
4. **Add routes.py** (optional): With `create_router(service)` function using `load_instruction`

**Example feature structure:**

```python
# features/my_feature/tool.py
from core.utils import inject_docstring, load_instruction

@mcp.tool()
@inject_docstring(lambda: load_instruction("instructions.md", __file__))
async def my_tool(param: str) -> dict:
    """Documentation loaded from instructions.md"""
    return {"result": param}

# features/my_feature/routes.py  
from core.utils import load_instruction

@router.post("/endpoint", description=load_instruction("instructions.md", __file__))
async def endpoint():
    """Same documentation for REST API"""
    return {"data": "value"}
```

**That's it!** The service automatically:
- Discovers your feature
- Registers MCP tools from `tool.py` 
- Includes REST routes from `routes.py`
- Loads documentation from `instructions.md`

No manual registration needed!

### 1. Configuration Layer (config.py)

Extends core configuration classes with service-specific settings:

```python
from core.config import BaseServerConfig

class BibleAPIConfig(BaseModel):
    base_url: str
    supported_versions: List[str]

class AppConfig(BaseModel):
    server: ServerConfig
    bible_api: BibleAPIConfig
```

### 2. Business Logic Layer (bible_service.py)

Pure business logic, independent of MCP/REST:

```python
class BibleService:
    async def fetch_passage(self, passage: str, version: str) -> dict:
        # Bible passage retrieval logic here
        ...
```

### 3. MCP Service Wrapper (service.py)

Implements `BaseService` to expose business logic via MCP:

```python
from core.server import BaseService

class BibleMCPService(BaseService):
    def register_mcp_tools(self, mcp: FastMCP) -> None:
        # Automatic feature discovery and registration
```

### 4. Server Implementation (server.py)

Extends `BaseMCPServer` to create the complete server:

```python
from core.server import BaseMCPServer

class BibleMCPServer(BaseMCPServer):
    @property
    def service_title(self) -> str:
        return "Bible MCP Server"

    def create_router(self) -> APIRouter:
        # Add REST endpoints
        ...
```

## Key Benefits of Using mcp-weather Core

By using `mcp-weather` as a dependency, you get:

✅ **No boilerplate** - Server infrastructure is ready to use  
✅ **Multiple deployment modes** - stdio, MCP-only HTTP, REST+MCP HTTP via CLI  
✅ **Dynamic documentation** - Markdown-based docs via core.utils  
✅ **Dual interfaces** - MCP + REST API automatically  
✅ **Configuration** - Environment variable management  
✅ **Error handling** - Comprehensive exception handling  
✅ **Type safety** - Full Pydantic models and type hints  
✅ **Async support** - Async-first design throughout  
✅ **Logging** - Structured logging built-in  
✅ **CORS** - Configurable CORS support  
✅ **Health checks** - Standard endpoints  
✅ **Testing** - Comprehensive test suite included

## Customization

### Add New MCP Tools

Edit `mcp_bible/service.py`:

```python
def register_mcp_tools(self, mcp: FastMCP) -> None:
    @mcp.tool()
    async def my_new_tool(param: str) -> dict:
        """Tool description for AI"""
        return {"result": "value"}
```

### Add New REST Endpoints

Edit `mcp_bible/server.py`:

```python
def create_router(self) -> APIRouter:
    router = APIRouter()

    @router.get("/my-endpoint")
    async def my_endpoint():
        return {"data": "value"}

    return router
```

### Add New Configuration

Edit `mcp_bible/config.py`:

```python
class BibleAPIConfig(BaseModel):
    my_new_field: str = Field(default="value")
```

## Troubleshooting

### Import Errors

Make sure you're importing from `core`, not `mcp_weather.core`:

```python
from core.server import BaseMCPServer  # ✅ Correct
from mcp_weather.core.server import BaseMCPServer  # ❌ Wrong
```

### Module Not Found

Make sure mcp-weather is installed:

```bash
uv pip list | grep mcp-weather
```

If not installed, install it:

```bash
uv sync  # Installs from pyproject.toml
```

## Features Implemented ✅

✅ **Multiple deployment modes** (stdio, mcp, rest)  
✅ **CLI interface** with comprehensive help  
✅ **Dynamic documentation** using core.utils  
✅ **Bible passage retrieval** from BibleGateway.com  
✅ **8 Bible translations** supported  
✅ **Multiple passage support** (semicolon-separated)  
✅ **Comprehensive test suite** with mode testing  
✅ **REST API examples** and curl scripts  
✅ **Auto-discovery** of features  
✅ **Structured logging** throughout  

## Next Steps

- Add authentication providers (Authentik integration)
- Add more Bible API sources (Bible API, ESV API) 
- Implement passage search and concordance
- Add daily verses and reading plans
- Add Redis caching for performance
- Add metrics and monitoring
- Add Docker deployment examples

## Learn More

- [Using mcp-weather as Dependency](https://github.com/geosp/mcp-weather/blob/master/docs/USING_AS_DEPENDENCY.md)
- [Main mcp-weather README](https://github.com/geosp/mcp-weather/blob/master/README.md)
- [FastMCP Documentation](https://github.com/jlowin/fastmcp)
- [FastAPI Documentation](https://fastapi.tiangolo.com/)

## License

This project is provided as-is for use and modification.