Inter-Service Communication
Relevant source files
The following files were used as context for generating this wiki page:
Inter-service communication in the MCP Games monorepo is designed to facilitate a decoupled architecture where the frontend, data connectors, and AI generation services interact through standardized RESTful APIs. The primary goal is to enable the cyoa-engine to orchestrate story progression by fetching real-time context from the mcp-connector and generating narrative content via the narrative-ai service.
The ecosystem utilizes a combination of Express.js (Node.js), FastAPI (Python), and Next.js, with communication protocols defined by a shared TypeScript type library to ensure consistency across the distributed environment.
Sources: README.md:21-31, packages/shared-types/README.md:3-12
Service Architecture and Network Topology
The system follows a hub-and-spoke model where the cyoa-engine acts as the primary consumer of downstream services. Connectivity is managed through environment variables that define the service locations.
The diagram above illustrates the request flow where the frontend initiates communication with backend services, which in turn interface with external Model Context Protocol (MCP) servers.
Sources: README.md:22-31, apps/cyoa-engine/next.config.js:5-8
Connectivity Configuration
Services are located via the following default configurations:
| Service | Environment Variable | Default URL |
|---|---|---|
| MCP Connector | MCP_CONNECTOR_URL | http://localhost:3001 |
| Narrative AI | NARRATIVE_AI_URL | http://localhost:8000 |
Sources: apps/cyoa-engine/next.config.js:6-7, apps/cyoa-engine/README.md:30-33
API Communication Protocols
Data Exchange via mcp-connector
The mcp-connector provides endpoints for the frontend to retrieve semantic context from external platforms like GitHub and Linear. This context is essential for personalizing narratives.
- Query Endpoint:
POST /api/mcp/query- Used to execute semantic queries. - Context Aggregation:
GET /api/mcp/context/:userId- Aggregates data across all connected MCPs for a specific user.
Sources: apps/mcp-connector/src/index.ts:28-56, apps/mcp-connector/README.md:19-25
Narrative Generation via narrative-ai
The narrative-ai service handles the high-latency requests associated with LLM processing. It consumes user context and MCP data to return generated story components.
The sequence diagram shows the synchronous request/response cycle for generating story scenes based on provided context.
Sources: apps/narrative-ai/main.py:44-55, apps/narrative-ai/README.md:27-30
Shared Communication Schemas
To prevent drift between services, the monorepo uses shared-types to define the payload structures for every inter-service request and response.
Narrative Generation Payloads
Used when cyoa-engine requests new content from narrative-ai.
| Field | Type | Description |
|---|---|---|
storyId | string | Unique identifier for the current story session |
userContext | Record<string, unknown> | Profile-specific data for personalization |
mcpData | Record<string, unknown> | Data retrieved from the mcp-connector |
previousChoices | string[] | History of player decisions to maintain continuity |
Sources: packages/shared-types/src/index.ts:121-127
Standard API Response Wrapper
All TypeScript-based services utilize a standard response envelope.
export interface APIResponse<T = unknown> {
success: boolean;
data?: T;
error?: APIError;
metadata?: Record<string, unknown>;
}
Sources: packages/shared-types/src/index.ts:139-144
Security and Cross-Origin Communication
Because the services run on different ports and potentially different domains, Cross-Origin Resource Sharing (CORS) is explicitly configured on all backend services to allow traffic from the frontend.
- Express implementation: Uses the
cors()middleware with default settings. - FastAPI implementation: Uses
CORSMiddlewareallowing all origins (*), methods, and headers.
Sources: apps/mcp-connector/src/index.ts:11-12, apps/narrative-ai/main.py:17-23
Summary
Inter-service communication in this project is characterized by a typed, RESTful architecture where the frontend orchestrates data from a context-providing service (mcp-connector) and an intelligence-providing service (narrative-ai). This separation allows for independent scaling of AI generation tasks and data aggregation tasks.