// OVERVIEW
Quest Keeper AI provides 97 MCP (Model Context Protocol) tools across two specialized servers for building AI-powered D&D 5e campaigns.
🎮 Game State Server: 68 tools for character management, world persistence, and game logic
⚔️ Combat Engine Server: 29 tools for dice mechanics, spatial combat, and tactical operations
Server Architecture
The dual-server architecture separates concerns:
- Game State Server - Handles persistence, character data, world state, and game progression
- Combat Engine Server - Provides stateless combat calculations, dice rolling, and spatial combat
// Typical workflow: coordinating both servers 1. get_character() → [Game State] Retrieve character stats 2. attack_roll() → [Combat Engine] Calculate attack 3. damage_roll() → [Combat Engine] Calculate damage 4. apply_damage() → [Game State] Update HP
// GAME STATE SERVER rpg-game-state
The Game State Server manages all persistent game data using SQLite for reliable storage across sessions.
Character Management
CRUD operations for player characters with full D&D 5e stat tracking.
create_character
Creates a new player character with name, race, class, level, ability scores, and inventory.
get_character
Retrieves complete character data by ID including stats, HP, inventory, and equipped items.
update_character
Updates any character field - HP, XP, level, stats, position, or equipped items.
list_characters
Returns all characters in the database with basic info for party management.
get_character_by_name
Finds a character by name for natural language queries.
// Example: Create a 5th level ranger
{
"name": "Lyra Swiftarrow",
"race": "Wood Elf",
"class": "Ranger",
"level": 5,
"max_hp": 38,
"current_hp": 38,
"ability_scores": {
"str": 10, "dex": 18, "con": 14,
"int": 12, "wis": 15, "cha": 8
}
}
Inventory Management
Full item system with quantities, weights, and equipment slots.
add_item
Adds items to character inventory with quantity, weight, and optional equipment status.
get_inventory
Returns complete inventory list with all item properties and total weight.
remove_item
Removes items by ID or reduces quantity for stackable items.
update_item
Modifies item properties, quantity, or equipped status.
World State Management
Flexible key-value storage for campaign state, locations, and narrative progress.
save_world_state
Stores arbitrary world data like locations, time, weather, or faction standings.
get_world_state
Retrieves stored world state data by key for campaign continuity.
update_world_state
Updates existing world state entries without recreating.
append_world_state
Appends to existing text-based state (e.g., adding to location descriptions).
NPCs & Monsters
Full creature management with D&D 5e stat blocks, abilities, and AI behavior.
create_npc
Creates individual NPCs/monsters with complete stat blocks, abilities, and inventory.
create_npc_group
Spawns multiple identical creatures at once (e.g., "5 goblins").
get_npc
Retrieves complete NPC data including current HP, status effects, and position.
list_npcs
Returns all NPCs in the world with filtering options.
update_npc
Modifies NPC stats, HP, position, or any other property.
remove_npc
Removes NPCs from the world (death, dismissal, etc.).
Encounter Management
Complete combat encounter system with initiative tracking and turn management.
create_encounter
Starts a new combat encounter with name, description, and initial difficulty.
add_to_encounter
Adds characters or NPCs to active encounter with initiative rolls.
get_encounter_state
Returns complete encounter status, participants, initiative order, and current turn.
next_turn
Advances to next creature in initiative order.
end_encounter
Concludes combat, awards XP, and cleans up encounter data.
apply_damage
Applies damage to characters or NPCs, handles death, and tracks HP.
get_active_encounter
Gets the currently active encounter if one exists.
start_turn
Begins a creature's turn and resets action economy.
end_turn
Ends current turn and processes end-of-turn effects.
consume_action
Tracks action economy (action, bonus action, reaction, movement).
Quest System
Track campaign objectives, quest progress, and story beats.
save_story_progress
Saves narrative progress, plot points, and story state.
add_quest
Creates new quests with objectives, rewards, and status tracking.
get_active_quests
Returns all active quests for a character or the party.
update_quest_state
Updates quest progress, completes objectives, or changes quest status.
assign_quest_to_character
Links quests to specific characters for personal storylines.
Spell Management
Complete spellcasting system with spell slots, spell tracking, and D&D 5e rules.
add_spell
Adds spells to a character's spell list with level, school, and details.
remove_spell
Removes spells from character's known/prepared spells.
get_character_spells
Returns all spells known/prepared by a character.
update_spell_status
Changes spell prepared status or modifies spell properties.
get_spell_slots
Returns available spell slots by level for a character.
use_spell_slot
Consumes a spell slot when casting a spell.
recover_spell_slot
Restores spell slots during short/long rests or special abilities.
reset_spell_slots
Fully restores all spell slots (typically after long rest).
initialize_spellcasting
Sets up spell slots for a spellcasting character based on class/level.
cast_spell
Complete spell casting flow including slot consumption and effects.
Stronghold System
Domain-level play with base building, hirelings, and passive income generation.
create_stronghold
Establishes a new stronghold with location, size, and initial facilities.
get_stronghold_status
Returns complete stronghold data including facilities, income, and events.
get_character_strongholds
Lists all strongholds owned by a character.
update_stronghold
Modifies stronghold properties like defenses, reputation, or resources.
add_facility
Constructs new facilities (barracks, library, workshop, etc.).
upgrade_facility
Improves existing facilities to higher tiers with better benefits.
get_stronghold_facilities
Lists all facilities and their current status.
list_facility_types
Returns available facility types and their costs/benefits.
recruit_hireling
Hires NPCs for stronghold staff (guards, craftsmen, etc.).
assign_hireling
Assigns hirelings to specific roles or facilities.
manage_hireling_loyalty
Tracks and modifies hireling morale and loyalty.
calculate_hireling_costs
Computes weekly/monthly costs for maintaining hirelings.
list_character_hirelings
Returns all hirelings employed by a character.
establish_business
Creates income-generating businesses in the stronghold.
process_weekly_income
Generates passive income from businesses and facilities.
get_stronghold_businesses
Lists all businesses and their income rates.
generate_stronghold_event
Creates random events (attacks, opportunities, problems) for the stronghold.
resolve_stronghold_event
Handles player responses to stronghold events and applies outcomes.
get_stronghold_events
Returns active and pending stronghold events.
Batch Operations
Optimized operations for handling multiple creatures or actions simultaneously.
batch_create_npcs
Creates multiple NPCs in a single transaction for performance.
batch_update_npcs
Updates multiple NPCs at once (e.g., move entire group).
batch_apply_damage
Applies damage to multiple creatures (area effects, explosions).
batch_remove_npcs
Removes multiple NPCs efficiently.
batch_add_to_encounter
Adds multiple creatures to encounter simultaneously.
// COMBAT ENGINE SERVER rpg-combat-engine
The Combat Engine Server provides stateless combat calculations and spatial battlefield management.
Dice & Rolling Mechanics
Complete D&D 5e dice system with advantage, modifiers, and critical hits.
roll_dice
Rolls any dice notation (1d20, 3d6+4, 8d8) with full support for modifiers.
roll_check
Ability checks with advantage/disadvantage and proficiency bonuses.
attack_roll
Attack rolls with modifiers, advantage/disadvantage, and critical hit detection.
initiative_roll
Initiative rolls with DEX modifiers for combat order.
damage_roll
Damage calculations with type tracking and critical damage.
saving_throw
Saving throws against DC with success/failure and damage on save.
// Example: Attack roll with advantage
{
"attacker": "Lyra",
"target": "Goblin Chief",
"modifier": 7,
"advantage": true
}
// Returns: { result: 25, roll: "2d20kh1+7 = [18,12]→18+7 = 25", hit: true }
Spatial Combat System
3D battlefield with terrain, elevation, line-of-sight, and movement.
initialize_battlefield
Creates a new battlefield with dimensions and terrain features.
place_creature
Places a creature on the battlefield at specific coordinates.
move_creature
Moves creature with pathfinding, terrain checking, and opportunity attacks.
check_line_of_sight
Determines if two positions have clear line of sight (for ranged attacks/spells).
get_area_effect_targets
Finds all creatures within an area (sphere, cone, cube) for AoE spells.
check_flanking
Checks if a creature is flanked for advantage on attacks.
check_height_advantage
Determines bonuses from elevation differences.
describe_battlefield
Generates narrative description of the battlefield layout.
generate_battlefield_map
Creates ASCII map visualization of current battlefield state.
// Example battlefield map output ═══════════════════════════════════════ │ 🧙 · · · ■ · · · · · │ │ · · · · ■ · · 👹 · · │ │ · · ⚔️ · · · · · · · │ │ · · · · ▲ ▲ · · · · │ │ · · · · ▲ ▲ · · 🗡️ · │ ═══════════════════════════════════════ Legend: 🧙 Wizard (PC) 👹 Goblin ⚔️ Fighter (PC) ■ Wall ▲ Difficult Terrain · Open
Tactical Analysis
Advanced combat features for complex encounters.
get_tactical_summary
Provides AI DM with tactical situation analysis (cover, threats, positioning).
describe_detailed_tactical_situation
Detailed narrative description of combat positioning for immersion.
get_combat_log
Returns history of all combat actions for review.
clear_combat_log
Clears combat log (typically after encounter ends).
use_reaction
Handles reactions (opportunity attacks, counterspell, etc.).
use_legendary_action
Legendary creature actions between turns.
trigger_lair_action
Lair actions on initiative count 20 for powerful creatures.
execute_multiattack
Handles monsters with multiple attacks per action.
Batch Combat Operations
Optimized operations for large-scale battles and area effects.
batch_place_creatures
Places multiple creatures on battlefield efficiently.
batch_move_creatures
Moves entire groups simultaneously (e.g., goblin horde).
batch_attack_rolls
Resolves multiple attacks at once (swarms, volleys).
batch_damage_rolls
Calculates damage for multiple targets (fireballs, explosions).
batch_saving_throws
Rolls saves for multiple creatures against area effects.
batch_initiative_rolls
Rolls initiative for all combatants at encounter start.
// COMPLETE TOOL LIST
Game State Server (68 tools)
- create_character
- get_character
- update_character
- list_characters
- get_character_by_name
- add_item
- get_inventory
- remove_item
- update_item
- save_world_state
- get_world_state
- update_world_state
- append_world_state
- create_npc
- create_npc_group
- get_npc
- list_npcs
- update_npc
- remove_npc
- create_encounter
- add_to_encounter
- get_encounter_state
- next_turn
- end_encounter
- apply_damage
- get_active_encounter
- start_turn
- end_turn
- consume_action
- save_story_progress
- add_quest
- get_active_quests
- update_quest_state
- assign_quest_to_character
- add_spell
- remove_spell
- get_character_spells
- update_spell_status
- get_spell_slots
- use_spell_slot
- recover_spell_slot
- reset_spell_slots
- initialize_spellcasting
- cast_spell
- create_stronghold
- get_stronghold_status
- get_character_strongholds
- update_stronghold
- add_facility
- upgrade_facility
- get_stronghold_facilities
- list_facility_types
- recruit_hireling
- assign_hireling
- manage_hireling_loyalty
- calculate_hireling_costs
- list_character_hirelings
- establish_business
- process_weekly_income
- get_stronghold_businesses
- generate_stronghold_event
- resolve_stronghold_event
- get_stronghold_events
- batch_create_npcs
- batch_update_npcs
- batch_apply_damage
- batch_remove_npcs
- batch_add_to_encounter
Combat Engine Server (29 tools)
- roll_dice
- roll_check
- attack_roll
- initiative_roll
- damage_roll
- saving_throw
- use_reaction
- use_legendary_action
- trigger_lair_action
- execute_multiattack
- initialize_battlefield
- place_creature
- move_creature
- check_line_of_sight
- get_area_effect_targets
- get_tactical_summary
- check_flanking
- check_height_advantage
- get_combat_log
- clear_combat_log
- describe_battlefield
- describe_detailed_tactical_situation
- generate_battlefield_map
- batch_place_creatures
- batch_move_creatures
- batch_attack_rolls
- batch_damage_rolls
- batch_saving_throws
- batch_initiative_rolls