// OVERVIEW
Quest Keeper AI provides 135+ MCP (Model Context Protocol) tools in a single, unified binary for building AI-powered D&D 5e campaigns.
⚙️ Unified rpg-mcp Server: A single executable handling character state, combat mechanics, authentic D&D rules, and world simulation.
Server Architecture
The unified architecture provides seamless integration:
- Core Systems - Character data, world state, and game progression
- Combat Engine - Stateless combat calculations and spatial tracking
- Simulation Kernel - Economy, decomposition, and social dynamics
// 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
// CORE SYSTEMS rpg-mcp
The Core Systems manage permanent 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.