d4d6788d26
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>
137 lines
3.5 KiB
Markdown
137 lines
3.5 KiB
Markdown
# 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 |