batson-j_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:

pip install -r requirements.txt

Configuration

Optionally set authentication token for access control. You can do this in two ways:

Option 1: Environment variable

export BIBLE_SERVER_TOKEN=your_token_here

Option 2: .env file (recommended)

Create a .env file in the project root:

echo "BIBLE_SERVER_TOKEN=your_token_here" > .env

If no token is set, the server runs without authentication.

Running the Server

Direct Python execution:

python bible.py

Using Docker:

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