Bible MCP Server

# 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.