Data Flow Lifecycle

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• packages/shared-types/src/index.ts
• apps/mcp-connector/src/index.ts
• apps/narrative-ai/main.py
• packages/story-engine/src/index.ts
• packages/mcp-sdk/src/index.ts

The Data Flow Lifecycle in the MCP Games monorepo governs how user data, Model Context Protocol (MCP) information, and narrative states interact to produce a personalized gaming experience. The system transforms static story templates into dynamic adventures by injecting real-world context retrieved from external services like GitHub, Linear, and Notion via semantic querying.

The lifecycle starts with a user interaction in the frontend, moves through semantic context retrieval, proceeds to AI-driven narrative generation, and concludes with state updates in the core engine. This architecture ensures that every narrative branch is grounded in the user's specific technical and professional context.

Sources: README.md:10-18, packages/shared-types/src/index.ts:145-151

System Architecture & Component Interaction

The ecosystem is composed of three primary applications and supporting shared packages that manage distinct stages of the data lifecycle.

High-Level Component Flow

The following diagram illustrates the flow of data between the primary services and the shared logic packages.

Service Responsibilities

Service	Primary Data Responsibility	Key Technologies
cyoa-engine	Orchestrates user input and renders the narrative UI.	Next.js, Zustand
mcp-connector	Aggregates and normalizes data from multiple MCP servers.	Express.js, MCP SDK
narrative-ai	Generates text and choices using LLMs and injected context.	FastAPI, LangChain
story-engine	Manages the deterministic state machine and variable effects.	TypeScript

Sources: README.md:32-55, apps/cyoa-engine/README.md:14-20

Semantic Context Retrieval

Data flow begins with the retrieval of external context. The mcp-connector facilitates this by executing semantic queries against connected servers.

The Query Pipeline

1. Request Construction: The client uses SemanticQueryBuilder to define the target server and query string.
2. Execution: The MCPClient checks the local cache before sending the request to the mcp-connector.
3. Aggregation: The mcp-connector queries services (e.g., GitHub for recent commits) and returns a QueryResult.

Narrative Generation Lifecycle

Once context is retrieved, it is passed to the narrative-ai service. This service combines the user_context (from MCPs) with the current story_id and scene_template to generate a personalized narrative.

Generation Parameters

The NarrativeGenerationRequest structure defines the inputs required for the AI to produce a valid response:

Field	Type	Description
storyId	string	Unique identifier for the active story.
sceneTemplate	string	The base text to be modified by AI.
userContext	Record	Data retrieved from the user's local profile.
mcpData	Record	External context (e.g., GitHub repo names).
previousChoices	string[]	History of player decisions for consistency.

Sources: packages/shared-types/src/index.ts:145-151, apps/narrative-ai/main.py:30-40

State Management and Story Progression

The story-engine acts as the source of truth for the game state. It processes choices, applies effects to variables, and determines the next valid scene.

State Transition Logic

When a user makes a choice, the following logic is executed within the StoryEngine.makeChoice method:

1. Requirement Check: Validates if the state meets ChoiceRequirements (e.g., specific variable values).
2. Effect Application: Executes VariableEffect operations such as increment, decrement, or set.
3. State Update: Transitions the currentSceneId to the nextSceneId.

Data Structure: Variable Effects

export interface VariableEffect {
  variable: string;
  operation: 'set' | 'increment' | 'decrement' | 'append';
  value: unknown;
}

Sources: packages/shared-types/src/index.ts:100-104, packages/story-engine/src/index.ts:173-200

Conclusion

The Data Flow Lifecycle ensures a seamless transition from external data retrieval to internal state management. By decoupling context aggregation (mcp-connector), narrative intelligence (narrative-ai), and state logic (story-engine), the system can produce highly personalized "Choose Your Own Adventure" experiences that remain technically consistent with the user's real-world data.