a4d95fac8a
- Add comprehensive deploy.sh script with build, run, push, deploy, and clean commands - Support configurable image tags, registries, and image names - Add Docker deployment documentation to README.md - Update project structure to include deploy.sh
124 lines
3.2 KiB
Markdown
124 lines
3.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"
|
|
]
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
## 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 |