Semantic Query Engine
Relevant source files
The following files were used as context for generating this wiki page:
The Semantic Query Engine is a core system within the MCP Games ecosystem designed to retrieve, normalize, and aggregate context from Model Context Protocol (MCP) servers. Its primary purpose is to allow "unrestricted OmniAgents" to query external data sources—such as GitHub, Linear, and Notion—using natural language or semantic requests to personalize Choose Your Own Adventure (CYOA) narratives.
Sources: README.md:3-8, packages/mcp-sdk/README.md:1-5
By bridging the gap between raw external data and the narrative generation process, the engine ensures that story progression reflects real-world user activity, such as recent code contributions or project management updates.
Sources: README.md:144-162, apps/mcp-connector/README.md:3-10
Architecture and Components
The engine is distributed across the mcp-sdk package and the mcp-connector service. The SDK provides the client-side logic for building queries and managing connections, while the connector service acts as the integration layer that interfaces with various MCP servers.
Component Overview
| Component | Responsibility | Relevant Files |
|---|---|---|
| MCPClient | Manages server connections, executes queries, and handles caching. | packages/mcp-sdk/src/index.ts |
| SemanticQueryBuilder | Provides a fluent API for constructing type-safe semantic queries. | packages/mcp-sdk/src/index.ts |
| mcp-connector | REST API service that aggregates data from multiple MCP sources. | apps/mcp-connector/src/index.ts |
| shared-types | Defines the protocol contracts for queries, connections, and results. | packages/shared-types/src/index.ts |
Sources: packages/mcp-sdk/src/index.ts:18-20, apps/mcp-connector/src/index.ts:21-50, packages/shared-types/src/index.ts:1-50
System Data Flow
The following diagram illustrates how a semantic query originates from a user request and flows through the SDK to the connector and external MCP servers.
The diagram shows the sequence from query construction to data retrieval across the monorepo services.
Sources: README.md:144-160, packages/mcp-sdk/src/index.ts:66-100, apps/mcp-connector/src/index.ts:36-47
Data Models and Types
The engine relies on a strictly defined set of interfaces to ensure consistency across the TypeScript monorepo.
Semantic Query Structure
A query specifies the target server, the semantic intent, and optional filters for narrowing results.
export interface SemanticQuery {
server: string;
query: string;
filters?: QueryFilters;
options?: QueryOptions;
}
Sources: packages/shared-types/src/index.ts:21-26
Connection States
The engine tracks the status of various integrations to manage availability.
| Field | Type | Description |
|---|---|---|
id | string | Unique identifier for the connection (e.g., 'github'). |
type | enum | github, linear, notion, filesystem, or custom. |
status | enum | connected, disconnected, or error. |
config | MCPConfig | Contains serverUrl, authToken, and capabilities. |
Sources: packages/shared-types/src/index.ts:6-19
Core Implementation Logic
MCP Client and Query Execution
The MCPClient class in the mcp-sdk handles the lifecycle of a semantic request. It includes a built-in caching mechanism to optimize performance and reduce redundant calls to external APIs.
This sequence highlights the "Cache-First" logic implemented in the SDK to improve response times for narrative generation.
Sources: packages/mcp-sdk/src/index.ts:69-95, packages/mcp-sdk/README.md:7-14
Query Builder Fluent API
The SemanticQueryBuilder simplifies the creation of complex queries, ensuring that required fields like server and query are present before execution.
- server(serverId): Sets the target MCP integration.
- query(text): Defines the semantic search string (e.g., "recent repositories").
- filter(key, value): Adds metadata filters such as
timeframeorstatus. - cachePolicy(policy): Configures whether to use
cache-first,network-first, orno-cache.
Sources: packages/mcp-sdk/src/index.ts:114-160, packages/shared-types/src/index.ts:34-38
Service Integration (mcp-connector)
The mcp-connector service exposes RESTful endpoints that the SDK consumes. It is responsible for the actual communication with MCP servers and the aggregation of user context.
API Endpoints
| Endpoint | Method | Description |
|---|---|---|
/api/mcp/connections | GET | Returns a list of available and connected MCP integrations. |
/api/mcp/query | POST | Executes a semantic query against a specific server. |
/api/mcp/context/:userId | GET | Aggregates data from all connected MCPs for a specific user. |
Sources: apps/mcp-connector/src/index.ts:21-60, apps/mcp-connector/README.md:18-28
Context Aggregation
One of the critical functions of the engine is "User context aggregation." This process collects data from multiple sources (e.g., GitHub and Linear) to create a unified userContext object. This object is subsequently used by the narrative-ai service to generate personalized story scenes.
Sources: apps/mcp-connector/src/index.ts:50-59, README.md:154-162
Conclusion
The Semantic Query Engine acts as the data-retrieval backbone for the MCP Games ecosystem. By providing a type-safe SDK and a centralized connector service, it enables dynamic story progression based on real-world user data. Its use of caching, fluent query building, and multi-server support allows for scalable and context-aware narrative experiences.