88 lines
2.2 KiB
Markdown
88 lines
2.2 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"
|
|
]
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
## 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 |