Alethea World History Engine MCP Server

Alethea 🌍

A narrative graph engine used to generate, track, and visualize fictional worlds using LLMs or purely procedurally.

History graph viewer

📖 Overview

World History Engine is a narrative framework that can work in two modes:

1. AI-Assisted: As an MCP Server for LLMs (like Claude), allowing them to query and mutate the world state consistently.
2. Procedural (Standalone): As a classic generator where you use the GUI or CLI to spawn worlds based on YAML templates, without needing an API key or LLM.

It maintains a consistent internal graph database of entities (Factions, Characters, Locations) and their relationships.

✨ Key Features

• 🕵️‍♂️ RAG for Fiction: Keeps track of thousands of entities without filling up the LLM context window.
• 🎲 Dual Mode: Works with Claude/OpenAI OR as a standalone offline generator.
• 🕸️ Graph-Based Consistency: Entities have strict relationships (e.g., Faction A --[war]--> Faction B).
• ⏳ Time-Travel Debugging: Includes a web-based visualizer (world_viz.html) with a timeline slider. Roll back history to see how the world looked 50 epochs ago.

🏗 Architecture

Here is the internal structure of the world engine entities:

graph TD
    %% --- Styles ---
    classDef browser fill:#f9f,stroke:#333,stroke-width:2px;
    classDef mcp fill:#ffecb3,stroke:#ff6f00,stroke-width:2px,stroke-dasharray: 5 5;
    classDef storage fill:#e0e0e0,stroke:#333,stroke-width:2px;
    classDef core fill:#e1f5fe,stroke:#0277bd,stroke-width:2px;

    %% --- Clients ---
    subgraph Clients ["Clients & Interfaces"]
        BrowserUI[BrowserWeb Visualizer / GUI]:::browser
        ClaudeApp[Claude DesktopAI Assistant]:::mcp
    end

    %% --- Backend ---
    subgraph Backend ["Backend (Python)"]
        
        %% Entry Points
        subgraph EntryPoints ["Entry Points"]
            Server[server.pyHTTP API & GUI]:::core
            CLI[main.pyCLI Generator]:::core
            MCPSrv[mcp_server.pyMCP Server]:::mcp
        end

        DI((Dishka IOC))

        subgraph Services ["Services"]
            TES[TemplateEditorService]
            SIM_S[SimulationService]
            ST_S[StorytellerService]
            WQS[WorldQueryService]
            NS[NamingService]
        end
        
        %% Core Logic
        subgraph CoreEngine ["Core Engine"]
            WG[WorldGenerator]
            Repo[InMemoryRepository]
        end

        %% Connections
        ClaudeApp == Stdio/SSE ==> MCPSrv
        BrowserUI == HTTP ==> Server
        
        Server & MCPSrv & CLI --> DI
        DI --> Services
        Services --> CoreEngine
    end

    %% --- Storage ---
    subgraph Storage ["Storage"]
        YAML[(YAML Templates)]:::storage
        JSON[(World JSON)]:::storage
    end

    Repo -.-> JSON
    TES -.-> YAML

🚀 Quick Start

🐳 Docker Deployment

1. Build the Image

Build the container image from the root of your repository:

docker build -t world-engine .

2\. Run the Container

Run the image, exposing the two required ports. Replace your_api_key_here with your actual key. You can skip BASE_URL if using standard OpenAI.:

docker run -d \
  --name world-engine \
  -p 8000:8000 \
  -p 8001:8001 \
  -e API_KEY="sk-..." \
  -e MODEL="claude-4-5-sonnet-latest" \
  -e BASE_URL="[https://api.anthropic.com/v1](https://api.anthropic.com/v1)" \
  world-engine

3\. Access

• Web UI (Standalone Generation): Access the graphical interface at http://localhost:8001.
• MCP Server (AI Integration): Connect your Claude Desktop or other MCP client to http://localhost:8000.
• Logs: View combined logs for both services: docker logs world-engine-instance.

Prerequisites for deployment without Docker

• Python 3.11+
• uv (recommended) or pip

Installation

# Clone the repository
git clone [https://github.com/your-username/world-history-engine.git](https://github.com/your-username/world-history-engine.git)
cd world-history-engine

# Install dependencies
uv sync

🎲 Generating Worlds (Standalone)

You can generate worlds without configuring any AI:

Option 1: Graphical Interface (GUI) Start the web server to generate and visualize worlds interactively.

uv run server.py
# Open [http://127.0.0.1:8001](http://127.0.0.1:8001) in your browser

Option 2: Command Line (CLI) Run the main generation script to create a fresh world snapshot in world_output/.

uv run main.py

🤖 Running with LLM (MCP Server)

To use this engine as a tool inside Claude (for interacti