mcp-server.tsā¢12.6 kB
/**
* EuConquisto Composer MCP Server - MCP Server Interface
*
* @version 0.1.0
* @created 2025-06-08
* @updated 2025-06-08
* @author EuConquisto Development Team
*
* @description TypeScript interfaces for the Model-Context-Protocol (MCP) server
* implementation, including server configuration, request/response handling,
* and communication protocols.
*
* @testStatus PENDING
* @coverage 0%
*
* @dependencies
* - TypeScript 5.0+
* - Node.js types
* - content-elements.ts
*
* @supersedes N/A
* @supersededBy N/A
*/
import { ContentElementType, ContentComposition, ValidationResult, ExportResult } from './content-elements';
// Core MCP Server Interfaces
export interface MCPServerConfig {
name: string;
version: string;
description?: string;
port: number;
host: string;
protocol: 'http' | 'https' | 'ws' | 'wss';
timeout: number;
maxConnections: number;
authentication: AuthenticationConfig;
logging: LoggingConfig;
cors: CORSConfig;
rateLimit: RateLimitConfig;
}
export interface AuthenticationConfig {
enabled: boolean;
providers: string[];
sessionTimeout: number;
tokenExpiration: number;
refreshEnabled: boolean;
requireHttps: boolean;
}
export interface LoggingConfig {
level: 'debug' | 'info' | 'warn' | 'error';
console: boolean;
file: {
enabled: boolean;
path: string;
maxSize: string;
maxFiles: number;
};
structured: boolean;
includeRequestId: boolean;
}
export interface CORSConfig {
enabled: boolean;
origins: string[];
methods: string[];
headers: string[];
credentials: boolean;
}
export interface RateLimitConfig {
enabled: boolean;
windowMs: number;
maxRequests: number;
skipSuccessfulRequests: boolean;
skipFailedRequests: boolean;
}
// MCP Protocol Interfaces
export interface MCPRequest {
id: string;
method: string;
params: Record<string, any>;
timestamp: string;
userId?: string;
sessionId?: string;
metadata?: Record<string, any>;
}
export interface MCPResponse {
id: string;
success: boolean;
result?: any;
error?: MCPError;
timestamp: string;
duration: number;
metadata?: Record<string, any>;
}
export interface MCPError {
code: string;
message: string;
details?: Record<string, any>;
stack?: string;
}
// Server Implementation Interfaces
export interface MCPServerCore {
config: MCPServerConfig;
start(): Promise<void>;
stop(): Promise<void>;
handleRequest(request: MCPRequest): Promise<MCPResponse>;
validateRequest(request: MCPRequest): ValidationResult;
isHealthy(): boolean;
getMetrics(): ServerMetrics;
}
export interface ServerMetrics {
uptime: number;
requestCount: number;
errorCount: number;
averageResponseTime: number;
activeConnections: number;
memoryUsage: {
used: number;
total: number;
percentage: number;
};
cpuUsage: number;
}
// Request Handler Interfaces
export interface RequestHandler {
method: string;
handler: (params: any, context: RequestContext) => Promise<any>;
validation?: ValidationRule[];
authentication?: boolean;
rateLimit?: RateLimitOptions;
}
export interface RequestContext {
requestId: string;
userId?: string;
sessionId?: string;
timestamp: string;
userAgent?: string;
ipAddress?: string;
metadata: Record<string, any>;
}
export interface ValidationRule {
field: string;
type: 'required' | 'string' | 'number' | 'boolean' | 'object' | 'array' | 'email' | 'url';
min?: number;
max?: number;
pattern?: string;
enum?: any[];
custom?: (value: any) => boolean;
message?: string;
}
export interface RateLimitOptions {
windowMs?: number;
maxRequests?: number;
skipSuccessfulRequests?: boolean;
}
// Content Management API Interfaces
export interface ContentAPI {
// Element Management
createElement(type: string, config: any, context: RequestContext): Promise<ContentElementType>;
getElement(id: string, context: RequestContext): Promise<ContentElementType>;
updateElement(id: string, updates: any, context: RequestContext): Promise<ContentElementType>;
deleteElement(id: string, context: RequestContext): Promise<boolean>;
listElements(filters?: ElementFilters, context?: RequestContext): Promise<ElementList>;
// Composition Management
createComposition(config: any, context: RequestContext): Promise<ContentComposition>;
getComposition(id: string, context: RequestContext): Promise<ContentComposition>;
updateComposition(id: string, updates: any, context: RequestContext): Promise<ContentComposition>;
deleteComposition(id: string, context: RequestContext): Promise<boolean>;
listCompositions(filters?: CompositionFilters, context?: RequestContext): Promise<CompositionList>;
// Validation
validateElement(element: ContentElementType, context: RequestContext): Promise<ValidationResult>;
validateComposition(composition: ContentComposition, context: RequestContext): Promise<ValidationResult>;
// Export
exportComposition(id: string, format: string, options: any, context: RequestContext): Promise<ExportResult>;
}
export interface ElementFilters {
type?: string;
tags?: string[];
createdBy?: string;
dateRange?: {
start: string;
end: string;
};
status?: string;
search?: string;
limit?: number;
offset?: number;
sortBy?: string;
sortOrder?: 'asc' | 'desc';
}
export interface ElementList {
elements: ContentElementType[];
total: number;
limit: number;
offset: number;
hasMore: boolean;
}
export interface CompositionFilters {
tags?: string[];
category?: string;
difficulty?: string;
createdBy?: string;
status?: string;
dateRange?: {
start: string;
end: string;
};
search?: string;
limit?: number;
offset?: number;
sortBy?: string;
sortOrder?: 'asc' | 'desc';
}
export interface CompositionList {
compositions: ContentComposition[];
total: number;
limit: number;
offset: number;
hasMore: boolean;
}
// Educational API Interfaces
export interface EducationalAPI {
// Course Management
generateCourse(specification: CourseSpecification, context: RequestContext): Promise<GeneratedCourse>;
buildLessonPlan(topic: string, objectives: string[], context: RequestContext): Promise<LessonPlan>;
createAssessment(type: string, parameters: AssessmentParameters, context: RequestContext): Promise<Assessment>;
// Content Generation
generateContent(prompt: string, type: string, constraints: any, context: RequestContext): Promise<GeneratedContent>;
enhanceContent(elementId: string, enhancements: string[], context: RequestContext): Promise<ContentElementType>;
// Learning Analytics
analyzeProgress(userId: string, compositionId: string, context: RequestContext): Promise<ProgressAnalysis>;
recommendContent(userId: string, preferences: any, context: RequestContext): Promise<ContentRecommendation[]>;
}
export interface CourseSpecification {
title: string;
description: string;
objectives: string[];
targetAudience: string;
difficulty: string;
estimatedDuration: number;
topics: string[];
assessmentTypes: string[];
interactivity: 'low' | 'medium' | 'high';
multimedia: boolean;
}
export interface GeneratedCourse {
id: string;
specification: CourseSpecification;
structure: CourseStructure;
lessons: LessonPlan[];
assessments: Assessment[];
resources: CourseResource[];
metadata: CourseMetadata;
}
export interface CourseStructure {
modules: CourseModule[];
prerequisites: string[];
learningPath: string[];
estimatedDuration: number;
}
export interface CourseModule {
id: string;
title: string;
description: string;
objectives: string[];
lessons: string[];
assessments: string[];
order: number;
}
export interface LessonPlan {
id: string;
title: string;
description: string;
objectives: string[];
duration: number;
activities: LessonActivity[];
resources: LessonResource[];
assessment?: string;
}
export interface LessonActivity {
id: string;
type: 'reading' | 'video' | 'interactive' | 'discussion' | 'practice' | 'reflection';
title: string;
description: string;
duration: number;
content: ContentElementType;
instructions?: string;
}
export interface LessonResource {
id: string;
type: 'document' | 'link' | 'media' | 'tool';
title: string;
description?: string;
url?: string;
content?: ContentElementType;
}
export interface Assessment {
id: string;
type: 'quiz' | 'assignment' | 'project' | 'peer-review' | 'self-assessment';
title: string;
description: string;
instructions: string;
rubric?: AssessmentRubric;
timeLimit?: number;
attempts?: number;
passingScore?: number;
weight: number;
content: ContentElementType;
}
export interface AssessmentParameters {
type: string;
topic: string;
difficulty: string;
questionCount: number;
timeLimit?: number;
objectives: string[];
}
export interface AssessmentRubric {
criteria: RubricCriterion[];
scoringMethod: 'points' | 'percentage' | 'letter' | 'passfail';
maxScore: number;
}
export interface RubricCriterion {
id: string;
name: string;
description: string;
weight: number;
levels: RubricLevel[];
}
export interface RubricLevel {
id: string;
name: string;
description: string;
points: number;
}
export interface GeneratedContent {
element: ContentElementType;
alternatives?: ContentElementType[];
metadata: {
prompt: string;
model: string;
timestamp: string;
confidence: number;
};
}
export interface ProgressAnalysis {
userId: string;
compositionId: string;
progress: {
completion: number;
timeSpent: number;
activitiesCompleted: number;
totalActivities: number;
averageScore?: number;
};
strengths: string[];
weaknesses: string[];
recommendations: string[];
nextSteps: string[];
}
export interface ContentRecommendation {
elementId: string;
type: string;
title: string;
description: string;
relevanceScore: number;
difficulty: string;
estimatedDuration: number;
reasons: string[];
}
export interface CourseResource {
id: string;
type: 'reading' | 'video' | 'audio' | 'interactive' | 'tool' | 'reference';
title: string;
description?: string;
url?: string;
content?: ContentElementType;
tags: string[];
}
export interface CourseMetadata {
created: string;
updated: string;
createdBy: string;
version: string;
status: 'draft' | 'review' | 'published' | 'archived';
tags: string[];
analytics?: {
enrollments: number;
completions: number;
averageRating: number;
averageCompletionTime: number;
};
}
// Server Events and Webhooks
export interface ServerEvent {
id: string;
type: string;
timestamp: string;
source: string;
data: Record<string, any>;
userId?: string;
sessionId?: string;
}
export interface WebhookConfig {
url: string;
events: string[];
secret?: string;
retryAttempts: number;
timeout: number;
active: boolean;
}
export interface WebhookDelivery {
id: string;
webhookId: string;
event: ServerEvent;
status: 'pending' | 'delivered' | 'failed' | 'retrying';
attempts: number;
lastAttempt?: string;
response?: {
status: number;
headers: Record<string, string>;
body: string;
};
}
// Plugin and Extension Interfaces
export interface MCPPlugin {
name: string;
version: string;
description?: string;
initialize(server: MCPServerCore): Promise<void>;
cleanup(): Promise<void>;
getHandlers(): RequestHandler[];
getConfig(): PluginConfig;
}
export interface PluginConfig {
enabled: boolean;
settings: Record<string, any>;
dependencies?: string[];
permissions?: string[];
}
// Utility Types
export type MCPMethod = 'createElement' | 'getElement' | 'updateElement' | 'deleteElement' |
'listElements' | 'createComposition' | 'getComposition' | 'updateComposition' |
'deleteComposition' | 'listCompositions' | 'validateElement' | 'validateComposition' |
'exportComposition' | 'generateCourse' | 'buildLessonPlan' | 'createAssessment' |
'generateContent' | 'analyzeProgress' | 'recommendContent';
export type ServerStatus = 'starting' | 'running' | 'stopping' | 'stopped' | 'error';
export type LogLevel = 'debug' | 'info' | 'warn' | 'error';
export type AuthProvider = 'jwt' | 'oauth' | 'apikey' | 'basic';
export type ContentType = 'text' | 'image' | 'video' | 'audio' | 'quiz' | 'interactive' | 'document';
export type AssessmentType = 'quiz' | 'assignment' | 'project' | 'peer-review' | 'self-assessment';
export type ActivityType = 'reading' | 'video' | 'interactive' | 'discussion' | 'practice' | 'reflection';