Getting Started Guide
Relevant source files
The following files were used as context for generating this wiki page:
The MCP Games Monorepo is a Turborepo-based ecosystem designed to build Choose Your Own Adventure (CYOA) experiences. These experiences leverage the Model Context Protocol (MCP) to semantically query connected data sources like GitHub, Linear, and Notion, creating personalized narratives based on real-world user context.
This guide provides the necessary steps to set up the environment, install dependencies, and run the various services that comprise the platform.
Sources: README.md:3-10, package.json:1-5
System Architecture
The project is structured as a monorepo with three primary applications and three core shared packages.
Component Overview
| Component | Type | Technology | Description |
|---|---|---|---|
| cyoa-engine | App | Next.js 14, React, Tailwind | Frontend interactive UI for narrative and choice selection. |
| mcp-connector | App | Express.js, Node.js | Integration layer for connecting to MCP servers (GitHub, Linear, etc.). |
| narrative-ai | App | FastAPI, Python | AI engine for dynamic story generation and LLM integration. |
| shared-types | Package | TypeScript | Central type definitions for MCP protocol and story structures. |
| mcp-sdk | Package | TypeScript | Client library for semantic querying and connection pooling. |
| story-engine | Package | TypeScript | Core logic for choice trees, state management, and save/load. |
Sources: README.md:15-38, apps/cyoa-engine/README.md:17-21, apps/narrative-ai/README.md:3-9
System Data Flow
The following diagram illustrates the interaction between the user interface, the narrative engine, and the external data sources via MCP.
Diagram showing the flow from user choice to context-aware narrative generation.
Sources: README.md:20-60, apps/cyoa-engine/README.md:5-10
Prerequisites
Before setting up the project, ensure the following software is installed:
- Node.js: version >= 18.0.0
- PNPM: version >= 8.0.0
- Python: version >= 3.11 (specifically for the
narrative-aiservice)
Sources: README.md:105-108, package.json:19-22
Installation and Setup
1. Clone and Install Node Dependencies
The monorepo uses PNPM workspaces to manage dependencies across all apps and packages.
# Clone the repository
git clone https://github.com/RemyLoveLogicAI/mcp-games-monorepo.git
cd mcp-games-monorepo
# Install all dependencies for the workspace
pnpm install
Sources: README.md:112-118, package.json:23-26
2. Python Environment Setup
The narrative-ai service requires a dedicated Python virtual environment.
cd apps/narrative-ai
python -m venv venv
source venv/bin/activate # Windows: venv\Scripts\activate
pip install -r requirements.txt
cd ../..
Sources: README.md:120-125, apps/narrative-ai/README.md:12-20
3. Environment Configuration
Create environment files for the respective applications to enable service communication and LLM access.
apps/cyoa-engine/.env.local
MCP_CONNECTOR_URL=http://localhost:3001
NARRATIVE_AI_URL=http://localhost:8000
apps/narrative-ai/.env
OPENAI_API_KEY=your_key_here
ANTHROPIC_API_KEY=your_key_here
DEFAULT_MODEL=gpt-4-turbo-preview
Sources: apps/cyoa-engine/README.md:25-28, apps/narrative-ai/README.md:37-41
Development Workflow
Global Commands
Turborepo orchestrates tasks across the entire workspace. These commands can be run from the root directory.
# Run all services (Frontend, Connector, AI) in parallel
pnpm dev
# Build all packages and applications
pnpm build
# Run linting across the monorepo
pnpm lint
Sources: package.json:6-12, turbo.json:4-22
Running Individual Services
You can target specific services using PNPM filters or by navigating to the application directory.
| Task | Command |
|---|---|
| Frontend UI | pnpm --filter cyoa-engine dev |
| MCP Connector | pnpm --filter mcp-connector dev |
| Narrative AI | cd apps/narrative-ai && uvicorn main:app --reload |
Sources: README.md:144-154, apps/mcp-connector/README.md:15-17
Technical Service Overview
API Interaction
The services communicate via RESTful endpoints to manage MCP connections and generate narratives.
Sequence diagram showing service interaction for scene generation.
Sources: apps/mcp-connector/README.md:21-30, apps/narrative-ai/README.md:25-30
Key API Endpoints
| Service | Endpoint | Method | Purpose |
|---|---|---|---|
| mcp-connector | /api/mcp/query | POST | Execute semantic queries across connected MCPs. |
| mcp-connector | /api/mcp/context/:userId | GET | Retrieve aggregated user context. |
| narrative-ai | /api/generate/scene | POST | Generate the next scene based on LLM and context. |
| narrative-ai | /api/generate/choices | POST | Generate dynamic choice options for the user. |
Sources: apps/mcp-connector/README.md:28-30, apps/narrative-ai/README.md:26-28
Conclusion
Setting up the MCP Games Monorepo involves initializing a PNPM workspace and a Python environment. Once configured, the Turborepo pipeline allows developers to run the interactive frontend, the MCP integration layer, and the AI narrative service simultaneously to create context-aware gaming experiences.
Sources: README.md:105-154