Initial commit: Character Details MCP Server

README.md

@@ -0,0 +1,88 @@
+# 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