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