Prompt Engineering System
Relevant source files
The following files were used as context for generating this wiki page:
The Prompt Engineering System is a core component of the narrative-ai service designed to facilitate context-aware narrative generation for Choose Your Own Adventure (CYOA) experiences. Its primary purpose is to inject semantic data retrieved from Model Context Protocol (MCP) servers into Large Language Model (LLM) prompts to create highly personalized story branches.
The system orchestrates the transformation of raw user data (from sources like GitHub, Linear, or Notion) into structured narrative elements, including scenes, choice options, and consequences. It ensures plot consistency and maintains character personality modeling by leveraging the aggregated context provided by the mcp-connector service.
Sources: README.md:46-51, apps/narrative-ai/README.md:5-10
Architecture and Context Injection
The system operates as part of the FastAPI-based narrative-ai application. It utilizes a combination of user preferences, historical choice data, and external MCP metadata to construct prompts for providers such as OpenAI and Anthropic.
The data flow involves receiving a generation request, aggregating context, and returning a structured narrative response.
The diagram above illustrates the high-level flow of data from initial request to the final narrative output.
Sources: README.md:120-136, apps/narrative-ai/main.py:34-60
Key Components and Data Structures
Narrative Generation Models
The system relies on specific data structures to handle the exchange of information between the engine and the LLM providers. These are primarily defined in the shared types and implemented as Pydantic models in the Python service.
| Component | Description | Source File |
|---|---|---|
NarrativeGenerationRequest | Defines the required input: story ID, scene template, user context, and MCP data. | packages/shared-types/src/index.ts:182-188 |
GenerateSceneRequest | Python model for requesting the next story scene, including previous choice references. | apps/narrative-ai/main.py:24-27 |
GenerateChoicesRequest | Python model for generating branching options based on current scene context. | apps/narrative-ai/main.py:29-32 |
NarrativeResponse | Standard output format containing the generated text and execution metadata. | apps/narrative-ai/main.py:34-36 |
API Endpoints for Prompting
The narrative-ai service exposes specific endpoints that trigger the prompt engineering logic:
POST /api/generate/scene: Constructs a prompt to generate the next segment of the story. It incorporates theuser_contextandstory_idto maintain narrative flow.POST /api/generate/choices: Specifically generates valid branching options that align with the current state of the story and the user's external context.POST /api/generate/consequence: Generates specific outcomes based on a selected choice.
Sources: apps/narrative-ai/README.md:21-25, apps/narrative-ai/main.py:43-73
Context Integration Logic
The system's "unrestricted OmniAgent" vision is realized through the semantic injection of MCP data. This allows the prompt engine to personalize stories based on real-world activity.
This sequence shows how the Narrative AI service acts as a mediator between user data and the LLM.
Sources: apps/mcp-connector/src/index.ts:46-55, README.md:120-136
Configuration and Environment
The prompt engineering behavior is governed by environment variables that determine the model behavior and provider selection.
DEFAULT_MODEL: Specified asgpt-4-turbo-previewfor high-quality narrative reasoning.ANTHROPIC_API_KEY/OPENAI_API_KEY: Authentication for the underlying model providers.
Sources: apps/narrative-ai/README.md:32-35, apps/narrative-ai/main.py:47-51
Narrative Generation Contract
The system enforces a strict interface for narrative output to ensure the cyoa-engine can render the story correctly.
export interface NarrativeGenerationResponse {
narrative: string;
choices: Choice[];
metadata: {
model: string;
tokensUsed: number;
generationTime: number;
};
}
Sources: packages/shared-types/src/index.ts:190-198
Summary
The Prompt Engineering System serves as the intelligence layer of the MCP Games monorepo. By synthesizing static story templates with dynamic, semantic data from MCP servers (such as recent GitHub contributions or Linear issues), it creates a personalized "Developer's Journey." The system is structured around FastAPI endpoints and shared TypeScript definitions to maintain consistency across the narrative generation lifecycle.
Sources: README.md:139-145, apps/narrative-ai/README.md:5-10