# World Anvil MCP Server

MCP (Model Context Protocol) server for interfacing with World Anvil API to assist with D&D world development.

## Overview

This MCP server bridges Claude Code with the World Anvil platform, enabling AI-assisted worldbuilding through structured tools, resources, and prompts. Designed specifically for D&D campaign management and creative writing.

## Features

- **Content Management**: Articles, blocks, categories, manuscripts
- **Map Integration**: Interactive maps with markers and layers
- **Campaign Tools**: RPG systems, timelines, session notes
- **D&D Assistance**: NPC generation, location design, quest tracking
- **Notebook System**: Organized notes and documentation

## Prerequisites

- Python 3.11+
- uv (fast Python package manager) — https://docs.astral.sh/uv/
- World Anvil account with Grandmaster guild membership
- World Anvil API application key
- World Anvil user authentication token

## Installation

```bash
# Clone repository and enter it
cd world-anvil

# Recommended: create a local virtualenv with uv
uv venv --python 3.11 .venv

# Activate the environment
# macOS/Linux
source .venv/bin/activate
# Windows (PowerShell)
.venv\\Scripts\\Activate.ps1

# Install dependencies (dev extras optional)
uv pip install -e .[dev]

# Tip: you can also run without activating via uv
uv run world-anvil-mcp
```

Without uv:

```bash
python -m venv .venv
source .venv/bin/activate    # Windows: .venv\Scripts\Activate.ps1
pip install -e .[dev]
```

## Configuration

Create a `.env` file:

```env
WORLD_ANVIL_APP_KEY=your_application_key_here
WORLD_ANVIL_USER_TOKEN=your_user_token_here
```

## Usage

### Running the Server

```bash
# Start MCP server with stdio transport
world-anvil-mcp

# Or run directly with Python
python -m world_anvil_mcp.server
```

### With Claude Code

Add to your MCP settings:

```json
{
  "mcpServers": {
    "world-anvil": {
      "command": "world-anvil-mcp"
    }
  }
}
```

## Documentation

- [Design Specification](claudedocs/DESIGN_SPECIFICATION.md) - Complete architecture and design
- [API Reference](claudedocs/API_REFERENCE.md) - Tool and resource documentation
- [Usage Examples](claudedocs/USAGE_EXAMPLES.md) - Common workflows

## Project Status

🚧 In Development — Phase 0.4 (Early Implementation)

- Architecture and specifications drafted; initial server scaffolding in place.
- Quality gates configured (ruff, mypy, pytest); tests being added.
- See `docs/PHASE_0_STATUS.md` for detailed phase tracking and milestones.

## License

BSD 3-Clause License — See LICENSE file for details

## Resources

- [World Anvil API Documentation](https://www.worldanvil.com/api/external/boromir/documentation)
- [Model Context Protocol](https://modelcontextprotocol.io)