# Vibe Worldbuilding MCP

> **Create detailed fictional worlds with Claude** - Complete with automatic taxonomies, interconnected entries, AI-generated images, and navigable websites.

![Example World](example-worlds/verdant-realms-20250604-143521/images/world-overview-header.png)

## ⚡ Quick Start

### 1. Install Dependencies
```bash
# Python dependencies
pip install -e .

# Node.js dependencies  
npm install
```

### 2. Configure FAL API (Optional - for image generation)
```bash
# Add your FAL API key to .env
echo "FAL_KEY=your_api_key_here" > .env
```

### 3. Set Up MCP Server
Add to your Claude Desktop configuration:
```json
{
  "mcpServers": {
    "vibe-worldbuilding": {
      "command": "python3",
      "args": ["./vibe_worldbuilding_server.py"],
      "env": {
        "FAL_KEY": "your_fal_api_key_here"
      }
    }
  }
}
```

### 4. Create Your First World
```
1. Ask Claude: "Create a fantasy world about floating islands"
2. Claude uses MCP tools to build complete world structure
3. Generated world includes entries, images, and navigable website
```

## 🌟 What You Get

**Complete Worldbuilding Pipeline:**
- ✅ **Rich world concepts** with detailed lore and atmosphere
- ✅ **Custom taxonomies** (characters, locations, artifacts, etc.)
- ✅ **Interconnected entries** with automatic cross-references
- ✅ **AI-generated images** for visual world elements
- ✅ **Static websites** with navigation and image galleries
- ✅ **Auto-stub generation** for referenced entities

## 📚 Documentation

| Document | Purpose |
|----------|---------|
| **[📖 User Guide](docs/README.md)** | Complete usage documentation and examples |
| **[⚡ Workflow Guide](docs/WORKFLOW.md)** | MCP command sequence and best practices |
| **[🔧 Development Guide](docs/DEVELOPMENT.md)** | Contributing and development setup |
| **[🏗️ Architecture Guide](docs/ARCHITECTURE.md)** | System design and technical details |

## 🧪 Testing

```bash
# Run complete test suite
python tests/run_tests.py

# Test with image generation
python tests/test_e2e_comprehensive.py --verbose

# Keep test world for exploration
python tests/test_e2e_comprehensive.py --verbose
```

## 🚀 Example Worlds

- **[Verdant Realms](example-worlds/)** - Bioluminescent forest ecosystem
- **[Test Worlds](test-worlds/)** - Generated by test suite

## 📄 License

MIT License - See [LICENSE](LICENSE) for details.

---

**Made with Claude** 🤖 | **Powered by MCP** ⚡ | **Enhanced with AI Images** 🎨
README

Installation
