Environment Configuration
Relevant source files
The following files were used as context for generating this wiki page:
The environment configuration in the MCP Games monorepo is designed to manage service discovery and integration settings across a distributed architecture. It facilitates communication between the interactive frontend, the Model Context Protocol (MCP) integration layer, and the AI narrative generation service.
The configuration strategy utilizes a combination of monorepo-wide pipeline settings via Turborepo and service-specific environment files (.env, .env.local). This ensures that each component—cyoa-engine, mcp-connector, and narrative-ai—has the necessary endpoints and API keys to function in both development and production environments.
Sources: apps/cyoa-engine/README.md, apps/narrative-ai/README.md, turbo.json
Global Monorepo Configuration
The project utilizes Turborepo to orchestrate builds and development workflows. The turbo.json file defines global dependencies on environment files, ensuring that changes to local environment settings trigger appropriate task re-executions.
{
"$schema": "https://turbo.build/schema.json",
"globalDependencies": ["**/.env.*local"],
"pipeline": {
"build": {
"dependsOn": ["^build"],
"outputs": [".next/**", "!.next/cache/**", "dist/**"]
}
}
}
Sources: turbo.json:1-10
Service Discovery and API Endpoints
The frontend application (cyoa-engine) requires connection strings for the backend microservices. These are typically defined in a .env.local file within the application directory and are injected into the Next.js runtime.
Frontend (cyoa-engine) Variables
| Variable | Description | Default/Example |
|---|---|---|
MCP_CONNECTOR_URL | Endpoint for the Express.js MCP integration service | http://localhost:3001 |
NARRATIVE_AI_URL | Endpoint for the FastAPI narrative generation service | http://localhost:8000 |
Sources: apps/cyoa-engine/README.md:25-30, apps/cyoa-engine/next.config.js:5-8
Next.js Configuration Injection
The next.config.js file explicitly maps these environment variables to ensure they are available during the build and runtime phases.
/** @type {import('next').NextConfig} */
const nextConfig = {
reactStrictMode: true,
transpilePackages: ['shared-types', 'mcp-sdk', 'story-engine'],
env: {
MCP_CONNECTOR_URL: process.env.MCP_CONNECTOR_URL || 'http://localhost:3001',
NARRATIVE_AI_URL: process.env.NARRATIVE_AI_URL || 'http://localhost:8000',
},
}
Sources: apps/cyoa-engine/next.config.js:1-10
Narrative AI Service Settings
The narrative-ai service, built with FastAPI, manages integrations with Large Language Model (LLM) providers. It requires specific API keys and model selections to generate story content and consequences.
AI Configuration Variables
| Variable | Description | Default Value |
|---|---|---|
OPENAI_API_KEY | Authentication key for OpenAI services | your_key_here |
ANTHROPIC_API_KEY | Authentication key for Anthropic services | your_key_here |
DEFAULT_MODEL | The LLM model used for narrative generation | gpt-4-turbo-preview |
Sources: apps/narrative-ai/README.md:32-37
Implementation in Python
The service uses python-dotenv to load these configurations into the application environment upon startup.
from dotenv import load_dotenv
import os
load_dotenv()
# Variables accessible via os.getenv("OPENAI_API_KEY")
Sources: apps/narrative-ai/main.py:7-9
MCP Connector Configuration
The mcp-connector acts as a gateway to external data sources. Its configuration focuses on network settings and caching policies for semantic queries.
Connector Variables
| Variable | Description | Default Value |
|---|---|---|
PORT | The port the Express server listens on | 3001 |
NODE_ENV | Current environment (development/production) | development |
MCP_CACHE_TTL | Time-to-live for cached MCP query results (seconds) | 3600 |
Sources: apps/mcp-connector/README.md:23-28
Configuration Data Flow
The following diagram illustrates how environment variables and configurations facilitate communication between the different services in the monorepo.
The diagram shows the distribution of configuration values from environment files to specific applications and the resulting communication paths.
Sources: apps/cyoa-engine/README.md, apps/mcp-connector/README.md, apps/narrative-ai/README.md
Conclusion
Environment configuration in the MCP Games monorepo is decentralized across services but unified by common naming conventions and Turborepo's pipeline management. By separating service endpoints and sensitive AI credentials into specific environment files, the architecture supports a modular deployment strategy where each component can be configured independently for different deployment contexts.