Files

Aodhan Collins d4d6788d26 Add 13 new Fandom wiki sources and integration tests

Expand franchise wiki mappings to cover Uma Musume, Fire Emblem,
Senran Kagura, Vocaloid, Dragon Ball, League of Legends, Street Fighter,
Sonic, Spy x Family, Zelda, The Witcher, Metroid, and Pokemon. Also
expand Final Fantasy aliases to cover all numbered titles I–XVI with
both arabic and roman numeral variants.

Adds parametrized integration tests that verify each wiki endpoint
returns valid CharacterData with a description and Fandom source URL.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

2026-03-19 21:41:53 +00:00

3.5 KiB

Raw Permalink Blame History

Character Details MCP

An MCP server that helps LLMs gather rich, structured information about fictional characters for storytelling and image generation.

It fetches from Fandom wikis and Wikipedia, then caches results locally (24-hour TTL) for fast follow-up responses.

Tools

Tool	Description
`get_character`	Fetch full character details (cached or live)
`refresh_character`	Force re-fetch from external sources
`list_characters`	List all locally cached characters
`remove_character`	Delete a character from the local cache
`generate_image_prompt`	Build a tag list for image generation tools
`generate_story_context`	Build a structured reference doc for roleplay/writing

Data Sources

Fandom wikis — franchise-specific, much richer character data
Wikipedia — supplements missing sections

Supported franchise → wiki mappings are defined in fetcher.py (FRANCHISE_WIKIS). Adding a new franchise is a one-liner.

Setup

Requirements

Python 3.11+
uv (recommended) or pip

Install

cd character_details
uv pip install -e .

Run (stdio transport)

uv run character-details

Add to Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "character-details": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/absolute/path/to/character_details",
        "character-details"
      ]
    }
  }
}

Docker Deployment

A deploy.sh script is provided for easy Docker build and deployment.

Quick Start

./deploy.sh build    # Build the Docker image
./deploy.sh run      # Run the container locally

Commands

Command	Description
`build`	Build the Docker image
`run`	Run the container locally with cache volume
`push`	Push the image to a registry
`deploy`	Build and push in one step
`clean`	Remove local images and containers

Options

./deploy.sh build -t v1.0.0                    # Build with specific tag
./deploy.sh push -r docker.io/myuser/          # Push to Docker Hub
./deploy.sh deploy -t v1.0.0 -r ghcr.io/myuser/  # Build and push to GitHub Container Registry

Environment Variables

IMAGE_TAG - Image tag (default: latest)
REGISTRY - Registry prefix (e.g., "docker.io/username/")
IMAGE_NAME - Image name (default: character-details)

Cache

Character data is cached at ~/.local/share/character_details/cache/ as JSON files. Each entry expires after 24 hours. Use refresh_character to force an update.

Project Structure

character_details/
  src/character_details/
    __init__.py
    models.py     # Pydantic data model (CharacterData)
    cache.py      # Read/write/list local JSON cache
    fetcher.py    # Fandom + Wikipedia fetching & section parsing
    server.py     # FastMCP server and tool definitions
  pyproject.toml
  README.md
  deploy.sh     # Docker build and deployment script

Test Characters

Aerith Gainsborough — Final Fantasy VII
Princess Peach — Super Mario
Sucy Manbavaran — Little Witch Academia
Tokai Teio — Uma Musume
Marth — Fire Emblem
Asuka — Senran Kagura
Hatsune Miku — Vocaloid
Goku — Dragon Ball
Jinx — League of Legends
Ryu — Street Fighter
Sonic — Sonic the Hedgehog
Anya Forger — Spy x Family
Link — The Legend of Zelda
Geralt of Rivia — The Witcher
Samus Aran — Metroid
Pikachu — Pokemon

3.5 KiB Raw Permalink Blame History