Which integrations are available for this server?

Supports OpenAI models to facilitate procedural or AI-driven generation and management of graph-based world histories.

How do I use Alethea World History Engine?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Alethea World History Engine List all factions currently at war and summarize their main grievances." That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

Alethea 🌍

License: MIT Python 3.11+ MCP Ready

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:

AI-Assisted: As an MCP Server for LLMs (like Claude), allowing them to query and mutate the world state consistently.
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[Browser Web Visualizer / GUI]:::browser ClaudeApp[Claude Desktop AI Assistant]:::mcp end %% --- Backend --- subgraph Backend ["Backend (Python)"] %% Entry Points subgraph EntryPoints ["Entry Points"] Server[server.py HTTP API & GUI]:::core CLI[main.py CLI Generator]:::core MCPSrv[mcp_server.py MCP 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 interactive storytelling), run the MCP server:

uv run mcp_server.py

Add this to your claude_desktop_config.json:

{ "mcpServers": { "world-engine": { "command": "uv", "args": [ "run", "mcp_server.py" ], "env": { "PYTHONUNBUFFERED": "1" } } } }

To use this engine as a tool inside Qwen Desktop, paste the following configuration in the MCP settings:

{ "mcpServers": { "world-builder": { "url": "http://0.0.0.0:8000" } }

And add description

📊 Visualizing Your World

The engine comes with a standalone HTML visualizer.

Generate a world using GUI, CLI, or MCP.
Open static/world_viz.html in your browser.
Upload the JSON export (from world_output/).
Explore: Drag nodes, filter by factions, and use the Timeline Slider to replay history.

⚙️ Configuration & Templates

The engine's logic is data-driven. You can modify the simulation rules in data/templates/:

factions.yaml: Define cultures, taboos, and aggression levels.
biomes.yaml: Configure environmental generation.
resources.yaml: Manage economy items.

And more other rules of naming in data/naming

🗺️ Roadmap

Persistent storage (PostgreSQL/Neo4j support)
Develop AI driven quest generator

🤝 Contributing

Contributions are welcome! Please check out the issues tab or submit a PR.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

Alethea World History Engine