World-Anvil-MCP: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

---

Project Overview

World Anvil MCP Server - An MCP (Model Context Protocol) server that bridges Claude Code with the World Anvil API for AI-assisted D&D campaign management and worldbuilding.

Status: Phase 0.4 (Early Implementation) — Architecture complete; core scaffolding in progress License: BSD 3-Clause Python: 3.11+ required

---

Architecture

Core Design Principles

1. MCP-Native: Built-in FastMCP Context integration (not bolted on)
2. Async-First: All I/O uses async/await with httpx.AsyncClient
3. Type-Safe: Pydantic v2 models for all API responses
4. Resilient: Built-in retry logic, rate limiting, and caching
5. Workflow-Driven: Designed for 10 specific D&D campaign workflows (see docs/workflows/)

Component Architecture

MCP Server (FastMCP)
  └─> WorldAnvilClient (main entry point)
       ├─> Endpoint Classes (ArticleEndpoint, WorldEndpoint, etc.)
       │    └─> BaseEndpoint (generic request handling)
       │         ├─> ResponseCache (TTL-based caching)
       │         ├─> RateLimiter (token bucket, 60 req/min)
       │         └─> Retry Logic (tenacity with exponential backoff)
       └─> httpx.AsyncClient (connection pooling, timeout management)

Key Pattern: The client delegates to specialized endpoint classes (15+ endpoints planned), each inheriting from BaseEndpoint[T] generic that handles:

• Request execution with MCP Context logging
• Automatic retries for transient failures (RateLimitError, ServerError)
• Response caching with granularity-aware keys
• Error parsing and exception mapping

Critical Implementation Details

Authentication: World Anvil uses custom headers (NOT Bearer tokens):

headers = {
    "x-auth-token": user_token,      # Lowercase, not X-Auth-Token
    "x-application-key": app_key,    # Lowercase, not X-Application-Key
}