Creating Custom Stories
Relevant source files
The following files were used as context for generating this wiki page:
Creating custom stories in the MCP Games ecosystem involves defining structured narrative data that can interact with the Model Context Protocol (MCP) and AI generation services. The system utilizes a Choose Your Own Adventure (CYOA) model where stories are composed of scenes, branching choices, and persistent variables that adapt based on real-world data from connected MCP servers.
Stories are managed by the StoryEngine, which handles state transitions, variable manipulation, and requirement validation. Custom stories can be static definitions or dynamically augmented by the narrative-ai service to personalize the experience based on user context.
Sources: README.md:12-25, packages/story-engine/src/index.ts:31-40
Story Architecture and Data Structures
A custom story is defined primarily by the Story interface. This structure acts as the blueprint for the narrative, containing all possible scenes, initial variables, and metadata.
Core Story Components
| Component | Type | Description |
|---|---|---|
id | string | Unique identifier for the story. |
title | string | The display title of the adventure. |
scenes | Scene[] | An array of narrative nodes containing text and choices. |
variables | StoryVariables | Key-value pairs representing the initial state of the story. |
metadata | StoryMetadata | Information about authorship, versioning, and required MCP integrations. |
Sources: packages/shared-types/src/index.ts:60-67
Scene and Choice Logic
Each Scene represents a single point in the narrative. To progress, a user must select a Choice. Choices can have requirements (to hide or show them based on state) and effects (to modify story variables).
The diagram above illustrates the hierarchical relationship between stories, scenes, and the choices that link them.
Sources: packages/shared-types/src/index.ts:69-92
Implementing Variable Effects
Custom stories use VariableEffect objects to create dynamic consequences for player actions. The StoryEngine supports several operations to modify the story state when a choice is made.
| Operation | Description | Implementation Detail |
|---|---|---|
set | Replaces a variable with a new value. | newVariables[variable] = value |
increment | Adds a numeric value to an existing variable. | Coerces current value to Number before adding. |
decrement | Subtracts a numeric value from an existing variable. | Coerces current value to Number before subtracting. |
append | Adds an item to a list variable. | Converts variable to array if not already one. |
Sources: packages/story-engine/src/index.ts:182-211, packages/shared-types/src/index.ts:94-99
Dynamic Personalization with Narrative AI
While stories can be static, the narrative-ai service allows for "unrestricted OmniAgents" to generate content dynamically. When creating a story intended for AI augmentation, the sceneTemplate is used alongside MCP data to generate the final text.
The sequence diagram shows how the system fetches real-world context to personalize the story generation process.
Sources: apps/narrative-ai/main.py:44-55, packages/shared-types/src/index.ts:145-152, README.md:12-25
Story State Management
The StoryEngine class is the primary interface for interacting with a custom story. Developers use it to start new sessions and process transitions.
Key Engine Methods
start(userId): Initializes a newStoryStateusing the story's first scene and default variables.makeChoice(state, choiceId): Validates requirements, applies variable effects, and moves the state to thenextSceneId.meetsRequirements(state, choice): Evaluates if a player's current variables match the criteria defined inChoiceRequirements.getProgress(state): Calculates the percentage of unique scenes visited relative to the total scenes in the story definition.
Sources: packages/story-engine/src/index.ts:47-52, packages/story-engine/src/index.ts:68-73, packages/story-engine/src/index.ts:121-125, packages/story-engine/src/index.ts:161-165
Conclusion
Creating custom stories for the MCP Games platform requires defining a JSON-compatible Story structure that maps out the narrative graph. By utilizing the VariableEffect system and integrating with the narrative-ai service, creators can build experiences that are not only branching but also deeply contextualized to a user's real-world data provided via MCP servers.
Sources: packages/story-engine/README.md:1-15, README.md:135-145