MCP SDK Documentation
Relevant source files
The following files were used as context for generating this wiki page:
The Model Context Protocol (MCP) SDK is a custom TypeScript client library designed to facilitate semantic querying and connection management with various MCP servers, such as GitHub, Linear, and Notion. It serves as the integration layer within the MCP Games monorepo, enabling AI agents to retrieve real-world context to drive dynamic, personalized Choose Your Own Adventure (CYOA) narratives.
The SDK provides a type-safe interface for managing connection pooling, executing semantic queries with a fluent API, and optimizing performance through built-in caching and retry logic. It is utilized primarily by the mcp-connector service to aggregate user data for the narrative generation engine.
Sources: README.md:15-20, packages/mcp-sdk/README.md:1-12
Core Architecture
The MCP SDK is structured around two primary classes: MCPClient for operational management and SemanticQueryBuilder for request construction. It relies heavily on shared-types to ensure protocol consistency across the monorepo.
MCPClient
The MCPClient is the central orchestrator responsible for maintaining active server connections and handling the execution of queries. It manages an internal connection pool using a Map and implements a local cache for query results.
The diagram above illustrates the relationship between the client manager and the query builder.
Sources: packages/mcp-sdk/src/index.ts:18-124
Connection Management
The SDK supports multiple connection types, ranging from standard productivity tools to custom implementations.
Supported Connection Types
| Type | Description |
|---|---|
github | Integration for repository and contribution data |
linear | Integration for project management and issue tracking |
notion | Integration for workspace and document context |
filesystem | Local file system access |
custom | Generic implementation for additional MCP servers |
Sources: packages/shared-types/src/index.ts:7-13
Connection Lifecycle
Connections are initialized with specific configurations, including server URLs and authentication tokens. The MCPClient tracks the status of these connections as connected, disconnected, or error.
This flow represents how the SDK manages the lifecycle of an MCP server connection.
Sources: packages/mcp-sdk/src/index.ts:35-71, packages/shared-types/src/index.ts:14-15
Semantic Querying
The SDK utilizes a "Semantic Query" pattern, allowing the system to query data sources based on natural language intent rather than strict schema lookups.
SemanticQueryBuilder
The SemanticQueryBuilder provides a fluent API to construct complex queries. It requires at least a target server and a query string to produce a valid SemanticQuery object.
// Example from packages/mcp-sdk/README.md
const query = new SemanticQueryBuilder()
.server('github')
.query('recent repositories and contributions')
.filter('timeframe', '30days')
.maxResults(10)
.build();
Sources: packages/mcp-sdk/src/index.ts:130-176, packages/mcp-sdk/README.md:27-33
Execution Logic and Caching
When executeQuery is called, the SDK follows a specific resolution path:
- Cache Check: If
cacheEnabledis true, it generates a cache key based on the server, query text, and filters. - Execution: If not cached, it executes the query (implementation pending actual MCP protocol transport).
- Result Metadata: Every result includes metadata regarding the source, timestamp, and whether it was retrieved from the cache.
This sequence shows the internal logic for query resolution and the role of the caching layer.
Sources: packages/mcp-sdk/src/index.ts:76-114
Data Structures
The SDK relies on shared interfaces to ensure type safety between the client and the mcp-connector.
Configuration Options
The MCPClient is initialized with an MCPClientConfig object.
| Field | Type | Default | Description |
|---|---|---|---|
defaultTimeout | number | 5000 | Request timeout in milliseconds |
cacheEnabled | boolean | true | Toggles the internal query cache |
retryAttempts | number | 3 | Number of retries for failed requests |
Sources: packages/mcp-sdk/src/index.ts:23-32, packages/mcp-sdk/src/index.ts:178-182
Query Result Schema
Results are wrapped in a generic QueryResult<T> interface.
| Field | Type | Description |
|---|---|---|
data | T | The actual data payload from the MCP server |
metadata.source | string | The ID of the server that provided the data |
metadata.timestamp | string | ISO timestamp of the query execution |
metadata.cached | boolean | Indicates if the result came from the local cache |
Sources: packages/shared-types/src/index.ts:41-48
Summary
The MCP SDK provides the foundational infrastructure for semantic data retrieval in the MCP Games ecosystem. By abstracting the complexities of connection management, retries, and caching, it allows the higher-level narrative services to focus on transforming raw context into interactive story elements. Its integration with shared-types ensures that as new MCP servers are added to the mcp-connector, the SDK remains a consistent, type-safe interface for all services in the monorepo.