@thijshakkenberg/valkyrie Mom

GitHub Actions

MCP server for AI-assisted Mansions of Madness scenario creation with Valkyrie

Add to Cursor Add to VS Code Run on PlugMCP

1{2  "mcpServers": {3    "thijshakkenberg-valkyrie-mom-mcp": {4      "command": "npx",5      "args": [6        "-y",7        "@thijshakkenberg/[email protected]"8      ]9    }10  }11}

.cursor/mcp.jsonMCP server

Transport: stdio
Status: Local

Power your agent

Add this server

The publisher's own command. Not a PlugMCP endpoint.

Add to Cursor Add to VS Code Run on PlugMCP

Host a copy with our keys and logs.

Local command

npx -y @thijshakkenberg/[email protected]

Claude Code has no install link for a local command. Copy the command below and run it in a terminal.

shClaude Code

1claude mcp add thijshakkenberg-valkyrie-mom-mcp -- npx -y @thijshakkenberg/valkyrie-mom-mcp@2.6.0

Run in a terminal.

jsonClaude Desktop

1{2  "mcpServers": {3    "thijshakkenberg-valkyrie-mom-mcp": {4      "command": "npx",5      "args": [6        "-y",7        "@thijshakkenberg/[email protected]"8      ]9    }10  }11}

claude_desktop_config.json

Local · npmPublisher installStep-by-step: add this in Claude

Remote URL or a command on your machine? How the two installs differ

Run on PlugMCP

Host a copy with our keys and logs.

A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.

Launch

Server facts

Local

Transport: stdio
Version: 2.6.0
Last checked: 2026-10-28

Stars: —
Tools: —
Uptime: —

Tools

No tool list yet. Remote servers get one after the first health check.

FAQ

Questions

How do I install @thijshakkenberg/valkyrie Mom?

Copy the stdio config for Cursor, Claude Desktop, Claude Code, or VS Code on this page. It uses the publisher's install, not a PlugMCP proxy.

Does @thijshakkenberg/valkyrie Mom need an API key?

No required environment variable is listed on this record.

What transport does @thijshakkenberg/valkyrie Mom use?

@thijshakkenberg/valkyrie Mom runs locally over stdio.

When was @thijshakkenberg/valkyrie Mom last checked?

Last checked 2026-10-28. MCP server for AI-assisted Mansions of Madness scenario creation with Valkyrie

From the publisher

Documentation

valkyrie-mom-mcp

MCP (Model Context Protocol) server and Claude Code plugin for AI-assisted Mansions of Madness 2nd Edition scenario creation with Valkyrie.

What it does

This server exposes Valkyrie scenario editing as MCP tools, enabling AI assistants (Claude, etc.) to create, modify, validate, and build complete MoM scenarios. It auto-detects the Valkyrie editor directory so scenarios appear directly in the app.

The plugin bundles 10 skills covering advanced patterns (event loops, mythos scaling, tile placement chains, custom puzzles, generated artwork, spoken narration, generated sound effects, etc.) and an autonomous scenario designer agent.

Install

As a Claude Code plugin (recommended)

claude plugin marketplace add thijs-hakkenberg/ValkyrieMCP
claude plugin install valkyrie-mom

This gives you:

MCP server with 25 tools for scenario editing (auto-started)
10 skills: /scenario, /event-patterns, /tile-placement, /variables-and-mythos, /custom-monsters, /ui-and-puzzles, /items-and-distribution, /artwork, /narration, /sound-effects
Scenario designer agent for autonomous scenario creation
5 MCP resources for format documentation

To update to the latest version:

claude plugin marketplace update valkyrie-mom
claude plugin update valkyrie-mom

To uninstall:

claude plugin uninstall valkyrie-mom

As a standalone MCP server (Claude Desktop, other MCP clients)

Add to your MCP client config (e.g., ~/.claude/mcp.json or Claude Desktop settings):

