Shared Types & Schemas
Relevant source files
The following files were used as context for generating this wiki page:
The shared-types package serves as the central source of truth for TypeScript definitions within the MCP Games monorepo. It establishes the technical contracts required for interoperability between the frontend (cyoa-engine), backend services (mcp-connector, narrative-ai), and shared libraries (mcp-sdk, story-engine).
By centralizing these schemas, the project ensures type safety across diverse domains, including the Model Context Protocol (MCP) communication layer, story state management, and user profile persistence.
Sources: packages/shared-types/README.md:1-12, packages/shared-types/src/index.ts:1-5
Core Domain Entities
The schema architecture is divided into logical domains that represent the different layers of the gaming ecosystem.
Story & Scene Structure
The story structure is defined by a hierarchical model starting from the Story object down to individual VariableEffect instances. This model supports branching narratives with conditional logic.
Diagram 1: The hierarchical relationship between stories, scenes, and choices.
Model Context Protocol (MCP) Types
These types define how the system connects to and queries external data sources like GitHub, Linear, and Notion to fetch real-world context for narrative personalization.
| Type | Description | Key Fields |
|---|---|---|
MCPConnection | Represents an active or historical connection to an MCP server. | id, type, status, config |
MCPConfig | Configuration parameters for an MCP server connection. | serverUrl, authToken, capabilities |
SemanticQuery | A request object for retrieving contextual data semantically. | server, query, filters, options |
QueryResult | The standardized envelope for data returned from an MCP. | data, metadata |
Sources: packages/shared-types/src/index.ts:6-46
State Management & Progress
The GameProgress and StoryState types are critical for maintaining continuity in Choice Your Own Adventure (CYOA) experiences.
Diagram 2: Data flow for user progress and state mutations.
The StoryState (defined in the story-engine) and GameProgress (defined in shared-types) are used to track the user's current position and variable values.
export interface GameProgress {
storyId: string;
currentSceneId: string;
variables: StoryVariables;
choices: string[];
timestamp: string;
}
Sources: packages/shared-types/src/index.ts:109-115, packages/story-engine/src/index.ts:18-25
Narrative Generation Contracts
The project uses specific request/response schemas for AI-driven content generation. This ensures that the narrative-ai service receives all necessary context, including MCP data and player history, to generate coherent updates.
- NarrativeGenerationRequest: Includes
sceneTemplate,userContext,mcpData, andpreviousChoices. - NarrativeGenerationResponse: Returns the generated
narrativetext, a new set ofChoiceobjects, and metadata regarding the LLM usage.
Sources: packages/shared-types/src/index.ts:130-146
Utility Types
To ensure consistent error handling across the monorepo, the shared library provides a functional Result pattern.
export type Result<T, E = Error> =
| { success: true; value: T }
| { success: false; error: E };
export type AsyncResult<T, E = Error> = Promise<Result<T, E>>;
This pattern is extensively utilized in the mcp-sdk and story-engine for operations like executing queries and processing choices.
Sources: packages/shared-types/src/index.ts:148-154, packages/mcp-sdk/src/index.ts:36-60, packages/story-engine/src/index.ts:40-54
Summary
The Shared Types & Schemas module provides the structural foundation for the MCP Games ecosystem. By defining standard interfaces for MCP connections, story hierarchies, and game state, it enables decoupled services to communicate effectively and maintains a strictly typed environment across the entire Turborepo.