Build & Deployment Process
Relevant source files
The following files were used as context for generating this wiki page:
The Build & Deployment Process for the MCP Games Monorepo is centered around Turborepo for build orchestration and PNPM for workspace management. The ecosystem is designed as a polyglot monorepo, managing a Next.js frontend, an Express.js connector, and a FastAPI service alongside several shared TypeScript packages.
The process leverages a unified pipeline that handles dependency resolution, environment configuration, and task execution across all services. This ensures that changes in shared packages, such as shared-types or mcp-sdk, are correctly propagated to the consuming applications during the build cycle.
Sources: README.md:14-25, package.json:20-25, turbo.json:1-20
Monorepo Architecture & Workspace Management
The project uses PNPM workspaces to manage dependencies and link internal packages. The root configuration defines two primary directories for the build system: apps/ for deployable services and packages/ for shared libraries.
The diagram above illustrates the structural hierarchy and the internal dependency links managed by PNPM.
Sources: package.json:20-24, README.md:20-30, apps/cyoa-engine/package.json:15-18
Build Pipeline (Turborepo)
The build process is orchestrated by Turborepo, which defines the execution order and caching strategies for tasks. The pipeline is configured in turbo.json to handle dependencies between tasks, ensuring that a package is built before its dependents.
Pipeline Configuration
| Task | Depends On | Outputs | Description |
|---|---|---|---|
build | ^build | .next/**, dist/** | Compiles the application and its workspace dependencies. |
lint | ^build | N/A | Performs static analysis after dependencies are built. |
test | ^build | coverage/** | Executes unit and integration tests. |
dev | N/A | N/A | Starts the development server with persistent caching disabled. |
Sources: turbo.json:4-19
Execution Flow
- Dependency Installation: PNPM resolves local workspace links (e.g.,
workspace:*) and installs external dependencies. - Task Orchestration:
turbo run buildtriggers recursive builds. - Caching: Turborepo caches successful build outputs to speed up subsequent executions.
Sources: package.json:7-12, apps/cyoa-engine/package.json:15-18
Service-Specific Build Requirements
Each service within the monorepo has unique build and runtime requirements based on its technology stack.
Frontend and Node.js Services
The cyoa-engine (Next.js) and mcp-connector (Express.js) use standard TypeScript compilation. The frontend specifically requires transpilation of workspace packages to ensure shared logic is compatible with the Next.js build environment.
// apps/cyoa-engine/next.config.js
const nextConfig = {
reactStrictMode: true,
transpilePackages: ['shared-types', 'mcp-sdk', 'story-engine'],
}
Sources: apps/cyoa-engine/next.config.js:2-6, apps/mcp-connector/package.json:6-12
Python Service (narrative-ai)
The narrative-ai service operates outside the standard PNPM/Node build flow and requires a Python 3.11 environment. Its deployment involves creating a virtual environment and installing dependencies via pip.
# Deployment steps for narrative-ai
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt
uvicorn main:app --host 0.0.0.0 --port 8000
Sources: apps/narrative-ai/README.md:12-20, README.md:104-109
Deployment Environment Configuration
Deployment is controlled via environment variables. The monorepo uses .env.local files which are tracked as global dependencies in Turborepo to ensure cache invalidation when configurations change.
Required Environment Variables
| Service | Variable | Default/Example | Purpose |
|---|---|---|---|
| cyoa-engine | MCP_CONNECTOR_URL | http://localhost:3001 | API endpoint for the MCP Connector. |
| cyoa-engine | NARRATIVE_AI_URL | http://localhost:8000 | API endpoint for Narrative AI. |
| narrative-ai | OPENAI_API_KEY | your_key_here | Authentication for LLM provider. |
| mcp-connector | PORT | 3001 | Service listening port. |
Sources: apps/cyoa-engine/README.md:28-31, apps/narrative-ai/README.md:33-37, turbo.json:3
Summary of Commands
The following commands are used to manage the lifecycle of the applications within the monorepo:
- Full Build:
pnpm build(Executesturbo run build). - Development:
pnpm dev(Starts all services in parallel). - Cleanup:
pnpm clean(Removesnode_modulesand build artifacts like.nextanddist). - Service Filtering:
pnpm --filter <service_name> dev(Runs a specific app only).
Sources: package.json:7-13, README.md:118-132