Monorepo Structure & Workspace
Relevant source files
The following files were used as context for generating this wiki page:
The MCP Games monorepo is a sophisticated ecosystem designed to build "Choose Your Own Adventure" (CYOA) experiences powered by the Model Context Protocol (MCP). It utilizes a modern TypeScript/Python stack managed through a monorepo architecture to ensure tight integration between AI narrative generation, semantic data querying, and interactive user interfaces.
The project is structured as a Turborepo monorepo using PNPM Workspaces for dependency management. This setup allows for efficient build orchestration, shared type safety across services, and a modular development workflow where core logic is encapsulated in local packages consumed by multiple specialized applications.
Sources: README.md:3-12, package.json:20-27
Architecture Overview
The workspace is divided into two primary directories: apps/ for executable services and packages/ for reusable libraries. This separation ensures that core business logic, such as story state management and MCP communication protocols, remains decoupled from specific delivery platforms.
Project Directory Structure
The diagram above illustrates the relationship between the central applications and the shared internal libraries they depend on.
Sources: README.md:14-25, package.json:28-31
Workspace Configuration
The monorepo uses PNPM for workspace management, as defined in the root configuration. This allows applications to reference local packages using the workspace:* protocol, ensuring that changes in shared code are immediately reflected across the entire ecosystem without requiring external registry publishing.
| Component | Path | Technology | Description |
|---|---|---|---|
| cyoa-engine | apps/cyoa-engine | Next.js 14 | The interactive frontend UI for players. |
| mcp-connector | apps/mcp-connector | Express.js | Integration layer for semantic MCP querying. |
| narrative-ai | apps/narrative-ai | FastAPI (Python) | AI engine for dynamic story generation. |
| shared-types | packages/shared-types | TypeScript | Centralized interfaces and API contracts. |
| mcp-sdk | packages/mcp-sdk | TypeScript | Client library for connecting to MCP servers. |
| story-engine | packages/story-engine | TypeScript | State machine and choice tree logic. |
Sources: package.json:20-31, README.md:27-66
Build Pipeline & Task Orchestration
Task execution is managed by Turborepo, which provides advanced caching and parallelization for common developer workflows. The pipeline is configured in turbo.json to handle dependencies between builds, ensuring that shared packages are compiled before the applications that consume them.
{
"pipeline": {
"build": {
"dependsOn": ["^build"],
"outputs": [".next/**", "dist/**"]
},
"dev": {
"cache": false,
"persistent": true
}
}
}
Sources: turbo.json:4-13, package.json:6-13
Cross-Service Dependencies
The strength of this monorepo lies in its internal dependency graph. For instance, the cyoa-engine frontend depends on three internal workspace packages to function, ensuring strict type safety from the UI layer down to the core logic.
The diagram shows how shared-types acts as the foundational layer for all other components in the monorepo.
Sources: apps/cyoa-engine/package.json:18-20, apps/mcp-connector/package.json:18-19, packages/mcp-sdk/package.json:15, packages/story-engine/package.json:13
Development Workflow
The monorepo provides a unified interface for running the entire stack. While the majority of the project is Node.js-based, the inclusion of the Python-based narrative-ai service requires a hybrid environment setup.
- Unified Dev:
pnpm devtriggers the Turborepodevpipeline across all compatible apps. - Filtered Dev:
pnpm --filter <app-name> devallows developers to focus on a specific service. - Python Integration: The
narrative-aiservice requires a local virtual environment (venv) and usesuvicornfor its server execution.
Sources: README.md:121-155, apps/narrative-ai/main.py:1-12
Summary
The MCP Games monorepo structure provides a robust foundation for building AI-driven interactive narratives. By leveraging Turborepo and PNPM Workspaces, the project maintains a clear separation between the Next.js frontend, Express/FastAPI backends, and reusable TypeScript libraries. This architecture facilitates rapid development of "OmniAgents" that can semantically query external data sources while maintaining narrative consistency through shared story logic.
Sources: README.md:6-12, README.md:193-205