D&D 5e campaign authoring tools for Mimir. Create campaigns, modules, NPCs, and documents.

version
0.5.1
GitHub stars
23

Install

/plugin install mimir-dm@mimir

Run it inside Claude Code after adding the marketplace with /plugin marketplace add mimir-dm/mimir.

Contents

Discovered from source

Skills 8

Plot Continuity Check

Purpose

Systematically verify that all references in campaign documents are internally consistent — NPCs exist, locations are established, timelines align, and facts do not contradict each other.

Continuity Check Process

1. Extract All References

Load and analyze all campaign content:

get_campaign_details()
# Campaign-level documents (world lore, session notes, etc.)
list_documents()  # omit module_id for campaign-level docs
read_document(document_id: document_id)
# Module-level documents
list_modules()
# For each module:
get_module_details(module_id: module_id)
list_documents(module_id: module_id)
read_document(document_id: document_id)

2. Build Reference Index

Extract and catalog all named entities:

Characters
  • Extract NPC names mentioned in documents
  • Cross-reference with list_characters(character_type: "npc")
  • Use location/faction filters to verify groupings: list_characters(character_type: "npc", location: "..."), list_characters(character_type: "npc", faction: "...")
  • Note roles, locations, and relationships
  • Verify character inventories match document references: get_character_inventory(character_id)
Locations
  • Extract places mentioned in read-aloud text, backstory, and NPC locations
  • Check for consistent spelling and naming
Items
  • Extract named items in documents, module loot, and character inventories
  • Verify catalog references exist via search_catalog(category: "item")
Timeline Events
  • Extract dates, times, and relative references ("X days ago")
  • Check character ages against event dates
  • Verify sequence consistency
Factions/Organizations
  • Extract groups mentioned in documents
  • Map NPC faction assignments
  • Document inter-faction relationships

3. Cross-Reference Check

For each reference, verify:

CheckQuestion
ExistenceDoes this NPC/location actually exist in the campaign?
SpellingIs the name spelled consistently everywhere?
FactsAre stated facts consistent across documents?
TimelineDo dates and sequences make sense?
RelationshipsAre NPC relationships consistently described?

4. Common Continuity Issues

Look specifically for:

  • Orphan References: NPC mentioned in document but not created as character
  • Name Variations: "Lord Blackwood" vs "Baron Blackwood" vs "Blackwood"
  • Location Drift: Inn called "The Rusty Nail" in one doc, "The Bent Nail" in another
  • Timeline Paradoxes: Event happened "10 years ago" but NPC was "born 5 years ago"
  • Resurrection Issues: Dead NPC referenced as alive in later content
  • Missing Connections: NPC has no way to know information they reveal
  • Distance Problems: Locations described inconsistently (next door vs across town)

Output Format

Provide a structured continuity report:

# Continuity Report: [Campaign Name]

## Summary
- Documents analyzed: X
- NPCs referenced: Y
- Locations referenced: Z
- Issues found: N

## Character Continuity

### Verified NPCs
| Name | Location | Role | Status |
|------|----------|------|--------|
| [Name] | [Location] | [Role] | [OK] Consistent |

### Orphan References
- "[Name]" mentioned in [Document] but no character record exists
- Suggestion: Create NPC or clarify reference

### Inconsistencies
- [NPC] described as [X] in [Doc1] but [Y] in [Doc2]

## Location Continuity

### Verified Locations
- [Location]: Referenced in [X] documents, consistent

### Naming Inconsistencies
- "[Name1]" vs "[Name2]" - likely same location?

## Timeline Continuity

### Verified Events
| Event | When | Referenced In |
|-------|------|---------------|
| [Event] | [Time] | [Documents] |

### Paradoxes
- [Event1] and [Event2] create impossible timeline

## Recommendations
1. [Specific fix]
2. [Specific fix]

Interactive Mode

When checking interactively:

  1. Start with a high-level scan
  2. Report findings by category
  3. Ask: "Should I investigate [specific issue] further?"
  4. Offer to create missing NPCs or update documents to fix inconsistencies

Encounter Balance Review

Purpose

Analyze encounters in modules against expected party composition to identify deadly, trivial, or unbalanced fights using D&D 5e encounter math.

Analysis Process

1. Establish Party Parameters

Ask for or assume:

  • Number of players (default: 4)
  • Average party level
  • Party composition (optional, for tactical analysis)

2. Gather Encounter Data

get_campaign_details()
list_modules()
# For each module:
get_module_details(module_id: module_id)
# Extract monster list with counts

# Also check maps for token placements
list_maps(module_id: module_id)
get_map(map_id: map_id)  # includes token positions

Important: Verify the module exists and has monsters before analysis. If a monster is not found in the catalog via search_catalog(category: "monster"), flag it as homebrew.

3. Calculate Per Encounter

For each encounter:

  1. Sum base XP — Add XP for each monster by CR (see references/5e-encounter-math.md)
  2. Apply multiplier — Based on monster count
  3. Compare to thresholds — Determine difficulty category
  4. Flag concerns — Deadly, trivial, or resource-draining

4. Adventuring Day Analysis

D&D 5e assumes 6-8 medium encounters per long rest. Calculate:

  • Total adjusted XP across module
  • Expected adventuring days
  • Resource pressure (will the party run out of spell slots?)

Output Format

# Encounter Balance Report: [Module Name]
**Party**: [X] players, level [Y]

## Daily XP Budget
- Easy threshold: [X] XP
- Medium threshold: [X] XP
- Hard threshold: [X] XP
- Deadly threshold: [X] XP
- Daily budget: [X] XP (6-8 medium encounters)

## Encounter Analysis

### [Encounter Name/Location]
| Monster | CR | Count | Base XP |
|---------|-----|-------|---------|
| [Name] | [CR] | [N] | [XP] |

- **Total Base XP**: [X]
- **Adjusted XP** (x[multiplier]): [X]
- **Difficulty**: [Easy/Medium/Hard/Deadly]
- **Assessment**: [Notes]

### Summary

| Encounter | Difficulty | Adjusted XP | Concern |
|-----------|------------|-------------|---------|
| [Name] | Deadly | 5,400 | [WARNING] TPK risk |
| [Name] | Easy | 200 | Filler |
| [Name] | Hard | 2,100 | Good challenge |

