High-Level Architecture
Relevant source files
The following files were used as context for generating this wiki page:
The MCP Games ecosystem is a distributed monorepo designed to create "Choose Your Own Adventure" (CYOA) experiences. It utilizes the Model Context Protocol (MCP) to semantically query external data sources (such as GitHub, Linear, and Notion) to inject real-world user context into AI-generated narratives. The project is orchestrated using Turborepo and PNPM, ensuring type safety and shared logic across multiple microservices and packages.
Sources: README.md:1-15, turbo.json:1-25
System Overview
The architecture is divided into three primary applications supported by shared internal packages. The workflow involves the frontend requesting a narrative state, the connector gathering semantic context from MCP servers, and the AI engine generating personalized content based on that data.
The diagram above illustrates the high-level communication between the frontend, backend services, and shared libraries.
Sources: README.md:18-35, apps/cyoa-engine/package.json:15-20
Core Components
Applications
| Component | Technology | Responsibility |
|---|---|---|
| cyoa-engine | Next.js 14 | Interactive UI, choice selection, and progress tracking. |
| mcp-connector | Express.js | Integration layer for external MCP servers; handles semantic queries. |
| narrative-ai | FastAPI | LLM-powered generation for scenes, choices, and consequences. |
Sources: README.md:38-65, apps/mcp-connector/src/index.ts:1-10, apps/narrative-ai/main.py:1-15
Shared Packages
- shared-types: Contains central TypeScript interfaces for the MCP protocol, story structures, and API contracts. (Sources: packages/shared-types/src/index.ts:1-130)
- mcp-sdk: A client library for managing connections to MCP servers and executing semantic queries with built-in caching. (Sources: packages/mcp-sdk/src/index.ts:18-100)
- story-engine: Manages the logic for state transitions, variable effects (increment, set, append), and choice requirements. (Sources: packages/story-engine/src/index.ts:25-150)
Data Flow & Integration
The system follows a request-response cycle where user choices trigger semantic data retrieval to influence the next narrative step.
The sequence of events from fetching user context to generating a personalized story scene.
Sources: apps/mcp-connector/src/index.ts:47-58, apps/narrative-ai/main.py:44-55, packages/story-engine/src/index.ts:57-85
Data Models
The system relies on a strictly defined set of interfaces to ensure consistency across the Python and TypeScript environments.
Story and Scene Structure
The Story object contains a collection of Scene objects. Each scene contains narrative text and a list of Choice objects.
Sources: packages/shared-types/src/index.ts:61-100
Semantic Queries
Queries sent to the mcp-connector use a semantic string and optional filters to retrieve context.
| Field | Type | Description |
|---|---|---|
server | string | Target MCP server (e.g., 'github') |
query | string | Natural language semantic query |
filters | QueryFilters | Criteria like timeframe or status |
Sources: packages/shared-types/src/index.ts:24-40
Narrative State Management
The StoryEngine class processes variable effects based on user choices.
// Example of VariableEffect operation logic
switch (effect.operation) {
case 'set': newVariables[effect.variable] = effect.value; break;
case 'increment': newVariables[effect.variable] += effect.value; break;
case 'append': newVariables[effect.variable].push(effect.value); break;
}
Sources: packages/story-engine/src/index.ts:167-185
Conclusion
The MCP Games High-Level Architecture establishes a modular framework where AI-driven storytelling is grounded in real-world data. By decoupling context retrieval (mcp-connector), story logic (story-engine), and content generation (narrative-ai), the system allows for scalable and deeply personalized CYOA experiences that reflect a user's actual professional or personal activity.
Sources: README.md:7-15, README.md:145-155