# Character Details MCP — User Guide

An MCP server that fetches structured information about fictional characters from Fandom wikis and Wikipedia, making it easy for LLMs to accurately portray or generate content for characters from games, anime, and other media.

---

## Quick Start (Docker — recommended)

### 1. Build the image

```bash
cd character_details
docker build -t character-details-mcp .
```

### 2. Add to Claude Desktop

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

```json
{
  "mcpServers": {
    "character-details": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-v", "character-details-cache:/root/.local/share/character_details",
        "character-details-mcp"
      ]
    }
  }
}
```

Restart Claude Desktop. The server will appear in the tools list.

**Important flags:**
- `-i` — keeps stdin open (required for stdio MCP transport)
- `--rm` — removes the container after the session ends
- `-v character-details-cache:...` — named Docker volume so the cache persists across sessions

---

## Quick Start (Local Python)

### Requirements

- Python 3.11+
- [uv](https://docs.astral.sh/uv/)

### Install

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

### Add to Claude Desktop

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

---

## Tool Reference

### `get_character`

Fetches complete character data. Checks the local cache first (24-hour TTL), fetches live if stale.

**Parameters:**
| Name | Type | Description |
|---|---|---|
| `name` | string | Character name, e.g. `"Aerith Gainsborough"` |
| `franchise` | string | Franchise name, e.g. `"Final Fantasy VII"` |

**Returns:** Formatted markdown with Description, Appearance, Personality, Background, Abilities, Relationships, and source URLs.

**Example prompt:**
> Use get_character to look up Aerith Gainsborough from Final Fantasy VII, then write a short scene where she tends her flowers.

---

### `refresh_character`

Same as `get_character` but bypasses the cache and re-fetches from source.

**Use when:** You suspect the cached data is incomplete, or you want the latest wiki content.

---

### `list_characters`

Lists all characters currently in the local cache with their franchise and cache timestamp.

---

### `remove_character`

Deletes a specific character from the cache.

**Parameters:** `name`, `franchise`

---

### `generate_image_prompt`

Builds a comma-separated tag list for image generation tools (Stable Diffusion, Midjourney, DALL-E, etc.).

**Parameters:**
| Name | Type | Description |
|---|---|---|
| `name` | string | Character name |
| `franchise` | string | Franchise name |
| `style` | string | Art style hint (optional), e.g. `"anime"`, `"oil painting"`, `"pixel art"` |
| `scene` | string | Scene description (optional), e.g. `"in a flower field"`, `"battle pose"` |
| `extra_tags` | string | Comma-separated additional tags (optional) |

**Example prompt:**
> Use generate_image_prompt for Princess Peach (Super Mario) in an anime style, standing in her castle throne room.

---

### `generate_story_context`

Produces a structured reference document for roleplay or creative writing. Includes overview, personality, background, appearance, abilities, and relationships.

**Parameters:**
| Name | Type | Description |
|---|---|---|
| `name` | string | Character name |
| `franchise` | string | Franchise name |
| `scenario` | string | Current scenario to include (optional) |
| `include_abilities` | boolean | Whether to include abilities section (default: true) |

**Example prompt:**
> Use generate_story_context for Sucy Manbavaran from Little Witch Academia. The scenario is: she's been asked to teach a potions class after the regular teacher falls ill.

---

## Supported Franchises

The following franchises have a dedicated Fandom wiki mapped for richer data:

| Franchise | Wiki | Aliases |
|---|---|---|
| Final Fantasy (I–XVI) | finalfantasy.fandom.com | final fantasy 1–16, ffi–ffxvi, ff1–ff16 |
| Super Mario | mario.fandom.com | mario, super mario |
| Little Witch Academia | little-witch-academia.fandom.com | lwa |
| Uma Musume | umamusume.fandom.com | uma musume pretty derby |
| Fire Emblem | fireemblem.fandom.com | |
| Senran Kagura | senrankagura.fandom.com | |
| Vocaloid | vocaloid.fandom.com | |
| Dragon Ball | dragonball.fandom.com | dragon ball z, dbz, dragon ball super, dbs |
| League of Legends | leagueoflegends.fandom.com | lol |
| Street Fighter | streetfighter.fandom.com | |
| Sonic | sonic.fandom.com | sonic the hedgehog |
| Spy x Family | spy-x-family.fandom.com | spy family, spyxfamily |
| The Legend of Zelda | zelda.fandom.com | zelda, legend of zelda |
| The Witcher | witcher.fandom.com | witcher |
| Metroid | metroid.fandom.com | |
| Pokemon | pokemon.fandom.com | pokémon |

Characters from other franchises will still work using Wikipedia as the data source. The data will be less detailed but usable.

---

## Adding a New Franchise

Open [src/character_details/fetcher.py](src/character_details/fetcher.py) and add an entry to `FRANCHISE_WIKIS`:

```python
FRANCHISE_WIKIS: dict[str, str] = {
    # existing entries ...
    "my hero academia": "myheroacademia",   # maps to myheroacademia.fandom.com
    "mha": "myheroacademia",
}
```

The value is the Fandom community subdomain (the part before `.fandom.com`). You can find it by visiting the character's wiki and noting the URL.

After editing, rebuild the Docker image:

```bash
docker build -t character-details-mcp .
```

---

## Cache

- Location: `~/.local/share/character_details/cache/` (host) or the `character-details-cache` Docker volume
- Format: one JSON file per character
- TTL: 24 hours — expired entries are re-fetched automatically
- Manual clear: use `remove_character` tool, or delete the JSON files / volume directly

---

## Using with the Claude API / SDK

If you're building an application with the Anthropic SDK rather than Claude Desktop, start the server in stdio mode and connect it as an MCP server:

```python
import anthropic

client = anthropic.Anthropic()

# Point to the server command
server_params = {
    "command": "docker",
    "args": [
        "run", "--rm", "-i",
        "-v", "character-details-cache:/root/.local/share/character_details",
        "character-details-mcp"
    ]
}
```

See the [MCP Python SDK docs](https://github.com/modelcontextprotocol/python-sdk) for full integration examples.

---

## Troubleshooting

**No data returned / all fields empty**
- Check internet connectivity from inside the container: `docker run --rm character-details-mcp python -c "import httpx; import asyncio; asyncio.run(httpx.AsyncClient().get('https://en.wikipedia.org'))"`
- Some franchises don't have a Fandom wiki mapped — add one (see above)

**Stale or incorrect data**
- Use `refresh_character` to bypass the cache
- Or delete the cached file from the volume

**Claude Desktop doesn't show the server**
- Verify the JSON config is valid (no trailing commas)
- Confirm the image name matches exactly: `character-details-mcp`
- Check Claude Desktop logs: `~/Library/Logs/Claude/`