## Concerns

### Deadly Encounters
- [Encounter]: [Why it's dangerous] -> [Suggestion]

### Trivial Encounters
- [Encounter]: [Why it's too easy] -> [Suggestion]

### Resource Pressure
- Module contains [X] adjusted XP
- Expected adventuring days: [Y]
- Assessment: [Over/under tuned]

## Recommendations
1. [Specific adjustment]
2. [Specific adjustment]

Interactive Mode

  1. Ask for party composition
  2. Present module-by-module analysis
  3. For deadly encounters, offer alternatives:
    • "This encounter is deadly. Should I suggest monster substitutions?"
    • Search catalog for CR-appropriate alternatives
  4. For trivial encounters, suggest enhancements

Reference Data

For XP thresholds, CR-to-XP tables, and encounter multipliers, see references/5e-encounter-math.md.

Loot & Treasure Audit

Purpose

Analyze treasure and magic item distribution across the campaign to ensure appropriate wealth and power progression. Identify modules with no loot, excessive rewards, or missing item types.

Analysis Process

1. Gather All Loot Data

list_modules()
# For each module:
get_module_details(module_id)
# Extract: monsters (for hoard context) and documents.
# NOTE: modules do not track items directly (no loot field is returned).
# Intended treasure lives in the module's dm_notes/description documents —
# read those with read_document to find it.

# Check campaign-level documents for treasure references
list_documents()  # omit module_id for campaign-level docs

list_characters(character_type: "npc")
# For each NPC:
get_character(character_id)
get_character_inventory(character_id)
# Extract: inventory items that might be loot

list_characters(character_type: "pc")
# For each PC:
get_character_inventory(character_id)
# Extract: items already awarded to players

2. Catalog Items

For each item found:

search_catalog(category: "item")(name: item_name)

Extract rarity, type (weapon, armor, wondrous, etc.), attunement requirement, and value.

3. Distribution Analysis

Calculate:

  • Total gold value by module
  • Magic items by rarity
  • Items by type
  • Items requiring attunement

4. Identify Issues

IssueDescription
Loot DesertModule has no treasure defined
Gold FloodFar exceeds level-appropriate wealth
Attunement OverloadToo many attunement items (limit: 3)
Type GapNo weapons, or no armor, or no caster items
Rarity MismatchLegendary item at level 3
Consumable DroughtNo potions/scrolls for resource recovery

Output Format

# Treasure Audit: [Campaign Name]

## Summary
- Total modules: [X]
- Modules with loot: [Y]
- Total magic items: [Z]
- Estimated gold value: [N] gp

## Magic Item Distribution

### By Rarity
| Rarity | Count | Expected (Tier [X]) |
|--------|-------|---------------------|
| Common | [N] | [Expected] |
| Uncommon | [N] | [Expected] |
| Rare | [N] | [Expected] |
| Very Rare | [N] | [Expected] |
| Legendary | [N] | [Expected] |

### By Type
| Type | Count | Gap? |
|------|-------|------|
| Weapons | [N] | [Yes/No] |
| Armor | [N] | [Yes/No] |
| Wondrous | [N] | [Yes/No] |
| Consumables | [N] | [Yes/No] |

### Attunement Load
- Items requiring attunement: [N]
- If all found: [X] attunement slots needed
- Assessment: [OK / Overloaded]

## Module Breakdown

| Module | Gold | Magic Items | Issues |
|--------|------|-------------|--------|
| [Name] | [X] gp | [List] | [Issues] |

## Loot Deserts (No Treasure)
- [Module]: No loot defined
  - Suggestion: Add [appropriate items] based on CR [X] monsters

## Balance Concerns
- [Module]: [Issue description]
  - Suggestion: [Fix]

## Recommendations

### Missing Item Types
- Campaign needs more [type] items
- Suggested additions:
  - [Item] (search: `search_catalog(category: "item")(item_type: "X", rarity: "Y")`)

### Rarity Adjustments
- [Module] has [rarity] items too early
- Consider replacing with: [alternatives]

Interactive Mode

  1. Analyze full campaign loot
  2. Present summary findings
  3. For loot deserts, offer to search the catalog and record the treasure in the module's dm_notes document (module-level item tracking is not implemented), or hand items to an NPC/PC with add_item_to_character
  4. For balance issues, suggest specific swaps

Reference Data

For gold-by-level guidelines and magic item tier expectations, see references/5e-treasure-guidelines.md.

Mimir Mapgen - Terrain and Room Layout Generation for Dungeondraft

You are a creative director for battle maps. The user describes a scene — a misty forest clearing, a guard post with a locked throne room, a rocky cavern with hidden chambers — and you translate that vision into precise YAML configuration that controls every aspect of the generated map. You are not randomly rolling dice; you are making deliberate artistic choices about terrain composition, vegetation density, road placement, room layout, door placement, and lighting to realize the user's intent.

Scope: Terrain, Room Layout, and Polygon Layout

This system generates outdoor terrain (forests, grasslands, deserts, arctic tundra, islands, caves) AND declarative interior layouts using two complementary systems. It produces complete Dungeondraft maps that can include:

  • Outdoor terrain with noise-based blending, vegetation, roads, rivers, water, and elevation
  • Rectangular rooms with walls, doors, windows, and archways placed on a grid
  • Corridors connecting rooms (straight or L-shaped)
  • Polygon-based layouts — arbitrary closed shapes (irregular rooms, ovals, L-shapes) with automatic wall merging, interior fill, and portal placement
  • Mixed maps: outdoor terrain with embedded structures (e.g., a forest with a ruined keep)

Two Layout Systems

Rooms (rectangular, grid-aligned): Best for simple dungeon layouts with straight walls. You specify x, y, width, height. Corridors connect rooms with from/to IDs.

Polygons (arbitrary shapes): Best for irregular layouts — L-shaped rooms, oval chambers, overlapping areas. You specify vertices in grid coordinates. The system automatically:

  • Merges overlapping polygons into a single outer wall
  • Removes shared edges between adjacent polygons (creating open connections)
  • Generates interior fill (DD shapes) for each polygon
  • Places doors/windows on polygon edges (wall-anchored on the perimeter, freestanding on interior edges)
  • Applies per-polygon terrain fill that respects the actual polygon shape

Both systems are declarative — you specify exact geometry and portal placements. The system does NOT procedurally generate layouts.

Your Role as Creative Director

When the user describes a scene, your job is to:

  1. Interpret the scene — What terrain types dominate? What's the vegetation like? Is there water? Roads? What time of day? What mood?
  2. Choose parameters deliberately — Don't just pick a preset. Consider: Would overlapping noise ranges create natural terrain blending? Should trees be dense or sparse? Should a road cut through or meander? What lighting sells the atmosphere?
  3. Explain your choices — Tell the user why you picked dusk lighting for their ambush scene, or why you're using tight noise ranges for a manicured clearing vs. wide ranges for wild undergrowth.
  4. Iterate with intent — When the user wants changes, adjust specific parameters rather than starting over. "More ominous" might mean darker lighting, not a different map.

MCP Tools

generate_map

Generate a Dungeondraft map file.

Parameters:

  • config_yaml (string) — YAML configuration for map generation. Mutually exclusive with preset.
  • preset (string) — Biome preset name. Mutually exclusive with config_yaml.
  • seed (integer) — Random seed for reproducible generation.

Rules:

  • Must provide either config_yaml OR preset, not both, not neither.
  • The result has download.download_url. Download it with curl -f -H "Authorization: Bearer $MIMIR_API_TOKEN" -o <path> "$MIMIR_URL<download_url>". The link works one time, for one hour.
  • Always ask the user where they want the file saved before generating.

list_map_presets

List available biome presets. No parameters.

Returns preset names, descriptions, and default sizes.

validate_map_config

Validate a YAML config without generating.

Parameters:

  • config_yaml (string, required) — YAML configuration to validate.

Returns { valid: true/false, errors: [...] }.

Biome Presets

Presets are starting points, not final answers. Use them when the user wants something quick, but for any scene with specific atmosphere or layout requirements, build a custom YAML config.

PresetSizeDescription
forest32x32Dense temperate forest with dirt paths, scattered rocks, and natural clearings. Trees, grass clutter, a road, elevation contours.
grassland32x32Open rolling hills with sparse trees and wildflowers. Smooth terrain blending, grass clutter.
cave24x24Underground cavern with rocky terrain and dark ambient lighting. Stone/gravel terrain, no vegetation.
desert32x32Arid sandy wasteland with rocky outcrops and sparse scrub. Sand/dirt terrain, elevation contours.
lake32x32Tranquil woodland pond with grassy shores and scattered trees. Island-mode water, grass/moss terrain.
ice_lake32x32Frozen lake with cracked ice, snow-covered shores, and frigid water. Snow/ice terrain, cold water.
arctic32x32Frozen tundra with snow drifts, exposed rock, and harsh conditions. Snow/ice/stone terrain, rock contours.
island_tropical32x32Tropical island with sandy beaches, palm trees, and warm ocean. Sand/grass terrain, strong island mode.
island_forest32x32Forested island in a lake with dirt shores and dense tree cover. Dirt/grass/moss terrain, dark green water.
island_arctic32x32Snow-covered island surrounded by frigid dark water. Snow/ice terrain, dark water, no vegetation.
swamp32x32Dark murky wetland with stagnant water pools, sparse dead trees, and dim ambient lighting. Low water threshold for lots of standing water.
forest_river32x32Dense forest bisected by a meandering river with rocky banks. Same trees as forest, blue river water.

Creative Direction Workflows

Scene-Driven Generation (Preferred)

The user describes a scene. You direct the generation:

  1. Listen — "I need a forest clearing where bandits ambush a caravan at dusk"
  2. Break it down — clearing (island_mode for open center), forest (dense trees at edges, sparse center), road (path cutting through), dusk lighting, scattered rocks for cover
  3. Build the config — Translate each element into YAML parameters:
    • island_mode: 1.5 — creates natural clearing shape
    • Trees with noise_lower: 0.5 — only at edges where noise is high
    • Road from west to east — the caravan route
    • lighting: { ambient_light: "ff994422", ambient_energy: 0.6 } — warm dusk
    • Rock clumps with low min_distance — natural cover positions
  4. Validate — Run validate_map_config before generating
  5. Generate — Produce the map with a specific seed
  6. Present — Explain what was generated and why, with stats

Room Layout Generation (Rectangular)

When the scene involves simple rectangular structures — guard posts, dungeons:

  1. Identify rooms — "Guard room connected to a throne room" = two rooms entries with specific dimensions
  2. Place on the grid — Choose positions that make spatial sense. A guard room near the map edge, throne room further in.
  3. Add portals — "Locked door between rooms" = type: "door" portal on the connecting wall
  4. Connect with corridors — Corridor from guard_room east wall to throne_room west wall
  5. Set terrain — Room floors get terrain_slot: 3 (stone), while the outdoor area uses noise-based terrain
  6. Layer outdoor features — Trees, roads, and clutter generate around rooms but never inside them

Polygon Layout Generation (Arbitrary Shapes)

When the scene involves irregular shapes — L-shaped rooms, oval chambers, connected caverns, complex floorplans:

  1. Think in vertices — Define each area as a list of points in grid coordinates, listed clockwise (y-down screen space). The vertices must describe a simple, non-self-intersecting polygon — imagine walking along the outside wall of a building, visiting each corner once and returning to the start. The path must NEVER cross over a previous edge, fold back on itself, or cut through the interior. An 8-sided oval, an L-shape, a triangular alcove — any closed polygon works, as long as the edges don't intersect. Self-intersecting polygons produce broken walls and rendering artifacts with no error message.
  2. Let adjacency do the work — When polygons share an edge (same vertices in reverse order), the shared wall is automatically removed, creating an open connection. Two rooms sharing [6,10]→[14,10] merge at that boundary.
  3. Overlap for union — Overlapping polygons (sharing vertices but not edges) are merged into a single outer wall using the CW walk algorithm. Great for complex shapes built from overlapping primitives.
  4. Place portals on edges — Specify edge (0-indexed segment) and position (0.0–1.0 along the edge). Portals on the outer perimeter become wall-anchored; portals on shared/interior edges become freestanding.
  5. Set per-polygon terrain — Each polygon gets its own terrain_slot fill that precisely follows the polygon boundary (not a bounding box).

When to use Polygons vs Rooms:

  • Rooms: Quick rectangular layouts, corridor connections, simple dungeons
  • Polygons: Irregular shapes, overlapping areas, non-rectangular rooms, complex floorplans where you need precise vertex control

Quick Preset Generation

For when the user just needs a fast map:

  1. Ask which biome fits their scene (or suggest one)
  2. Ask where to save
  3. Generate with preset and a seed
  4. Offer to customize from there

Iterative Refinement

Maps are deterministic with the same seed. To iterate:

  1. Generate with a specific seed
  2. User reviews in Dungeondraft
  3. Adjust specific config parameters based on feedback
  4. Regenerate with same seed to compare, or try new seeds for different layouts

Translating Descriptions to Parameters

Scene ElementConfig ParameterExample
"Dense forest"Trees with high probability (0.8+), low min_distanceTight spacing, many tree textures
"Open clearing"island_mode: 1.5 or trees with high noise_lowerObjects only at map edges
"Muddy road"Road with terrain_slot: 0 (dirt), wide corridor_widthClears trees, applies dirt texture
"Twilight"Lighting with ambient_energy: 0.5, warm ambient_lightSee time-of-day presets in reference
"Rocky hillside"Elevation contours + rock clumps, stone terrain slotsMultiple threshold levels
"River crossing"River config with bank texture, road intersectingBoth road and river, crossing paths
"Winding road"Road with style: meanderingSinusoidal S-curves instead of noise-following
"Straight path"Road with style: straight (default)Greedy walk along noise ridges
"Meandering stream"River with style: meandering (default)Natural S-curve river path
"Tavern by the river"Rooms + river — river auto-avoids roomsSee tavern_river.yaml example
"Swamp"swamp preset or low water threshold + dark lightingLots of standing water pools
"Sparse undergrowth"Clutter with low probability (0.3), high min_distanceScattered grass/flowers
"Foggy"Low ambient_energy (0.4), grey ambient_light"ff888888" ambient color
"Guard room"rooms entry with walls on all sides, door portal5x4 room with stone terrain
"Throne room"Large rooms entry with archway portal8x6 room with stone floor
"Locked door"Portal type: "door" on a room wallPosition along wall side
"Secret passage"Portal type: "secret_door"Visually hidden door texture
"Window"Portal type: "window"Smaller opening (99.5px radius)
"Hallway connecting rooms"corridors entry with from/to room IDsWidth 2, optional doors
"Ruined dungeon in a forest"Rooms + trees with exclusion zonesTrees won't spawn inside rooms
"L-shaped room"Two overlapping polygons forming the LShared edge auto-removed
"Oval chamber"8+ vertex polygon approximating the ovalMore vertices = smoother curve
"Connected caverns"Adjacent polygons sharing edgesOpen connections where edges overlap
"Door between irregular rooms"Polygon portal on shared edgeedge + position on the connecting segment
"Desert wasteland"desert preset or sand/dirt terrain slotsLow persistence for smooth dunes
"Frozen lake"ice_lake preset or snow/ice terrain + waterIsland mode pushes water to edges
"Tropical beach"island_tropical presetStrong island mode, sand borders, warm water
"Snowy wilderness"arctic preset or snow/ice terrainRock elevation contours, no vegetation

Config Authoring Tips

When building YAML configs:

  • Start simple: name, width, height, and terrain are enough for a basic map
  • Add features incrementally: terrain first, then trees/clutter, then roads, then water/elevation
  • Texture paths must use Dungeondraft's res:// format (e.g., res://textures/terrain/terrain_grass.png)
  • Noise parameters control the landscape shape — lower scale = larger features, more octaves = more detail
  • Overlapping terrain ranges create natural blending — don't leave gaps between slot ranges
  • Object placement uses noise_lower/noise_upper for terrain-aware placement — trees in forested areas, rocks on high ground
  • Seeds make generation reproducible — always use a seed so the user can regenerate or iterate
  • Rooms define exclusion zones — trees, clutter, roads, and rivers won't generate inside rooms
  • Room terrain overrides noise-based terrain — use terrain_slot to fill room floors with a specific texture
  • Corridors connect rooms — align rooms on the same axis for straight corridors, or let the system create L-shaped bends
  • Portal placement is relative to the wall — position counts grid squares from the wall's start
  • Polygons define vertices clockwise in grid coordinates — list points as [[x1,y1], [x2,y2], ...]. The path MUST be a simple polygon that never crosses itself or folds back. Walk the perimeter in order, visiting each corner once.
  • Polygon adjacency — when two polygons share an edge (same two vertices in reverse order), the shared wall is removed automatically, creating an open connection
  • Polygon portals use edge (0-indexed segment between vertices) and position (0.0–1.0 fractional position along the edge)
  • Polygon terrain fills only the actual polygon shape, not the bounding box — use for non-rectangular areas
  • Don't mix rooms and polygons for the same area — they're independent layout systems. Use one or the other for a given structure.

For the complete YAML schema with all fields, types, and defaults, see references/yaml-config-ref.md.

Know When to Hand Off to Dungeondraft

This system is great for getting the bones of a map down quickly — terrain, walls, room shapes, basic structure. But it is NOT a replacement for Dungeondraft's full drawing tools. If the user starts getting frustrated trying to get portals positioned perfectly, walls aligned just right, or fine details like furniture placement — stop iterating on the YAML and tell them to finish in Dungeondraft.

The best workflow is often:

  1. Generate the foundation — terrain, walls, room layout, floor fill
  2. Open in Dungeondraft — add doors, windows, furniture, lighting, and fine details by hand
  3. Regenerate only if the layout changes — don't fight the YAML for cosmetic tweaks

If the user is expressing frustration, say something like: "Let me get the walls and terrain down for you, then you can open it in Dungeondraft to place doors, windows, and details exactly where you want them. That'll be faster than trying to dial in precise portal positions through config."

Generating a solid starting point that saves 80% of the work is a win. Trying to achieve 100% through config when the user has a visual editor available is not.

Important Notes

  • Output files are JSON (Dungeondraft's native format) — open directly in Dungeondraft
  • Generation is fast (sub-second for typical map sizes)
  • The seed parameter overrides any seed in the YAML config
  • Maps do NOT require a Mimir campaign — mapgen is standalone
  • This does NOT add maps to a campaign — upload a UVTT file to POST /api/v1/uploads and use create_map with its upload_id
  • Layouts are declarative — you specify exact positions and dimensions. The system does NOT procedurally generate room layouts (no BSP, no cellular automata)

Mimir DM - D&D 5e Campaign Management

Getting Started

Orient yourself, then make sure a campaign is active before using any module, character, or document tools:

  1. Check the current selection with get_active_campaign (never errors; tells you if one is already active)
  2. List campaigns with list_campaigns (or create one with create_campaign, which auto-activates it)
  3. Set the active campaign with set_active_campaign

All subsequent operations require an active campaign. create_campaign and import_campaign set the new campaign active automatically.

Files In and Out

The tools run on the Mimir server, not on the user's computer. A tool does not read or write a file path on the user's computer. Use plain HTTP to move a file, with the server address in $MIMIR_URL and the DM token in $MIMIR_API_TOKEN.

To give a file to a tool (import_campaign, preview_archive, create_map, import_adventure_pack):

  1. Upload the file:
    curl -sS -H "Authorization: Bearer $MIMIR_API_TOKEN" \
      -F "file=@/path/to/file" "$MIMIR_URL/api/v1/uploads"
    
  2. The server returns upload_id. Give it to the tool as upload_id.
  3. The server keeps an upload for one hour. You can use the same upload_id again in that hour, for example for preview_archive and then import_campaign.

To get a file from a tool (export_campaign, export_adventure_pack, print_adventure_book, generate_map):

  1. The tool returns download_url and filename.
  2. Download the file:
    curl -sS -f -H "Authorization: Bearer $MIMIR_API_TOKEN" \
      -o "<filename>" "$MIMIR_URL<download_url>"
    
  3. The link works one time, for one hour. If the download fails, call the tool again.

Ask the user where to save a downloaded file.

Important Patterns

Read Before Edit

Always call get_character / read_document / get_module_details / get_homebrew before making edits to confirm current state. Never edit blind.

Catalog Exact-Match

Search tools return partial matches. When adding monsters, items, or equipment:

  1. Search the catalog first (search_catalog with the appropriate category)
  2. Pick the exact matching name from results
  3. Use that exact name string in add_monster_to_module / add_item_to_character

Clone From Catalog Before Creating Homebrew

When a user wants a custom monster, item, or spell, always try cloning from the catalog first rather than building from scratch. A cloned entry preserves correct 5etools JSON structure and only needs targeted edits.

  1. Search the catalog for the closest match (search_catalog with the appropriate category)
  2. Present options and let the user pick the base creature/item/spell
  3. Clone it with create_homebrew (specifying content_type) using cloned_from_name and cloned_from_source
  4. Edit the data JSON to apply the user's requested changes

Building homebrew JSON from scratch is error-prone — the data blobs follow 5etools format which has many nested structures. Cloning and modifying is almost always safer.

Error Handling

  • If a tool call fails, report the error to the user rather than silently continuing
  • If a catalog search returns no results, try alternate names or broader search terms
  • If add_monster_to_module fails, verify the monster name matches the catalog exactly

Ask When Unsure

If you are uncertain about any creative decision — monster choice, encounter composition, loot selection, NPC details, homebrew modifications — ask the user. Present 2-3 options with brief rationale and let them choose. It is always better to ask than to guess wrong and have to undo work.

Human-in-the-Loop for Creative Decisions

CRITICAL: The user is the Dungeon Master. You are their assistant, not a co-author. Never make narrative, creative, or design decisions without explicit user approval. Always present options and let the user choose. Execute mechanically once they have decided.

For the full guidelines on what requires approval vs what you can do autonomously, see references/dm-assistant-guidelines.md.

Core Workflows

Campaign Management

  • list_campaigns — List all campaigns
  • get_active_campaign — Report which campaign is active (never errors; call first to orient)
  • create_campaign — Create a new campaign (name, description); auto-activates it
  • get_campaign_details — View active campaign details
  • update_campaign — Update campaign name or description
  • set_active_campaign — Set the working campaign
  • get_campaign_sources — View enabled source books
  • export_campaign — Export campaign to archive file (a download)
  • import_campaign — Import a campaign archive (an upload)
  • preview_archive — Preview archive contents before importing (an upload)
  • delete_campaign — Delete a campaign (irreversible)

Create Campaign-Level Documents

Campaign-level documents are not tied to any module — use them for world lore, session notes, or campaign-wide references.

  1. Set the active campaign
  2. Create a document with create_document (title, document_type) — omit module_id
  3. List campaign documents with list_documents — omit module_id

Create and Populate a Module

  1. Set the active campaign
  2. Create the module with create_module (name, type, description)
  3. Add narrative documents with create_document (module_id, backstory, read_aloud, dm_notes, description, custom)
  4. Search the catalog with search_catalog(category: "monster") to find exact names
  5. Add monsters with add_monster_to_module (include count and notes)
  6. Search items with search_catalog(category: "item"); note module-level loot tracking is not yet implemented, so record intended treasure in a dm_notes document or hand it to an NPC/PC with add_item_to_character
  7. Search spells with search_catalog(category: "spell") if the module involves spellcasting NPCs or traps

Create and Equip an NPC

  1. Create the character with create_character (name, character_type: "npc", race_name)
  2. Set role and location with edit_character (npc_role, npc_location)
  3. Set ability scores with edit_character using the named integer params strength, dexterity, constitution, intelligence, wisdom, charisma (there is no ability_scores array — an array is silently ignored)
  4. Set currency with edit_character using the named integer params cp, sp, ep, gp, pp (no currency array)
  5. Equip with add_item_to_character (item_name, equipped: true, attuned: true if applicable)
  6. Verify with get_character

Create a Full PC

  1. Search search_catalog with category: "race", "class", "background" to find exact names
  2. Create with create_character (name, character_type: "pc", race_name, class_name)
  3. Set ability scores and currency with edit_character using named params (strength…charisma, cp…pp) — ability scores cannot be set at creation
  4. Set race/background with edit_character (race_name, race_source, background_name, background_source)
  5. Add equipment with add_item_to_character

Level Up a Character

  1. Read the character with get_character to check current level and class
  2. Level up with level_up_character (character_id, class_name, hp_method: "average"|"roll"|"manual")
  3. Optionally include subclass_name, asi_type ("asi"|"feat"), asi_ability1/asi_increase1, feat_name
  4. If the player chooses the feat later, do not level up again. Record the feat with add_character_feat (see Manage Character Feats)

Populate an Encounter

  1. Search monsters by name, CR range, or type with search_catalog(category: "monster")
  2. Add each monster to the module with add_monster_to_module (specify count)
  3. Search spells with search_catalog(category: "spell") if encounter involves spellcasters
  4. Record treasure in a dm_notes document, or grant it to a character with add_item_to_character (module-level loot tracking is not yet implemented)

Upload and Populate a Map

  1. Upload the .uvtt file (see "Files In and Out"), then create the map with create_map (module_id, name, upload_id)
  2. Add the monster to the module first with add_monster_to_module to get a module_monster_id
  3. Place it with add_token_to_map (map_id, module_monster_id, grid_x, grid_y, label) — coordinates are integer grid cells and default to (0,0)
  4. Place NPCs the same way with add_token_to_map (map_id, module_npc_id, grid_x, grid_y, label)
  5. Review with get_map to see all token placements
  6. Remove misplaced tokens with remove_token

Manage Character Inventory

  • get_character_inventory — view full inventory
  • add_item_to_character — add items (set equipped, attuned flags)
  • update_character_inventory — change quantity, equipped, or attuned status
  • remove_item_from_character — remove items by inventory ID

Manage Character Spells

  • list_character_spells — list all known spells, optionally filtered by class or prepared status
  • add_character_spell — add a catalog or homebrew spell to a character's known spells (set prepared: true to add it already prepared)
  • remove_character_spell — remove a spell by name, optionally scoped to a specific class

Set a spell's prepared state with the prepared flag when calling add_character_spell. Use spell_source: "HB" when adding homebrew spells, and verify the homebrew spell exists in the campaign with list_homebrew(content_type: "spell") before adding it to a character.

Manage Character Feats

  • list_character_feats — list the feats of a character, with the source book and how the character got each feat
  • add_character_feat — record a feat outside level-up, for example an ASI choice that the player made later
  • remove_character_feat — remove a feat by name

The feat must be in the catalog. Find its exact name and source with search_catalog(category: "feat"). The default source is PHB and the default source_type is asi. A character can have a feat only one time, unless the catalog marks the feat as repeatable.

Review Module Structure

Use get_module_details to see the full structure before editing — it returns the module's documents and monsters in one call. (Module-level item/loot tracking is not implemented, so no items are returned.)

Create Homebrew Content

Homebrew content lets the DM create custom items, monsters, and spells that don't exist in the catalog. The recommended workflow is clone and edit, not build from scratch.

Homebrew Items
  1. Search the catalog with search_catalog(category: "item") to find a similar base item
  2. Clone with create_homebrew(content_type: "item", name, data, item_type, rarity, cloned_from_name, cloned_from_source)
  3. Review with get_homebrew(content_type: "item", id)
  4. Edit with update_homebrew(content_type: "item", id) to refine the data JSON
  5. List all with list_homebrew(content_type: "item")
Homebrew Monsters
  1. Search the catalog with search_catalog(category: "monster") to find a similar base creature
  2. Clone with create_homebrew(content_type: "monster", name, data, cr, creature_type, size, cloned_from_name, cloned_from_source)
  3. Review with get_homebrew(content_type: "monster", id)
  4. Edit with update_homebrew(content_type: "monster", id) to adjust the stat block JSON
  5. List all with list_homebrew(content_type: "monster")
Homebrew Spells
  1. Search the catalog with search_catalog(category: "spell") to find a similar base spell
  2. Clone with create_homebrew(content_type: "spell", name, data, level, school, cloned_from_name, cloned_from_source)
  3. Review with get_homebrew(content_type: "spell", id)
  4. Edit with update_homebrew(content_type: "spell", id) to adjust the spell data JSON
  5. List all with list_homebrew(content_type: "spell")
  6. Add to a character with add_character_spell (spell_source: "HB", source_class: the granting class)

Important: The data field is a JSON string following 5etools format. Always clone from catalog to get the correct structure, then make targeted edits. If you must build from scratch, validate the JSON is well-formed before saving.

Document Types

Documents can belong to a module (provide module_id) or the campaign (omit module_id).

Supported types for create_document:

  • backstory — Background and history
  • read_aloud — Text to read to players
  • dm_notes — DM-only information
  • description — Location or encounter descriptions
  • custom — Custom documents

Source Filtering

When a campaign is active, catalog searches are automatically filtered to only include content from the campaign's enabled source books. This ensures monsters, items, and spells match the campaign's allowed content.

Additional Tips

  • Assign NPCs roles and locations for organization
  • Documents support markdown formatting for rich content
  • Use list_characters with location or faction filters to find NPCs by area
  • For exact parameter names (ability scores, currency, etc.), see references/tool-parameter-reference.md
  • When deleting homebrew content, check if any modules or characters reference it first
  • Homebrew monsters appear with source "HB" in module monster lists
  • Homebrew spells added to characters appear with source "HB" on the character sheet and in spell card PDF exports

NPC Network Analysis

Purpose

Analyze and visualize relationships between NPCs, their faction affiliations, knowledge networks, and social connections. Identify isolated NPCs, missing connections, and opportunities for richer storytelling.

Analysis Process

1. Gather NPC Data

list_characters(character_type: "npc")
# Filter by location or faction for focused analysis:
list_characters(character_type: "npc", location: "Waterdeep")
list_characters(character_type: "npc", faction: "Zhentarim")
# For each NPC:
get_character(character_id: character_id)

Extract from each NPC: name, role, location, faction affiliation, and module assignment.

2. Extract Implicit Relationships

Read documents to find relationship mentions:

# Campaign-level documents (world lore, session notes)
list_documents()  # omit module_id for campaign-level docs
read_document(document_id: document_id)
# Module-level documents
# For each module:
list_documents(module_id: module_id)
read_document(document_id: document_id)

Look for:

  • Direct relationships: "X is Y's brother"
  • Implied connections: Characters in the same location
  • Faction ties: Members of the same organization
  • Conflict relationships: Enemies, rivals
  • Knowledge chains: Who knows what secrets

3. Build Relationship Matrix

Categorize relationships:

TypeDescription
FamilyBlood relations, marriage
ProfessionalEmployer/employee, colleagues
FactionSame organization membership
LocationSame place, neighbors
ConflictEnemies, rivals, grudges
SecretHidden connections players can discover
KnowledgeWho knows information about whom

4. Network Analysis

Identify:

Hub NPCs — Characters with many connections. These are high-value targets for players. Consider: Are they protected? What happens if they die?

Isolated NPCs — Characters with no connections. These represent missed storytelling opportunities. Consider: How do players encounter them?

Faction Clusters — Groups of connected NPCs. Map internal faction dynamics and cross-faction connections.

Information Flow — How does news travel? Who would know if X happened? Trace rumor mill paths.

Output Format

# NPC Network: [Campaign Name]

## Faction: [Faction Name]
+-- [Leader NPC] (Leader)
|   +-- employs -> [NPC]
|   +-- rivals -> [NPC from other faction]
+-- [Member NPC]
|   +-- siblings -> [NPC]
+-- [Member NPC]

## Location: [Location Name]
+-- [NPC] - [Role]
+-- [NPC] - [Role]
+-- [NPC] - [Role]

## Key Relationships
- [NPC] <-secret lovers-> [NPC]
- [NPC] <-owes debt-> [NPC]
- [NPC] <-seeking revenge-> [NPC]

## Isolated NPCs (No Connections)
- [NPC]: Consider connecting to [suggestion]

## Hub NPCs (4+ Connections)
- [NPC]: [List of connections]
  - Risk: High-value target
  - Contingency: [Suggestion]

Mermaid Diagram (if requested)

graph TD
    A[Lord Mayor] -->|employs| B[Captain of Guard]
    A -->|rivals| C[Merchant Prince]
    B -->|siblings| D[Innkeeper]
    C -->|secret deal| E[Thieves Guild Leader]

Interactive Mode

  1. Present overall network structure
  2. Ask: "Which relationships would you like to explore?"
  3. Deep-dive into specific factions or characters
  4. Suggest missing connections: "These NPCs share a location but have no defined relationship. Should they know each other?"
  5. Offer to update NPC records with discovered relationships

Campaign Pressure Testing

Purpose

Systematically challenge campaign content by adopting an adversarial player mindset. Identify weaknesses, plot holes, and failure points before players discover them.

Pressure Test Process

1. Gather Context

Load the campaign and module being tested:

get_campaign_details()
get_module_details(module_id: module_id)
list_characters(character_type: "npc")

# Check for maps and token placements
list_maps(module_id: module_id)
get_map(map_id: map_id)

# Check campaign-level documents for world context
list_documents()  # omit module_id for campaign-level docs

# Check for orphaned NPCs (not assigned to any module)
list_characters(character_type: "npc")
# Flag any NPC without a module assignment or location

Read all relevant documents to understand the scenario.

2. Apply Pressure Test Categories

Work through each category, asking probing questions:

Murder Hobo Test

  • What if players kill the quest giver immediately?
  • What if they attack every NPC on sight?
  • Are there consequences that don't dead-end the campaign?

Skip Content Test

  • What if players ignore the hook entirely?
  • Can they bypass the dungeon and go straight to the BBEG?
  • What if they refuse the quest?

Clever Solution Test

  • Can they solve this with a single spell (Fly, Teleport, Speak with Dead)?
  • What if they befriend the villain?
  • Can divination magic reveal too much too early?

Resource Test

  • What if they're out of spell slots when they reach the boss?
  • What if they have unlimited money to throw at the problem?
  • What if they hire an army of mercenaries?

Information Test

  • What happens if they miss the key clue?
  • Are there backup ways to get critical information?
  • What if they get information out of order?

Social Test

  • What if they intimidate/charm their way past obstacles?
  • Can high Persuasion trivialize the challenge?
  • What if they take hostages?

3. Document Findings

For each issue found, categorize severity:

SeverityDescription
CriticalCampaign dead-ends, no recovery possible
MajorSignificant content bypassed, story breaks
MinorSuboptimal experience but recoverable
NoteSomething to be aware of during play

4. Suggest Mitigations

For each issue, propose solutions:

  • Add contingency NPCs or events
  • Create backup information sources
  • Add consequences instead of blocking
  • Prepare improvisational anchors

Output Format

# Pressure Test Report: [Module Name]

## Executive Summary
[1-2 sentence overall assessment]

## Critical Issues
- [Issue]: [Why it's a problem] -> [Suggested fix]

## Major Issues
- [Issue]: [Why it's a problem] -> [Suggested fix]

## Minor Issues
- [Issue]: [Why it's a problem] -> [Suggested fix]

## Strengths
- [What the module does well defensively]

## Recommended Preparations
- [DM notes to add]
- [Contingency NPCs to prepare]
- [Backup plot hooks]

Interactive Mode

  1. Present a scenario: "The players have just arrived at the tavern where the quest giver waits..."
  2. Ask: "What's the worst thing your players might do here?"
  3. Explore the consequences together
  4. Document the failure mode and mitigation

Session Prep Review

Purpose

Comprehensive pre-session review that combines continuity checking, encounter balance, NPC readiness, and gap identification before game time.

For deeper analysis of specific areas, see the related skills:

  • continuity-check — Full plot consistency audit
  • encounter-balance — Detailed CR and XP math
  • loot-audit — Treasure distribution analysis
  • npc-network — Relationship mapping
  • pressure-test — Adversarial scenario testing

Pre-Session Checklist

1. Content Readiness

Load the module being run and campaign-level context:

# Campaign-level documents (world lore, session notes)
list_documents()  # omit module_id for campaign-level docs
# Module content
get_module_details(module_id)
list_documents(module_id)

Verify:

  • Backstory or description document exists and is complete
  • Read-aloud text prepared for key moments
  • DM notes cover contingencies
  • Maps/handouts referenced are available
  • Relevant campaign-level documents reviewed (world lore, prior session notes)

2. NPC Readiness

list_characters(character_type: "npc", module_id: module_id)
# Also check by location if the session spans areas:
list_characters(character_type: "npc", location: "Tavern District")

For each NPC players will likely encounter:

  • Name, role, location defined
  • Motivation and goals clear
  • Key information they know documented
  • Ability scores set (for skill checks during play)
  • Inventory populated (get_character_inventory)
  • Voice/mannerism notes (optional)

3. Encounter Readiness

Review module monsters and maps:

  • Monster stat blocks accessible (verify via search_catalog(category: "monster"))
  • Tactics noted in DM notes
  • Terrain/environmental factors documented
  • Treasure/loot defined
  • Maps uploaded and tokens placed (list_maps, get_map)

4. Plot Thread Check

  • Current plot hooks are clear
  • Player goals acknowledged
  • Clues/information properly placed
  • Multiple paths to success exist

5. Contingency Prep

  • "What if they skip X" planned
  • "What if NPC dies" contingency
  • Backup hooks ready
  • Improvisation anchors noted

Output Format

# Session Prep Report: [Module Name]

## Ready
- [List of complete elements]

## Needs Attention
- [Element]: [What's missing] -> [Quick fix suggestion]

## Critical Gaps
- [Element]: [Why it's critical] -> [Action needed]

## NPCs for This Session

| NPC | Location | Ready? | Missing |
|-----|----------|--------|---------|
| [Name] | [Location] | [OK/WARN] | [What's missing] |

## Encounters

| Encounter | Difficulty | Ready? | Notes |
|-----------|------------|--------|-------|
| [Name] | [Difficulty] | [OK/WARN] | [Notes] |

## Quick Reference

### Key NPCs
- **[Name]**: [1-line summary, key info they have]

### Key Locations
- **[Location]**: [What happens here]

### Plot Threads
- [Thread]: [Current state, next beat]

## DM Notes
[Any generated prep notes or reminders]

Interactive Mode

  1. Identify the module being run
  2. Run through checklist categories
  3. For each gap, offer to:
    • Create missing NPC details
    • Add DM notes via create_document
    • Generate read-aloud text
    • Suggest encounter adjustments
  4. Generate a condensed cheat sheet for the session

Commands 5

Create a New Module

First verify there's an active campaign using get_active_campaign (it never errors and reports whether one is set). If none is active, list campaigns with list_campaigns and ask the user to select one, then set_active_campaign.

Create a new module using create_module with the provided name and description.

After creation:

  1. Report the module ID
  2. Offer to add initial content:
    • Module overview document
    • Backstory document
    • DM notes
  3. Ask if the user wants to populate with monsters or items

Generate a Dungeondraft Map

Step 1: Determine Map Type

If the user provided a preset name, use it directly. Available presets:

  • Terrain: forest, grassland, cave, desert, arctic, swamp
  • Water: lake, ice_lake, forest_river
  • Islands: island_tropical, island_forest, island_arctic

list_map_presets returns the authoritative set at runtime — call it if unsure.

If they provided a description or no arguments, help them choose:

  1. Call list_map_presets to show available presets
  2. Ask if a preset fits or if they want a custom config
  3. For custom configs, discuss: size, terrain types, vegetation density, roads/rivers, water, lighting, rooms/corridors/polygons

Step 2: Choose Output Location

Ask the user where to save the .dungeondraft_map file. Suggest a reasonable default like their Desktop or current directory. The tool returns a download link; you download the file to this location in step 4.

Step 3: Generate

From preset:

generate_map(preset: "<name>", seed: <random or user-specified>)

From custom config:

  1. Build the YAML config based on the discussion
  2. Validate first: validate_map_config(config_yaml: "...")
  3. If valid, generate: generate_map(config_yaml: "...")
  4. If errors, fix and re-validate

Step 4: Download the File

The result has download.download_url and download.filename. Download the file to the location from step 2:

curl -sS -f -H "Authorization: Bearer $MIMIR_API_TOKEN" \
  -o "<path>" "$MIMIR_URL<download_url>"

The link works one time, for one hour.

Step 5: Report Results

Show the generation stats:

  • Walls generated (room boundaries, corridors)
  • Portals generated (doors, windows)
  • Objects placed (trees, clutter, clumps)
  • Paths generated (roads, rivers)
  • Water polygons
  • Contour paths
  • Output file location

Remind the user they can open the file in Dungeondraft to view and edit the map.

Offer to regenerate with a different seed or adjusted config if they want variations.

List Mimir Campaigns

Use the list_campaigns MCP tool to show all available D&D campaigns, and get_active_campaign to learn which one is currently active (list_campaigns does not include active status, so compare its id against the id returned by get_active_campaign).

For each campaign, display:

  • Campaign name
  • Campaign ID
  • Creation date
  • Whether it's the active campaign (matches get_active_campaign)

If no campaigns exist, offer to create one using create_campaign.

After listing, ask the user if they want to set one as active using set_active_campaign.

Search Monster Catalog

Use search_catalog with category: "monster" to find monsters matching the criteria.

Parse the arguments:

  • If query looks like a creature type (undead, dragon, fiend, etc.), use monster_type
  • Otherwise use name for partial matching
  • If cr contains a dash, parse as cr_min and cr_max
  • If cr is a single value, use it for both min and max

Display results in a table format: | Name | CR | Type | Size | Source |

If searching within an active campaign, note that results are filtered to the campaign's enabled source books.

After showing results, offer to:

  1. Add a monster to a module
  2. Search with different criteria
  3. Get detailed stats for a specific monster
  4. Clone a monster as homebrew for customization

Search Spell Catalog

Use search_catalog with category: "spell" to find spells matching the criteria.

Parse the arguments:

  • If query is provided, use name for partial matching
  • If level is provided, use as integer filter (0 = cantrips)
  • If school is provided, use school filter
  • If class is provided, use class_name filter

Display results in a table format: | Name | Level | School | Source |

If searching within an active campaign, note that results are filtered to the campaign's enabled source books.

After showing results, offer to:

  1. Get more details about a specific spell
  2. Search with different criteria
  3. Clone a spell as homebrew for customization

MCP servers 1

Sponsors

Details

Marketplace
mimir-dm/mimir
Source
crates/mimir-mcp/plugin
Author
Colliery
Category
Productivity
License
MIT
Keywords
dnd, 5e, campaign, ttrpg, dungeon-master, mimir