Introduction & Vision
Relevant source files
The following files were used as context for generating this wiki page:
The MCP Games Monorepo is the foundational project within the Prime AI Agents ecosystem, specifically focused on creating unrestricted "OmniAgents." These agents power personalized Choose Your Own Adventure (CYOA) experiences by integrating with the Model Context Protocol (MCP). The core mission is to move beyond static narratives by semantically querying a user's real-world data—such as GitHub contributions, Linear tasks, or Notion documents—to generate context-aware stories where every decision and plot point reflects the user's actual environment and professional identity.
The project is structured as a Turborepo monorepo, orchestrating a suite of specialized microservices and shared libraries. By leveraging AI-powered narrative generation and a robust MCP integration layer, the system transforms standard productivity data into dynamic, interactive storytelling.
Sources: README.md:1-12, README.md:144-148
Core Philosophy: Unrestricted OmniAgents
The vision centers on the concept of OmniAgents that leverage MCP integrations to break the barriers between traditional gaming and real-world utility. These agents do not just follow a pre-written script; they adapt to the user's specific context, preferences, and data sources.
Key Objectives
- Contextual Storytelling: Use semantic queries to pull data from platforms like GitHub, Linear, and Notion to influence story branches.
- Dynamic Personalization: Generate narratives that evolve based on a user's actual work patterns and professional history.
- Modular Architecture: Utilize a monorepo structure to maintain tight coupling between shared types and independent services.
Sources: README.md:8-12, README.md:130-141
System Architecture Overview
The ecosystem is divided into three primary applications and three core packages. This separation ensures that the narrative logic, AI generation, and data retrieval layers remain scalable and maintainable.
High-Level Component Relationship
The following diagram illustrates how the various services and packages interact within the monorepo to deliver a personalized experience.
The diagram shows the interaction between the Next.js frontend, the FastAPI narrative engine, and the Express.js MCP connector.
Sources: README.md:14-30, packages/shared-types/src/index.ts
Component Responsibilities
| Component | Technology | Description |
|---|---|---|
| cyoa-engine | Next.js 14, React | The primary UI for interactive narratives, choice selection, and MCP configuration. |
| mcp-connector | Express.js, Node.js | Aggregates and normalizes data from multiple MCP servers (GitHub, Linear, etc.). |
| narrative-ai | FastAPI, Python | Generates dynamic plot points and character dialogue using LLMs (OpenAI/Anthropic). |
| shared-types | TypeScript | Defines the data contracts, including Story, Scene, and MCPConnection interfaces. |
| mcp-sdk | TypeScript | A client library providing a fluent API for semantic querying of MCP servers. |
| story-engine | TypeScript | Logic for choice tree navigation, variable tracking, and state persistence. |
Sources: README.md:32-75, apps/cyoa-engine/README.md:16-21, apps/mcp-connector/README.md:5-11
MCP Integration & Data Flow
The "Vision" of the project is realized through the semantic query system. Unlike standard API calls, the system uses semantic queries to interpret the "essence" of user data for narrative injection.
Narrative Generation Sequence
The following sequence diagram detail how a user's real-world context is fetched and turned into a story scene.
The sequence shows the flow from initial data retrieval to the final AI-generated narrative response.
Sources: README.md:112-128, apps/mcp-connector/src/index.ts:39-48, apps/narrative-ai/main.py:46-56
Data Structures for Connectivity
The shared-types package defines how these connections are modeled to ensure consistency across the monorepo.
// From packages/shared-types/src/index.ts
export interface MCPConnection {
id: string;
name: string;
type: 'github' | 'linear' | 'notion' | 'filesystem' | 'custom';
status: 'connected' | 'disconnected' | 'error';
config: MCPConfig;
}
export interface SemanticQuery {
server: string;
query: string;
filters?: QueryFilters;
options?: QueryOptions;
}
Sources: packages/shared-types/src/index.ts:7-22
Implementation Roadmap
The project follows a five-phase sprint plan to move from foundation to a polished product.
- Foundation: Establishing the monorepo, PNPM workspaces, and core SDK.
- MCP Integration: Building the connector service and implementing GitHub/Linear integrations.
- Narrative Engine: Integrating LLMs and building the prompt engineering system for context injection.
- Frontend & Story Logic: Developing the Next.js UI and the state machine for story progression.
- Polish: Integration testing and performance optimization.
Sources: README.md:77-101
Conclusion
The MCP Games Monorepo serves as a blueprint for the next generation of AI agents. By combining the Model Context Protocol with dynamic narrative generation, the project creates an ecosystem where software and storytelling converge. The architecture's reliance on a unified monorepo and shared type system allows for rapid iteration across diverse technological stacks (Next.js, Express, FastAPI), ensuring that the vision of "unrestricted OmniAgents" is built on a robust, scalable foundation.