# 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](https://docs.astral.sh/uv/) (recommended) or pip

### Install

```bash
cd character_details
uv pip install -e .
```

### Run (stdio transport)

```bash
uv run character-details
```

### Add to Claude Desktop

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

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

## Docker Deployment

A [`deploy.sh`](deploy.sh:1) script is provided for easy Docker build and deployment.

### Quick Start

```bash
./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

```bash
./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