Content
# Tool List
Starting from the character name, organize information through Web MCP and generate prompts that can be used for role-playing. It also supports generating character cards for SillyTavern.
## Application Examples
In my own project [umamusume-agent](https://github.com/quantumxiaol/umamusume-agent)
<img src=resources/pngs/example.png>
In the [SillyTavern](https://github.com/SillyTavern/SillyTavern) project
Import character card
<img src=resources/pngs/character_import.png>
And character conversation
<img src=resources/pngs/character_chat.png>
## Project Structure
```
umamusume-agent-prompt/
|-- umamusume_prompt/
| |-- mcp/
| | |-- server.py # Web MCP service (integrated with umamusume-web-crawler)
| |-- prompts/
| | |-- collect_web.md # Phase 1: Information collection
| | |-- build_prompt.md # Phase 2: Prompt generation
| | |-- build_SillyTavern_character.md # Phase 2: SillyTavern character card generation
| |-- characters.py # Character mapping reading/parsing
| |-- pipeline.py # Two-phase process
| |-- pipeline_sillytavern.py# SillyTavern two-phase process
| |-- cli.py # CLI entry
| |-- config.py # Environment variable configuration
|-- tests/
| |-- test_google.py # Google search test (through library encapsulation)
| |-- test_crawler.py # General crawling test
| |-- test_mcp_tool_crawler.py# MCP crawling tool test
| |-- test_mcp_tool_crawler_moegirl.py # MCP MoeGirls Encyclopedia crawling test
| |-- test_mcp_tool_google.py # MCP search tool test
| |-- test_stream_mcp.py # Agent calls MCP tool test
| |-- test_biligame_crawler.py# Bilibili Wiki API crawling test
| |-- test_moegirl_crawler.py # MoeGirls Encyclopedia API crawling test
|-- scripts/
| |-- build_SillyTavern_card.py # Assemble SillyTavern character card from role_prompt + image (CCV2)
|-- main.py # CLI entry
|-- mcpserver.py # MCP entry
|-- download_models.py # Docling model download script (if using Docling)
|-- umamusume_characters.json
|-- results/
|-- examples/
```
## Environment
Use uv to manage the environment.
```bash
uv lock
uv sync
source .venv/bin/activate
cat .env.example > .env
```
Set in `.env`:
- `INFO_LLM_MODEL_API_KEY`
- `WRITER_LLM_MODEL_API_KEY`
- `GOOGLE_API_KEY`
- `GOOGLE_CSE_ID`
- `HTTP_PROXY` / `HTTPS_PROXY` (optional, if accessing Google, MoeGirls Encyclopedia requires a proxy, then set; if not set, access directly)
Where `INFO_LLM` is responsible for tool calls, and `WRITER_LLM` is responsible for output.
Please create `GOOGLE_API_KEY` in the [Google Cloud Credential Console](https://console.cloud.google.com/apis/credentials) and create `GOOGLE_CSE_ID` using [Programmable Search Engine](https://programmablesearchengine.google.com/controlpanel/create).
## Crawler Process (Current)
Core capabilities have been migrated to the `umamusume-web-crawler` library.
The current default uses the **MediaWiki API** crawling process, which is more stable and efficient than visual crawling:
1) **Site Search**: Search Bilibili Wiki / MoeGirls Encyclopedia through API to get accurate page titles.
2) **API Pull**: Directly call MediaWiki API to pull Wikitext.
3) **Parsing and Cleaning**:
- Automatically expand Transclusion sub-pages.
- Parse InfoBox and key sections.
- Convert to LLM-friendly Markdown format.
MCP tool `crawl_biligame_wiki` / `crawl_moegirl_wiki` returns this cleaned Markdown.
For non-Wiki pages, provide `crawl_page` tool using headless browser (MarkItDown/Crawl4AI) for general crawling.
## Exploration Experience (Brief)
- Early attempts at HTML cleaning, Bwiki dynamic structure processing difficulties.
- Mid-term use of "visual crawling (screenshot to PDF to Markdown)", good results but high cost and dependent on browser environment.
- Final solution: Integrate `umamusume-web-crawler`, use MediaWiki API for structured data acquisition, supplemented by visual crawlers for general web pages.
## Running
1) Start Web MCP service
```bash
python mcpserver.py --http -p 7777
```
2) Generate character Prompt
```bash
python main.py --mcp-url http://127.0.0.1:7777/mcp/ --character
```
Output will be written to `results/<character name>/web_info.md` and `results/<character name>/role_prompt.md`.
3) Generate SillyTavern character card text
```bash
python main.py --mcp-url http://127.0.0.1:7777/mcp/ --character --build-target sillytavern
```
Default output will be written to `results_SillyTavern/<character name>/web_info.md` and `results_SillyTavern/<character name>/role_prompt.md`.
4) Assemble `results_SillyTavern` text + `results_images` best costume image into SillyTavern character card
```bash
uv run python scripts/build_SillyTavern_card.py
```
Single character construction example:
```bash
uv run python scripts/build_SillyTavern_card.py --character
```
Output will be written to `results_SillyTavern/<character name>/character_card_v2.json` and `results_SillyTavern/<character name>/character_card_v2.png`.
## Testing
Please start MCP service before running tests:
```bash
python mcpserver.py --http -p 7777
```
```bash
python tests/test_google.py
python tests/test_mcp_tool_crawler.py -u http://127.0.0.1:7777/mcp/
python tests/test_mcp_tool_crawler_moegirl.py -u http://127.0.0.1:7777/mcp/
python tests/test_stream_mcp.py -u http://127.0.0.1:7777/mcp/ -q ""
```
Run using pytest:
```bash
pytest -q
```
## Generated Examples
- [](./examples/.md)
- [](./examples/.md)
- [](./examples/.md)
- [](./examples/.md)
- [](./examples/.md)
- [](./examples/.md)
- [](./examples/.md)
- [](./examples/.md)
- [](./examples/.md)
- [](./examples/.md)
- [](./examples/.md)
- [](./examples/.md)
- [](./examples/.md)
- [](./examples/.md)
- [](./examples/.md)
- [](./examples/.md)
- [](./examples/.md)
- [](./examples/.md)
- [](./examples/.md)
- [](./examples/.md)
- [](./examples/.md)