{
  "mcpServers": {
    "valkyrie-mom": {
      "command": "npx",
      "args": ["-y", "@thijshakkenberg/valkyrie-mom-mcp"]
    }
  }
}

This gives you the MCP tools and resources, but not the skills or agent (those require Claude Code).

As a Hermes Agent plugin

Hermes Agent installs the repository as a plugin with every tool and all skills:

hermes plugins install thijs-hakkenberg/ValkyrieMCP --enable

If Hermes offers to install the plugin's Node dependencies, answer N: they are only needed to develop the plugin. The plugin registers the MCP tools as native Hermes tools (toolset valkyrie-mom) and the skills as valkyrie-mom:<skill> (e.g. skill_view("valkyrie-mom:artwork")). On the first tool call it starts the matching @thijshakkenberg/valkyrie-mom-mcp version with npx (Node.js 20+ required) and keeps it running for the session, since the scenario being edited lives there. Pictures that tools return, such as render_map, are saved under ~/.hermes/cache/valkyrie-mom/ and their paths are given in the result. For a local checkout, set VALKYRIE_MCP_COMMAND="npx tsx /path/to/ValkyrieMCP/src/index.ts".

From source

git clone https://github.com/thijs-hakkenberg/ValkyrieMCP.git
cd ValkyrieMCP
npm install
npx tsx src/index.ts   # Run MCP server via stdio

Skills

Skill	Description
`/scenario`	Guided end-to-end scenario creation workflow
`/event-patterns`	Event loops, multi-question dialogues, silent events, token swaps, random events, variable branching
`/tile-placement`	Standard placement chains, multi-entry tiles, naming conventions
`/variables-and-mythos`	Variable system, mythos scaling formula, random generation, hero detection, content pack gating
`/custom-monsters`	Custom activations, evade/horror events, round-based spawn triggering
`/ui-and-puzzles`	Prologues, interactive journals, combination locks, built-in puzzle types
`/items-and-distribution`	Random items, unique items, starting items, inspection events
`/artwork`	Generate pictures with a local ComfyUI (FLUX.2 [klein] 4B) and show them: cover, intro cutscene, handouts, scenes, monsters, tokens, image puzzles
`/narration`	Read story text aloud with a local Kokoro voice: what to narrate, voices, pronunciations, how Valkyrie plays event audio
`/sound-effects`	Generate sound effects with a local ComfyUI (Stable Audio 3): prompts, lengths, stock sound or generated, an effect and narration on one moment

MCP Tools

Lifecycle

Tool	Description
`list_scenarios`	List all scenarios in the Valkyrie editor directory
`create_scenario`	Create a new scenario (defaults to Valkyrie editor dir)
`load_scenario`	Load an existing scenario from a directory
`get_scenario_state`	Get current scenario component/localization summary
`validate_scenario`	Run all validation rules
`save_scenario`	Write the scenario to its folder (edits stay in memory until saved or built)
`build_scenario`	Save and build the `.valkyrie` package with Valkyrie's manifest `.ini` and cover image (default: `Desktop/<Package>/`, like Valkyrie's Create Package)
`set_quest_config`	Set difficulty, play time, investigator count, cover image

Components

Tool	Description
`upsert_event`	Create or update an event
`upsert_tile`	Create or update a tile
`upsert_token`	Create or update a token
`upsert_spawn`	Create or update a monster spawn
`upsert_item`	Create or update an item
`upsert_puzzle`	Create or update a puzzle
`upsert_ui`	Create or update a UI element
`upsert_custom_monster`	Create or update a custom monster
`upsert_mplace`	Create or update a monster placement
`upsert_activation`	Create or update a custom monster activation
`delete_component`	Delete a component with cascade reference cleanup
`set_localization`	Set localization key-value pairs

Map

