# 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"
      ]
    }
  }
}
```

## 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
```

## Test Characters

- Aerith Gainsborough — Final Fantasy VII
- Princess Peach — Super Mario
- Sucy Manbavaran — Little Witch Academia