Kairos Codex MCP Server

# Kairos Codex - MCP Server This server implements the Model Context Protocol (MCP) to provide standardized access to Bible data resources. It acts as a "tool provider" for Large Language Models (LLMs), allowing them to query Bible translations, books, and verses. The server is implemented in `bible.py` and acts as a wrapper around the Bible API at `https://bible.helloao.org`, providing MCP tools for Bible access with comprehensive error handling and authentication support. ## Core Functionality The server provides the following MCP tools: * **get_translations** - Get list of available Bible translations, with optional language filtering * **get_books** - Get list of books available in a specific Bible translation * **get_verses** - Get specific verse(s) from a chapter in a given translation * **get_chapter** - Get an entire chapter from a book in a given translation ## Tech Stack * **Language:** Python 3.11+ * **MCP Framework:** FastMCP * **HTTP Client:** `httpx` * **Authentication:** Simple token-based auth (optional) * **Data Format:** JSON responses with structured error handling * **Containerization:** Docker support included ## Available Tools ### get_translations(language) - **Description:** Get list of available Bible translations - **Parameters:** - `language` (str): Language to filter for (matches language, languageEnglishName, or languageName) - **Returns:** List of translation objects with id, name, englishName, language, numberOfBooks, etc. ### get_books(translation_id) - **Description:** Get list of books available in a specific Bible translation - **Parameters:** - `translation_id` (str): The translation ID to get books for - **Returns:** Object with translation info and list of books with id, name, commonName, numberOfChapters, etc. ### get_verses(translation_id, book, chapter, verse_start, verse_end?) - **Description:** Get specific verse(s) from a chapter - **Parameters:** - `translation_id` (str): The translation ID to use - `book` (str): Book name, tag, or ID - `chapter` (int): Chapter number - `verse_start` (int): Starting verse number (inclusive) - `verse_end` (int, optional): Ending verse number (inclusive) - **Returns:** Structured object with translation info, book info, and verse data with metadata ### get_chapter(translation_id, book, chapter) - **Description:** Get an entire chapter from a book - **Parameters:** - `translation_id` (str): The translation ID to use - `book` (str): Book name, tag, or ID - `chapter` (int): Chapter number - **Returns:** Structured object with translation info, book info, and all verses in the chapter ## Getting Started ### Prerequisites * Python 3.11+ * Required packages: `fastmcp`, `httpx`, `pydantic`, `PyYAML`, `python-dotenv` ### Installation Install dependencies: ```bash pip install -r requirements.txt ``` ### Configuration Optionally set authentication token for access control. You can do this in two ways: #### Option 1: Environment variable ```bash export BIBLE_SERVER_TOKEN=your_token_here ``` #### Option 2: .env file (recommended) Create a `.env` file in the project root: ```bash echo "BIBLE_SERVER_TOKEN=your_token_here" > .env ``` If no token is set, the server runs without authentication. ### Running the Server #### Direct Python execution: ```bash python bible.py ``` #### Using Docker: ```bash # Build and run with docker-compose docker-compose up --build # Or build and run manually docker build -t kairos-codex-mcp . docker run -p 8000:8000 kairos-codex-mcp ``` The server runs using streamable HTTP transport on port 8000 and can be connected to by MCP clients. ## Contributing **(To be filled in later - contribution guidelines)** ## License **(To be determined - e.g., MIT, GPL)**