Tool	Description
`get_map_ascii`	Describe the board: tile areas, doors and where they lead (with explore-token spots), tokens and their tile, ASCII sketch
`render_map`	Render the board as a PNG with the real tile artwork (from Valkyrie's imported data) or a schematic, tokens numbered
`suggest_tile_layout`	Suggest coordinates for large (7x7) tiles in linear, L-shape, or hub-spoke layouts
`place_tile_relative`	Position and rotation for a new tile against an existing one, with a door lined up

Story

Tool	Description
`story_graph`	Project the storyline as a graph: a condensed text outline (buttons, conditions, effects, placed tokens, puzzles, monster events, endings, never-reached events), Mermaid, or an HTML page with the rendered flowchart

Artwork

Tool	Description
`artwork_status`	Check a local ComfyUI server and the FLUX.2 [klein] 4B model files; prints comfy-cli setup and download commands for anything missing
`generate_artwork`	Generate an image (4 steps, CFG 1, size presets per use) and save it into the scenario folder, with a preview

Artwork is optional and runs entirely on your machine. Setup with comfy-cli:

pip install comfy-cli && comfy install
comfy model download --url https://huggingface.co/Comfy-Org/flux2-klein-4B/resolve/main/split_files/diffusion_models/flux-2-klein-4b.safetensors --relative-path models/diffusion_models
comfy model download --url https://huggingface.co/Comfy-Org/flux2-klein-4B/resolve/main/split_files/text_encoders/qwen_3_4b.safetensors --relative-path models/text_encoders
comfy model download --url https://huggingface.co/Comfy-Org/flux2-dev/resolve/main/split_files/vae/flux2-vae.safetensors --relative-path models/vae
comfy launch --background

On NVIDIA GPUs with less VRAM, the fp8 model (black-forest-labs/FLUX.2-klein-4b-fp8) is smaller. Set VALKYRIE_COMFYUI_URL if ComfyUI runs somewhere other than http://127.0.0.1:8188. The /artwork skill covers prompts and where Valkyrie shows images.

Narration

Tool	Description
`narration_status`	Check the local text-to-speech engine and model, list the voices; `install=true` installs the engine
`generate_narration`	Speak components' dialog text with Kokoro-82M into OGG clips in the scenario folder (`audio/narration/<Event>.ogg`) and set their `audio=`. Speaks only the italic story text by default, expands `{qst:}`, turns icons into words, takes respellings for names

Narration is optional and runs entirely on your machine, on the CPU: Kokoro-82M (Apache 2.0) through kokoro-js, with OGG Vorbis encoding in WebAssembly, so no Python or ffmpeg is needed. narration_status install=true installs the engine once (about 450 MB, in ~/.cache/valkyrie-mom-mcp/kokoro, or VALKYRIE_TTS_DIR); the first narration downloads the model (about 330 MB). English voices only. The default voice, af_nicole at speed 0.9, was picked by ear from 15 voices for horror (bf_isabella, bm_lewis and bm_daniel also fit); the model's quality grades didn't predict the fit. The /narration skill covers what to narrate and how Valkyrie plays the clips.

Sound effects

Tool	Description
`sound_status`	Check a local ComfyUI server, the Stable Audio 3 Small SFX model files and the `--fp32-vae` flag; prints setup and download commands for anything missing
`generate_sound_effect`	Generate a sound from a description (8 steps, about 1 s per clip) into an OGG clip in the scenario folder (`audio/sfx/<Event>.ogg`) and set the events' `audio=`. Peak-normalised, silent tail cut; narration on an event is kept unless `assign=true`

Sound effects are optional and run on the same ComfyUI as artwork, with Stable Audio 3 Small SFX (Stability AI Community License), small enough for the CPU:

comfy model download --url https://huggingface.co/Comfy-Org/stable-audio-3/resolve/main/checkpoints/stable_audio_3_small_sfx.safetensors --relative-path models/checkpoints
comfy model download --url https://huggingface.co/Comfy-Org/stable-audio-3/resolve/main/text_encoders/t5gemma_b_b_ul2.safetensors --relative-path models/text_encoders
comfy launch --background -- --fp32-vae

Start ComfyUI with --fp32-vae: by default it decodes the audio in bfloat16, and every clip comes out as noise. Other flags (such as --force-fp16 for FLUX) can stay. ComfyUI saves FLAC; the server converts it to OGG Vorbis in WebAssembly, so no ffmpeg is needed. The /sound-effects skill covers prompts and when a stock sound will do.

Reference

Tool	Description
`search_game_content`	Search game content catalogs (846 entries across tiles, monsters, items, audio)

Diagnostics

Tool	Description
`export_bug_report`	Generate a ZIP bug report with session trace, scenario files, validation results, and Valkyrie logs

MCP Resources

Resource	URI
Event format docs	`valkyrie://format/events`
Localization format docs	`valkyrie://format/localization`
Component format docs	`valkyrie://format/components`
Pattern reference	`valkyrie://format/patterns`
Current scenario state	`valkyrie://scenario/current`

MCP Prompts

Prompt	Description
`create-scenario`	Guided workflow for creating a new scenario
`review-scenario`	Analyze a scenario for balance and completeness

Valkyrie Editor Paths

The server auto-detects where Valkyrie stores editor scenarios:

Platform	Path
macOS / Linux	`~/.config/Valkyrie/MoM/Editor/`
Windows	`%APPDATA%\Valkyrie\MoM\Editor\`

Scenario File Format

A scenario is a directory containing:

quest.ini - Quest config and file listings
events.ini - Event components (triggers, buttons, branching)
tiles.ini - Map tile placements
tokens.ini - Search, explore, interact, and wall tokens
spawns.ini - Monster spawn configurations
items.ini - Quest items
ui.ini - UI elements (backgrounds, etc.)
other.ini - Puzzles and misc components
Localization.English.txt - CSV localization (key,value pairs)

Built scenarios are ZIP archives with a .valkyrie extension.

Validation Rules

The server validates scenarios against 18 rule categories, checked against Valkyrie 3.28 (quest format 21):

Unique names - No duplicate component names
Required fields - Tiles have side or customImage, displayed events have buttons
Cross-references - All referenced components exist; remove #keywords are valid
Event graph - EventStart trigger exists, no unreachable/dead-end events
Event flow - No endless loops of hidden events
Localization completeness - Event text, button labels, quest metadata
Format rules - Valid format version (4-21) and high enough for the features used, type=MoM, tile rotations
Catalog references - Tile sides, monster names, items match game content
Tile connectivity - Tiles don't overlap, touch at least one other tile, and share a lined-up door or open edge (door data measured from the tile artwork)
Mythos structure - Proper mythos trigger configuration
Investigator token - TokenInvestigators setup and removal
Explore token - Explore tokens linked to tile reveal events
Field schema - Only fields Valkyrie reads for each component type; valid tokensize and boolean values
Event semantics - How Valkyrie actually runs events: unreachable event2+ on hidden events, conditions ignored next to vartests, trailing logical operators, spawns wrongly placed in add
Custom images - Referenced image files exist in the scenario folder
Token placement - Tokens and monster placements sit on a tile
Triggers - Every trigger is one Valkyrie fires (no token triggers)
Game flow - The game can reach an ending from its triggers; defeat condition, mythos, items and start marker set up correctly

build_scenario refuses to package a scenario while any rule reports an error.

Development

npm test           # Run all tests
npm run test:watch # Watch mode
npm run lint       # Type check
npm run build      # Compile to dist/
npm run hermes:tools  # Re-export the Hermes plugin tool list after changing tools or the version

Project Structure

.claude-plugin/    Claude Code plugin manifest
plugin.yaml        Hermes Agent plugin manifest (+ __init__.py entry point)
hermes_bridge/     Hermes plugin: MCP stdio client, tool registration, exported tools.json
skills/            9 skill SKILL.md files (Claude Code and Hermes)
agents/            Scenario designer agent
src/
  io/              INI parser/writer, localization CSV, ZIP packager
  model/           ScenarioModel, LocalizationStore, component types
  validation/      Rules + orchestrator
    rules/         Individual validation rule implementations
  tools/           MCP tool implementations
  story/           Storyline graph: outline, Mermaid, HTML
  artwork/         ComfyUI (FLUX.2 [klein]) artwork generation
  narration/       Kokoro text-to-speech, dialog text to speech text
  audio/           Stable Audio 3 sound effects through ComfyUI, FLAC to OGG Vorbis
  resources/       Format documentation resources
  catalogs/        846-entry game content catalog
  diagnostics/     Bug report builder, session trace, ring buffer
  server.ts        MCP server registration
  index.ts         Entry point (stdio transport)
tests/
  fixtures/        ExoticMaterial (reference scenario), MinimalScenario
  io/              IO layer tests
  model/           Model layer tests
  tools/           Tool tests
  validation/      Validation rule tests
  diagnostics/     Diagnostics tests
  golden.test.ts   Round-trip integrity tests
  integration.test.ts  Full pipeline tests

Changes and Roadmap

See CHANGELOG.md for what changed in each release and TODO.md for what is planned next (hybrid semantic search for game content, generated sound effects).

Related Projects

Valkyrie - Scenario builder and player
valkyrie-questdata - Community scenario source data
valkyrie-store - Scenario manifest pipeline

License

MIT

@thijshakkenberg/valkyrie Mom

GitHub Actions

MCP server for AI-assisted Mansions of Madness scenario creation with Valkyrie

Devops Developer Tools

Add to Cursor Add to VS Code Run on PlugMCP

GitHub npm Website

Add to Cursor Add to VS Code Run on PlugMCP

1{2  "mcpServers": {3    "thijshakkenberg-valkyrie-mom-mcp": {4      "command": "npx",5      "args": [6        "-y",7        "@thijshakkenberg/[email protected]"8      ]9    }10  }11}

.cursor/mcp.jsonMCP server

Transport: stdio
Status: Local

Power your agent

Add this server

The publisher's own command. Not a PlugMCP endpoint.

Add to Cursor Add to VS Code Run on PlugMCP

Host a copy with our keys and logs.

Local command

npx -y @thijshakkenberg/[email protected]

Claude Code has no install link for a local command. Copy the command below and run it in a terminal.

shClaude Code

1claude mcp add thijshakkenberg-valkyrie-mom-mcp -- npx -y @thijshakkenberg/valkyrie-mom-mcp@2.6.0

Run in a terminal.

jsonClaude Desktop

1{2  "mcpServers": {3    "thijshakkenberg-valkyrie-mom-mcp": {4      "command": "npx",5      "args": [6        "-y",7        "@thijshakkenberg/[email protected]"8      ]9    }10  }11}

claude_desktop_config.json

Local · npmPublisher installStep-by-step: add this in Claude

Remote URL or a command on your machine? How the two installs differ

Run on PlugMCP

Host a copy with our keys and logs.

A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.

Launch

Server facts

Local

Transport: stdio
Version: 2.6.0
Last checked: 2026-10-28

Stars: —
Tools: —
Uptime: —

Tools

No tool list yet. Remote servers get one after the first health check.

FAQ

Questions

How do I install @thijshakkenberg/valkyrie Mom?

Copy the stdio config for Cursor, Claude Desktop, Claude Code, or VS Code on this page. It uses the publisher's install, not a PlugMCP proxy.

Does @thijshakkenberg/valkyrie Mom need an API key?

No required environment variable is listed on this record.

What transport does @thijshakkenberg/valkyrie Mom use?

@thijshakkenberg/valkyrie Mom runs locally over stdio.

When was @thijshakkenberg/valkyrie Mom last checked?

Last checked 2026-10-28. MCP server for AI-assisted Mansions of Madness scenario creation with Valkyrie

From the publisher

Documentation

valkyrie-mom-mcp

MCP (Model Context Protocol) server and Claude Code plugin for AI-assisted Mansions of Madness 2nd Edition scenario creation with Valkyrie.

What it does

Install

As a Claude Code plugin (recommended)

claude plugin marketplace add thijs-hakkenberg/ValkyrieMCP
claude plugin install valkyrie-mom

This gives you:

MCP server with 25 tools for scenario editing (auto-started)
10 skills: /scenario, /event-patterns, /tile-placement, /variables-and-mythos, /custom-monsters, /ui-and-puzzles, /items-and-distribution, /artwork, /narration, /sound-effects
Scenario designer agent for autonomous scenario creation
5 MCP resources for format documentation

To update to the latest version:

claude plugin marketplace update valkyrie-mom
claude plugin update valkyrie-mom

To uninstall:

claude plugin uninstall valkyrie-mom

As a standalone MCP server (Claude Desktop, other MCP clients)

Add to your MCP client config (e.g., ~/.claude/mcp.json or Claude Desktop settings):

{
  "mcpServers": {
    "valkyrie-mom": {
      "command": "npx",
      "args": ["-y", "@thijshakkenberg/valkyrie-mom-mcp"]
    }
  }
}

This gives you the MCP tools and resources, but not the skills or agent (those require Claude Code).

As a Hermes Agent plugin

Hermes Agent installs the repository as a plugin with every tool and all skills:

hermes plugins install thijs-hakkenberg/ValkyrieMCP --enable

From source

git clone https://github.com/thijs-hakkenberg/ValkyrieMCP.git
cd ValkyrieMCP
npm install
npx tsx src/index.ts   # Run MCP server via stdio

Skills

Skill	Description
`/scenario`	Guided end-to-end scenario creation workflow
`/event-patterns`	Event loops, multi-question dialogues, silent events, token swaps, random events, variable branching
`/tile-placement`	Standard placement chains, multi-entry tiles, naming conventions
`/variables-and-mythos`	Variable system, mythos scaling formula, random generation, hero detection, content pack gating
`/custom-monsters`	Custom activations, evade/horror events, round-based spawn triggering
`/ui-and-puzzles`	Prologues, interactive journals, combination locks, built-in puzzle types
`/items-and-distribution`	Random items, unique items, starting items, inspection events
`/artwork`	Generate pictures with a local ComfyUI (FLUX.2 [klein] 4B) and show them: cover, intro cutscene, handouts, scenes, monsters, tokens, image puzzles
`/narration`	Read story text aloud with a local Kokoro voice: what to narrate, voices, pronunciations, how Valkyrie plays event audio
`/sound-effects`	Generate sound effects with a local ComfyUI (Stable Audio 3): prompts, lengths, stock sound or generated, an effect and narration on one moment

MCP Tools

Lifecycle

Tool	Description
`list_scenarios`	List all scenarios in the Valkyrie editor directory
`create_scenario`	Create a new scenario (defaults to Valkyrie editor dir)
`load_scenario`	Load an existing scenario from a directory
`get_scenario_state`	Get current scenario component/localization summary
`validate_scenario`	Run all validation rules
`save_scenario`	Write the scenario to its folder (edits stay in memory until saved or built)
`build_scenario`	Save and build the `.valkyrie` package with Valkyrie's manifest `.ini` and cover image (default: `Desktop/<Package>/`, like Valkyrie's Create Package)
`set_quest_config`	Set difficulty, play time, investigator count, cover image

Components

Tool	Description
`upsert_event`	Create or update an event
`upsert_tile`	Create or update a tile
`upsert_token`	Create or update a token
`upsert_spawn`	Create or update a monster spawn
`upsert_item`	Create or update an item
`upsert_puzzle`	Create or update a puzzle
`upsert_ui`	Create or update a UI element
`upsert_custom_monster`	Create or update a custom monster
`upsert_mplace`	Create or update a monster placement
`upsert_activation`	Create or update a custom monster activation
`delete_component`	Delete a component with cascade reference cleanup
`set_localization`	Set localization key-value pairs

Map

Tool	Description
`get_map_ascii`	Describe the board: tile areas, doors and where they lead (with explore-token spots), tokens and their tile, ASCII sketch
`render_map`	Render the board as a PNG with the real tile artwork (from Valkyrie's imported data) or a schematic, tokens numbered
`suggest_tile_layout`	Suggest coordinates for large (7x7) tiles in linear, L-shape, or hub-spoke layouts
`place_tile_relative`	Position and rotation for a new tile against an existing one, with a door lined up

Story

Tool	Description
`story_graph`	Project the storyline as a graph: a condensed text outline (buttons, conditions, effects, placed tokens, puzzles, monster events, endings, never-reached events), Mermaid, or an HTML page with the rendered flowchart

Artwork

Tool	Description
`artwork_status`	Check a local ComfyUI server and the FLUX.2 [klein] 4B model files; prints comfy-cli setup and download commands for anything missing
`generate_artwork`	Generate an image (4 steps, CFG 1, size presets per use) and save it into the scenario folder, with a preview

Artwork is optional and runs entirely on your machine. Setup with comfy-cli:

pip install comfy-cli && comfy install
comfy model download --url https://huggingface.co/Comfy-Org/flux2-klein-4B/resolve/main/split_files/diffusion_models/flux-2-klein-4b.safetensors --relative-path models/diffusion_models
comfy model download --url https://huggingface.co/Comfy-Org/flux2-klein-4B/resolve/main/split_files/text_encoders/qwen_3_4b.safetensors --relative-path models/text_encoders
comfy model download --url https://huggingface.co/Comfy-Org/flux2-dev/resolve/main/split_files/vae/flux2-vae.safetensors --relative-path models/vae
comfy launch --background

Narration

Tool	Description
`narration_status`	Check the local text-to-speech engine and model, list the voices; `install=true` installs the engine
`generate_narration`	Speak components' dialog text with Kokoro-82M into OGG clips in the scenario folder (`audio/narration/<Event>.ogg`) and set their `audio=`. Speaks only the italic story text by default, expands `{qst:}`, turns icons into words, takes respellings for names

Sound effects

Tool	Description
`sound_status`	Check a local ComfyUI server, the Stable Audio 3 Small SFX model files and the `--fp32-vae` flag; prints setup and download commands for anything missing
`generate_sound_effect`	Generate a sound from a description (8 steps, about 1 s per clip) into an OGG clip in the scenario folder (`audio/sfx/<Event>.ogg`) and set the events' `audio=`. Peak-normalised, silent tail cut; narration on an event is kept unless `assign=true`

Sound effects are optional and run on the same ComfyUI as artwork, with Stable Audio 3 Small SFX (Stability AI Community License), small enough for the CPU:

comfy model download --url https://huggingface.co/Comfy-Org/stable-audio-3/resolve/main/checkpoints/stable_audio_3_small_sfx.safetensors --relative-path models/checkpoints
comfy model download --url https://huggingface.co/Comfy-Org/stable-audio-3/resolve/main/text_encoders/t5gemma_b_b_ul2.safetensors --relative-path models/text_encoders
comfy launch --background -- --fp32-vae

Reference

Tool	Description
`search_game_content`	Search game content catalogs (846 entries across tiles, monsters, items, audio)

Diagnostics

Tool	Description
`export_bug_report`	Generate a ZIP bug report with session trace, scenario files, validation results, and Valkyrie logs

MCP Resources

Resource	URI
Event format docs	`valkyrie://format/events`
Localization format docs	`valkyrie://format/localization`
Component format docs	`valkyrie://format/components`
Pattern reference	`valkyrie://format/patterns`
Current scenario state	`valkyrie://scenario/current`

MCP Prompts

Prompt	Description
`create-scenario`	Guided workflow for creating a new scenario
`review-scenario`	Analyze a scenario for balance and completeness

Valkyrie Editor Paths

The server auto-detects where Valkyrie stores editor scenarios:

Platform	Path
macOS / Linux	`~/.config/Valkyrie/MoM/Editor/`
Windows	`%APPDATA%\Valkyrie\MoM\Editor\`

Scenario File Format

A scenario is a directory containing:

quest.ini - Quest config and file listings
events.ini - Event components (triggers, buttons, branching)
tiles.ini - Map tile placements
tokens.ini - Search, explore, interact, and wall tokens
spawns.ini - Monster spawn configurations
items.ini - Quest items
ui.ini - UI elements (backgrounds, etc.)
other.ini - Puzzles and misc components
Localization.English.txt - CSV localization (key,value pairs)

Built scenarios are ZIP archives with a .valkyrie extension.

Validation Rules

The server validates scenarios against 18 rule categories, checked against Valkyrie 3.28 (quest format 21):

Unique names - No duplicate component names
Required fields - Tiles have side or customImage, displayed events have buttons
Cross-references - All referenced components exist; remove #keywords are valid
Event graph - EventStart trigger exists, no unreachable/dead-end events
Event flow - No endless loops of hidden events
Localization completeness - Event text, button labels, quest metadata
Format rules - Valid format version (4-21) and high enough for the features used, type=MoM, tile rotations
Catalog references - Tile sides, monster names, items match game content
Tile connectivity - Tiles don't overlap, touch at least one other tile, and share a lined-up door or open edge (door data measured from the tile artwork)
Mythos structure - Proper mythos trigger configuration
Investigator token - TokenInvestigators setup and removal
Explore token - Explore tokens linked to tile reveal events
Field schema - Only fields Valkyrie reads for each component type; valid tokensize and boolean values
Event semantics - How Valkyrie actually runs events: unreachable event2+ on hidden events, conditions ignored next to vartests, trailing logical operators, spawns wrongly placed in add
Custom images - Referenced image files exist in the scenario folder
Token placement - Tokens and monster placements sit on a tile
Triggers - Every trigger is one Valkyrie fires (no token triggers)
Game flow - The game can reach an ending from its triggers; defeat condition, mythos, items and start marker set up correctly

build_scenario refuses to package a scenario while any rule reports an error.

Development

npm test           # Run all tests
npm run test:watch # Watch mode
npm run lint       # Type check
npm run build      # Compile to dist/
npm run hermes:tools  # Re-export the Hermes plugin tool list after changing tools or the version

Project Structure

.claude-plugin/    Claude Code plugin manifest
plugin.yaml        Hermes Agent plugin manifest (+ __init__.py entry point)
hermes_bridge/     Hermes plugin: MCP stdio client, tool registration, exported tools.json
skills/            9 skill SKILL.md files (Claude Code and Hermes)
agents/            Scenario designer agent
src/
  io/              INI parser/writer, localization CSV, ZIP packager
  model/           ScenarioModel, LocalizationStore, component types
  validation/      Rules + orchestrator
    rules/         Individual validation rule implementations
  tools/           MCP tool implementations
  story/           Storyline graph: outline, Mermaid, HTML
  artwork/         ComfyUI (FLUX.2 [klein]) artwork generation
  narration/       Kokoro text-to-speech, dialog text to speech text
  audio/           Stable Audio 3 sound effects through ComfyUI, FLAC to OGG Vorbis
  resources/       Format documentation resources
  catalogs/        846-entry game content catalog
  diagnostics/     Bug report builder, session trace, ring buffer
  server.ts        MCP server registration
  index.ts         Entry point (stdio transport)
tests/
  fixtures/        ExoticMaterial (reference scenario), MinimalScenario
  io/              IO layer tests
  model/           Model layer tests
  tools/           Tool tests
  validation/      Validation rule tests
  diagnostics/     Diagnostics tests
  golden.test.ts   Round-trip integrity tests
  integration.test.ts  Full pipeline tests

Changes and Roadmap

See CHANGELOG.md for what changed in each release and TODO.md for what is planned next (hybrid semantic search for game content, generated sound effects).

Related Projects

Valkyrie - Scenario builder and player
valkyrie-questdata - Community scenario source data
valkyrie-store - Scenario manifest pipeline

License

MIT