Narrative Generation Logic
Relevant source files
The following files were used as context for generating this wiki page:
The Narrative Generation Logic is a core component of the MCP Games ecosystem, responsible for creating dynamic, context-aware Choose Your Own Adventure (CYOA) experiences. It leverages Model Context Protocol (MCP) data—such as GitHub activity or Linear issues—to personalize story beats, character interactions, and plot branching. This logic is primarily encapsulated within the narrative-ai service and supported by the story-engine and shared-types packages.
Sources: README.md:1-20, apps/narrative-ai/README.md:1-10
Service Architecture
The narrative generation process is distributed across a Python-based AI service and a TypeScript-based state engine. The narrative-ai service handles the heavy lifting of Large Language Model (LLM) integration, while the story-engine manages the logical state machine and variable tracking.
Narrative AI Service (FastAPI)
The narrative-ai application provides REST endpoints for generating scenes, choices, and consequences. It is designed to be multi-provider, supporting models like GPT-4 Turbo and Claude via LangChain or direct SDKs.
The diagram shows the flow of data from the user interface through the AI service to the LLM providers, incorporating external context.
Sources: apps/narrative-ai/main.py:10-50, apps/narrative-ai/README.md:5-15
Data Models and Interfaces
Narrative generation relies on structured requests that include story identifiers, user context (aggregated from MCPs), and historical choice data.
Request/Response Schemas
| Component | Type | Description |
|---|---|---|
GenerateSceneRequest | Object | Contains story_id, user_context (Dict), and optional previous_choice. |
NarrativeResponse | Object | Returns generated text and metadata (model used, tokens). |
NarrativeGenerationRequest | Interface | (TS) Includes sceneTemplate, mcpData, and previousChoices. |
Sources: apps/narrative-ai/main.py:27-40, packages/shared-types/src/index.ts:182-192
Story Structure Types
The logic operates on a predefined Story structure that defines the boundaries of the generation.
This diagram illustrates the hierarchical relationship between stories, scenes, and player choices used during generation.
Sources: packages/shared-types/src/index.ts:55-80
Generation Flow and Logic
The generation logic follows a sequence where the system first validates the current state and then injects semantic context into the AI prompt.
Scene and Choice Generation
The narrative-ai service exposes specific endpoints for different stages of the narrative:
- Scene Generation: Uses the current story state and MCP context to draft the narrative text.
- Choice Generation: Dynamically creates options based on the generated scene and available variables.
- Consequence Calculation: Determines the text and variable changes resulting from a user's selection.
Sources: apps/narrative-ai/main.py:48-75, apps/narrative-ai/README.md:17-25
State Management Integration
While the AI generates the text, the StoryEngine in the story-engine package ensures that the narrative adheres to the game's logic.
The sequence shows how the deterministic state engine updates variables before the AI service generates the narrative text.
Sources: packages/story-engine/src/index.ts:58-90, apps/narrative-ai/main.py:43-55
Variable and Consequence Logic
The narrative is personalized through a system of variable substitution and requirement checking.
- Variable Effects: Choices can trigger operations like
set,increment,decrement, orappendon story variables. - Requirements: Choices may be gated by
ChoiceRequirements, which check both internalvariablesand externalmcpData. - Conditionals:
Consequenceobjects use condition strings to determine which narrative fragments are displayed to the user based on their previous actions.
Sources: packages/shared-types/src/index.ts:88-112, packages/story-engine/src/index.ts:167-210
Implementation Status
The current implementation provides the structural framework, with several core AI features marked for completion.
| Endpoint | Status | File Reference |
|---|---|---|
POST /api/generate/scene | Pending LLM Integration | apps/narrative-ai/main.py:48 |
POST /api/generate/choices | Pending Logic Implementation | apps/narrative-ai/main.py:61 |
GET /api/story/{story_id} | State Retrieval Pending | apps/narrative-ai/main.py:75 |
POST /api/story/validate | Consistency Logic Pending | apps/narrative-ai/README.md:25 |
The Narrative Generation Logic serves as the bridge between deterministic game state and dynamic AI-generated content, ensuring that every user adventure is uniquely tailored to their connected professional and personal contexts through the Model Context Protocol.