mcp-server-architecture.md•28.9 kB
# EuConquisto Composer MCP Server - Architecture v5.2.0
**Version**: v5.2.0 FULLY OPERATIONAL
**Date**: January 12, 2025
**Status**: ✅ FULLY OPERATIONAL - Complete MCP Architecture
**Sync**: EuConquisto Composer MCP v5.2.0
**Architecture**: JIT Workflow with Exact API Compliance
## 🏗 Architecture Overview
The EuConquisto Composer MCP Server implements a lightweight, standards-compliant Model Context Protocol (MCP) server that provides educational widget analysis and Composer platform integration capabilities. The architecture follows MCP specifications while maintaining simplicity, performance, and extensibility.
### 🎯 Design Principles
- **MCP Compliance**: Full adherence to Anthropic's MCP specification
- **Minimal Dependencies**: Lightweight implementation with focused scope
- **Performance First**: Sub-100ms response times for all operations
- **Type Safety**: Complete TypeScript implementation with strict typing
- **Educational Focus**: Specialized for educational content analysis and creation
## 📊 System Architecture
### High-Level Architecture Diagram
```
┌─────────────────────────────────────────────────────────────┐
│ Claude Desktop │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ User Interface │ │
│ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │
│ │ │Test Connect │ │Widget Info │ │Composer URL │ │ │
│ │ └─────────────┘ └─────────────┘ └─────────────┘ │ │
│ └─────────────────────────────────────────────────────┘ │
└─────────────────────────┬───────────────────────────────────┘
│ JSON-RPC 2.0 over STDIO
│
┌─────────────────────────▼───────────────────────────────────┐
│ EuConquisto Composer MCP Server │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ MCP Protocol Layer │ │
│ │ ┌──────────────┐ ┌──────────────┐ ┌─────────────┐ │ │
│ │ │ Server │ │ Transport │ │ Content │ │ │
│ │ │ Capabilities │ │ Handler │ │ Handler │ │ │
│ │ └──────────────┘ └──────────────┘ └─────────────┘ │ │
│ └─────────────────────────────────────────────────────┘ │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ Tool Layer │ │
│ │ ┌──────────────┐ ┌──────────────┐ ┌─────────────┐ │ │
│ │ │test-connection│ │get-widget-info│ │get-composer-│ │ │
│ │ │ │ │ │ │ url │ │ │
│ │ └──────────────┘ └──────────────┘ └─────────────┘ │ │
│ └─────────────────────────────────────────────────────┘ │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ Business Logic Layer │ │
│ │ ┌──────────────┐ ┌──────────────┐ ┌─────────────┐ │ │
│ │ │ Widget │ │ Analysis │ │ JWT │ │ │
│ │ │ Analysis │ │ Engine │ │ Generator │ │ │
│ │ └──────────────┘ └──────────────┘ └─────────────┘ │ │
│ └─────────────────────────────────────────────────────┘ │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ Data Layer │ │
│ │ ┌──────────────┐ ┌──────────────┐ ┌─────────────┐ │ │
│ │ │ Widget │ │ Template │ │ Auth Token │ │ │
│ │ │ Definitions │ │ Data │ │ Store │ │ │
│ │ └──────────────┘ └──────────────┘ └─────────────┘ │ │
│ └─────────────────────────────────────────────────────┘ │
└─────────────────────────┬───────────────────────────────────┘
│ HTTPS REST API
│
┌─────────────────────────▼───────────────────────────────────┐
│ EuConquisto Composer Platform │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ composer.euconquisto.com │ │
│ │ ┌──────────────┐ ┌──────────────┐ ┌─────────────┐ │ │
│ │ │ Widget │ │ Course │ │ Template │ │ │
│ │ │ Library │ │ Builder │ │ Library │ │ │
│ │ └──────────────┘ └──────────────┘ └─────────────┘ │ │
│ └─────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
```
### Architecture Layers
#### 1. **MCP Protocol Layer**
- **Server Capabilities**: Advertises available tools and features
- **Transport Handler**: Manages STDIO communication with Claude Desktop
- **Content Handler**: Formats responses according to MCP content specification
#### 2. **Tool Layer**
- **test-connection**: Server health and status validation
- **get-widget-info**: Educational widget analysis retrieval
- **get-composer-url**: Authenticated URL generation for Composer access
#### 3. **Business Logic Layer**
- **Widget Analysis**: Educational widget metadata and capability analysis
- **Analysis Engine**: Widget property extraction and classification
- **JWT Generator**: Secure token generation for Composer authentication
#### 4. **Data Layer**
- **Widget Definitions**: Static analysis data for 6 educational widget types
- **Template Data**: Pre-analyzed widget templates and examples
- **Auth Token Store**: JWT token configuration and secrets
## 🔧 Component Architecture
### Core Components
#### MCP Server Implementation
```typescript
// Core server setup
const server = new McpServer({
name: "euconquisto-composer",
version: "0.1.3",
description: "EuConquisto Composer MCP Server - Educational Widget Analysis"
});
// Transport layer
const transport = new StdioServerTransport();
await server.connect(transport);
```
**Responsibilities**:
- MCP protocol compliance
- Tool registration and management
- Request/response handling
- Error management and logging
#### Tool Implementation Pattern
```typescript
server.tool(
"tool-name",
{
// Zod schema for parameter validation
param: z.string().describe("Parameter description")
},
async (params) => {
// Business logic
const result = await processRequest(params);
// MCP-compliant response format
return {
content: [{
type: "text",
text: JSON.stringify(result, null, 2)
}]
};
}
);
```
**Features**:
- Type-safe parameter validation with Zod
- Async operation support
- Consistent error handling
- MCP content format compliance
### Widget Analysis Engine
#### Widget Data Structure
```typescript
interface WidgetAnalysis {
widget: string; // Widget identifier
type: string; // Portuguese type name
status: "completed"; // Analysis status
properties: number; // Property count
subtypes: number; // Subtype variations
examples: string[]; // Template examples
special?: string; // Special features
description: string; // Human description
analysisComplete: boolean; // Completion flag
}
```
#### Analysis Implementation
```typescript
const analyzeWidget = (widgetType: string): WidgetAnalysis => {
const widgetDefinitions = {
text: {
type: "texto",
properties: 8,
subtypes: 9,
description: "Rich text formatting with multiple text types",
special: "Supports rich text formatting and multiple text styles"
},
// ... other widget definitions
};
return {
success: true,
widget: widgetType,
...widgetDefinitions[widgetType],
message: `Widget analysis retrieved for ${widgetType}`,
analysisComplete: true
};
};
```
### JWT Authentication System
#### Token Generation Architecture
```typescript
interface JWTPayload {
email: string;
name: string;
oid: string; // Organization ID
directory: string; // Directory ID
apim: string; // API Management ID
dirn: string; // Directory name
role: string[]; // User roles
dcn: string[]; // Data center nodes
scp: string[]; // Scopes
nbf: number; // Not before
exp: number; // Expiration
iat: number; // Issued at
iss: string; // Issuer
aud: string; // Audience
}
```
#### URL Generation Process
```typescript
const generateComposerUrl = (path: string = "home"): ComposerUrlResponse => {
const organizationId = "36c92686-c494-ec11-a22a-dc984041c95d";
const jwtToken = generateJWTToken();
const embedURL = `https://composer.euconquisto.com/#/embed/auth-with-token/pt_br/${path}/${organizationId}/${jwtToken}`;
return {
success: true,
embedURL,
path,
message: "🔗 Composer embed URL with JWT authentication",
usage: "Open this URL to access EuConquisto Composer with admin authentication",
authentication: "Admin-level access with development JWT token",
organization: "EuConquisto Development Environment"
};
};
```
## 📡 Communication Protocols
### MCP Protocol Implementation
#### Transport Layer: STDIO
```typescript
// STDIO transport configuration
const transport = new StdioServerTransport();
// Message handling
transport.onrequest = async (request) => {
// JSON-RPC 2.0 message processing
return await processRequest(request);
};
```
#### Message Format: JSON-RPC 2.0
```json
// Request format
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "tool-name",
"arguments": {
"param": "value"
}
}
}
// Response format
{
"result": {
"content": [{
"type": "text",
"text": "JSON response data"
}]
},
"jsonrpc": "2.0",
"id": 1
}
```
### Content Format Specification
#### MCP Content Structure
```typescript
interface MCPContent {
type: "text";
text: string; // JSON-serialized response data
}
interface MCPResponse {
content: MCPContent[];
}
```
#### Response Data Format
```typescript
// All tool responses follow this pattern
const toolResponse = {
success: boolean; // Operation success flag
message: string; // Human-readable message
[key: string]: any; // Tool-specific data
};
// Wrapped in MCP content format
return {
content: [{
type: "text",
text: JSON.stringify(toolResponse, null, 2)
}]
};
```
## 🎯 Tool Architecture
### Tool Registration System
#### Tool Definition Structure
```typescript
interface ToolDefinition {
name: string; // Tool identifier
description: string; // Tool description
parameters: ZodSchema; // Parameter validation schema
handler: ToolHandler; // Implementation function
}
```
#### Parameter Validation with Zod
```typescript
// Example: get-widget-info tool parameters
const widgetInfoParameters = z.object({
widget: z.enum(["text", "image", "header", "list", "gallery", "hotspot"])
.describe("Widget type to analyze")
});
// Type inference
type WidgetInfoParams = z.infer<typeof widgetInfoParameters>;
```
### Tool Implementation Patterns
#### Standard Tool Pattern
```typescript
const implementTool = (
name: string,
parameters: ZodSchema,
handler: (params: any) => Promise<any>
) => {
server.tool(name, parameters, async (params) => {
try {
const result = await handler(params);
return {
content: [{
type: "text",
text: JSON.stringify(result, null, 2)
}]
};
} catch (error) {
return {
content: [{
type: "text",
text: JSON.stringify({
success: false,
error: error.message,
message: "An error occurred processing the request"
}, null, 2)
}]
};
}
});
};
```
#### Error Handling Pattern
```typescript
const handleToolError = (error: Error, toolName: string) => {
const errorResponse = {
success: false,
error: error.name,
message: error.message,
tool: toolName,
timestamp: new Date().toISOString()
};
return {
content: [{
type: "text",
text: JSON.stringify(errorResponse, null, 2)
}]
};
};
```
## 📊 Data Architecture
### Widget Analysis Data Model
#### Widget Type Definitions
```typescript
const WIDGET_DEFINITIONS = {
text: {
type: "texto",
properties: 8,
subtypes: 9,
description: "Rich text formatting with multiple text types",
special: "Supports rich text formatting and multiple text styles"
},
image: {
type: "imagem",
properties: 12,
subtypes: 5,
description: "Image display with zoom and gallery capabilities",
special: "Zoom capabilities and gallery integration"
},
header: {
type: "cabecalho",
properties: 44,
subtypes: 6,
examples: ["template-1", "template-2", "template-3"],
description: "Header sections with background media, categories, and author info",
special: "Template 3 includes SCORM LMS integration"
},
list: {
type: "lista",
properties: 10,
subtypes: 3,
description: "Numbered, bullet, and checkbox list options",
special: "Supports numbered, bullet, and checkbox list formats"
},
gallery: {
type: "galeria",
properties: 10,
subtypes: 1,
description: "Image gallery with slideshow functionality",
special: "Slideshow functionality with navigation controls"
},
hotspot: {
type: "hotspot",
properties: 15,
subtypes: 1,
description: "Interactive hotspot overlays with 25+ icon options",
special: "25+ interactive icons with overlay support"
}
} as const;
```
#### Analysis Result Structure
```typescript
interface AnalysisResult {
analyzed: number; // Total widgets analyzed
completed: string[]; // Completed widget names
validation: string; // Validation status
}
const ANALYSIS_SUMMARY: AnalysisResult = {
analyzed: 6,
completed: ["Text", "Image", "Header", "List", "Gallery", "Hotspot Interactive"],
validation: "Ready for widget creation testing"
};
```
### Authentication Data Model
#### JWT Configuration
```typescript
interface JWTConfig {
organizationId: string;
secretKey: string; // For token signing
expirationTime: number; // Token lifetime in seconds
issuer: string; // Token issuer
audience: string; // Token audience
}
const JWT_CONFIG: JWTConfig = {
organizationId: "36c92686-c494-ec11-a22a-dc984041c95d",
secretKey: "[DEVELOPMENT_SECRET]",
expirationTime: 2592000, // 30 days
issuer: "https://api.digitalpages.com.br",
audience: "EuConquisto"
};
```
## 🚀 Performance Architecture
### Response Time Optimization
#### Caching Strategy
```typescript
// In-memory cache for widget definitions
const widgetCache = new Map<string, WidgetAnalysis>();
const getCachedWidget = (widgetType: string): WidgetAnalysis => {
if (!widgetCache.has(widgetType)) {
widgetCache.set(widgetType, analyzeWidget(widgetType));
}
return widgetCache.get(widgetType)!;
};
```
#### Async Processing Pattern
```typescript
// Non-blocking tool implementation
const processToolRequest = async (toolName: string, params: any): Promise<any> => {
return new Promise((resolve) => {
// Immediate processing for simple operations
setImmediate(() => {
const result = processRequest(toolName, params);
resolve(result);
});
});
};
```
### Memory Management
#### Resource Optimization
```typescript
// Minimal memory footprint
const optimizeMemoryUsage = () => {
// Use const definitions to prevent runtime allocation
// Leverage object freezing for immutable data
Object.freeze(WIDGET_DEFINITIONS);
// Implement lazy loading for expensive operations
const lazyLoadAnalysis = (widgetType: string) => {
return () => WIDGET_DEFINITIONS[widgetType];
};
};
```
## 🔒 Security Architecture
### Authentication Security
#### JWT Token Security
```typescript
interface SecurityConfig {
tokenExpiration: number; // Token lifetime
secretRotation: boolean; // Secret key rotation
audienceValidation: boolean; // Audience validation
httpsEnforcement: boolean; // HTTPS requirement
}
const SECURITY_CONFIG: SecurityConfig = {
tokenExpiration: 2592000, // 30 days
secretRotation: false, // Development mode
audienceValidation: true, // Validate audience
httpsEnforcement: true // Require HTTPS
};
```
#### URL Security
```typescript
const generateSecureUrl = (path: string): string => {
// Validate path parameter
const sanitizedPath = path.replace(/[^a-zA-Z0-9-_]/g, '');
// Enforce HTTPS
const baseUrl = "https://composer.euconquisto.com";
// Generate secure JWT with expiration
const jwt = generateJWTWithExpiration();
return `${baseUrl}/#/embed/auth-with-token/pt_br/${sanitizedPath}/${organizationId}/${jwt}`;
};
```
### Input Validation
#### Parameter Sanitization
```typescript
// Zod-based validation with sanitization
const sanitizeInput = z.object({
widget: z.enum(["text", "image", "header", "list", "gallery", "hotspot"])
.transform(val => val.toLowerCase().trim()),
path: z.string()
.max(100)
.regex(/^[a-zA-Z0-9-_]+$/)
.optional()
.default("home")
});
```
## 📈 Scalability Architecture
### Horizontal Scaling Considerations
#### Stateless Design
```typescript
// Stateless tool implementations
const statelessToolHandler = (params: any) => {
// No shared state - each request is independent
// All data comes from immutable definitions
// No side effects or persistent state changes
return processRequest(params);
};
```
#### Resource Efficiency
```typescript
// Efficient resource usage patterns
const efficientProcessing = {
// Minimize object creation
reuseObjects: true,
// Use streaming for large responses
streamingSupport: false, // Not needed for current data sizes
// Implement connection pooling for external APIs
connectionPooling: false, // Not needed for current implementation
// Cache expensive computations
computationCaching: true
};
```
### Performance Monitoring
#### Metrics Collection
```typescript
interface PerformanceMetrics {
responseTime: number; // Response time in ms
memoryUsage: number; // Memory usage in MB
requestCount: number; // Total requests processed
errorRate: number; // Error percentage
}
const collectMetrics = (): PerformanceMetrics => {
return {
responseTime: process.hrtime.bigint(),
memoryUsage: process.memoryUsage().rss / 1024 / 1024,
requestCount: global.requestCounter || 0,
errorRate: (global.errorCounter || 0) / (global.requestCounter || 1)
};
};
```
## 🔧 Build and Deployment Architecture
### Build System Configuration
#### TypeScript Configuration
```json
// tsconfig-minimal.json - Optimized for reliability
{
"compilerOptions": {
"target": "ES2022",
"module": "ESNext",
"moduleResolution": "node",
"outDir": "./dist",
"strict": true,
"esModuleInterop": true,
"skipLibCheck": true,
"forceConsistentCasingInFileNames": true
},
"include": ["src/index.ts"],
"exclude": [
"src/core/**/*",
"src/interfaces/**/*",
"src/educational/**/*"
]
}
```
#### Build Process
```bash
# Optimized build command
npm run build:minimal
# Build steps:
# 1. TypeScript compilation with minimal config
# 2. Output to dist/index.js
# 3. Source map generation for debugging
# 4. Type definition generation
```
### Deployment Architecture
#### Local Deployment
```json
// Claude Desktop configuration
{
"mcpServers": {
"euconquisto-composer": {
"command": "node",
"args": ["/absolute/path/to/dist/index.js"],
"env": {
"NODE_ENV": "production"
}
}
}
}
```
#### Production Considerations
```typescript
interface DeploymentConfig {
environment: "development" | "production";
logging: boolean;
errorReporting: boolean;
performanceMonitoring: boolean;
}
const DEPLOYMENT_CONFIG: DeploymentConfig = {
environment: process.env.NODE_ENV as any || "development",
logging: true,
errorReporting: true,
performanceMonitoring: true
};
```
## 📊 Quality Architecture
### Code Quality Standards
#### TypeScript Strictness
```typescript
// Strict typing enforcement
interface StrictTyping {
noImplicitAny: true;
strictNullChecks: true;
strictFunctionTypes: true;
noImplicitReturns: true;
noFallthroughCasesInSwitch: true;
}
```
#### Error Handling Standards
```typescript
class MCPServerError extends Error {
constructor(
message: string,
public code: string,
public toolName?: string
) {
super(message);
this.name = "MCPServerError";
}
}
const handleError = (error: unknown, context: string): never => {
if (error instanceof MCPServerError) {
throw error;
}
throw new MCPServerError(
`Unexpected error in ${context}: ${error}`,
"INTERNAL_ERROR",
context
);
};
```
### Testing Architecture
#### Unit Testing Structure
```typescript
// Test organization
describe("EuConquisto MCP Server", () => {
describe("Tool Functions", () => {
describe("test-connection", () => {
it("should return server status", () => {
// Test implementation
});
});
describe("get-widget-info", () => {
it("should return widget analysis", () => {
// Test implementation
});
});
describe("get-composer-url", () => {
it("should generate valid URLs", () => {
// Test implementation
});
});
});
});
```
## 📋 Architecture Decision Records (ADRs)
### ADR-001: MCP Protocol Compliance
**Decision**: Use official Anthropic MCP SDK with strict protocol compliance
**Rationale**: Ensures compatibility with Claude Desktop and future MCP developments
**Consequences**: Requires adherence to JSON-RPC 2.0 and MCP content format specifications
### ADR-002: STDIO Transport Selection
**Decision**: Implement STDIO transport instead of HTTP/WebSocket
**Rationale**: Required by Claude Desktop for local MCP server integration
**Consequences**: Server runs as child process of Claude Desktop
### ADR-003: TypeScript with Zod Validation
**Decision**: Use TypeScript with Zod for runtime type validation
**Rationale**: Provides compile-time and runtime type safety
**Consequences**: Requires schema definitions for all tool parameters
### ADR-004: Minimal Build Configuration
**Decision**: Use minimal TypeScript configuration excluding complex modules
**Rationale**: Ensures reliable compilation and reduces build complexity
**Consequences**: Some advanced features excluded but core functionality preserved
### ADR-005: Static Widget Analysis
**Decision**: Use static widget definitions instead of dynamic API calls
**Rationale**: Ensures fast response times and reduces external dependencies
**Consequences**: Widget data must be updated manually when Composer changes
## 🔮 Future Architecture Considerations
### Extensibility Points
#### Plugin Architecture
```typescript
interface ToolPlugin {
name: string;
description: string;
parameters: ZodSchema;
handler: ToolHandler;
}
const registerPlugin = (plugin: ToolPlugin) => {
server.tool(plugin.name, plugin.parameters, plugin.handler);
};
```
#### Configuration Management
```typescript
interface ServerConfiguration {
tools: {
enabled: string[];
disabled: string[];
};
performance: {
caching: boolean;
timeout: number;
};
security: {
tokenExpiration: number;
rateLimiting: boolean;
};
}
```
### Integration Expansion
#### Additional MCP Primitives
```typescript
// Future: MCP Resources implementation
server.resource(
"widget-templates",
new ResourceTemplate("widget://{type}/template/{id}"),
async (uri, params) => {
// Resource handler implementation
}
);
// Future: MCP Prompts implementation
server.prompt(
"educational-content-creator",
{
topic: z.string(),
difficulty: z.enum(["beginner", "intermediate", "advanced"])
},
async (params) => {
// Prompt handler implementation
}
);
```
---
## 📜 Document Information
**Document Version**: 1.0
**Architecture Version**: v0.1.3
**Creation Date**: 2025-06-09
**Last Updated**: 2025-06-09
**Review Status**: Phase 3 Documentation Complete
**Architecture Style**: MCP-Compliant Microservice
**Compliance Level**: Full MCP Specification
**Performance Target**: <100ms Response Time ✅
**Security Level**: JWT Authentication with HTTPS ✅
**Dependencies**: TASK-F002 Phase 2 Complete
**Validation**: Architecture Implemented and Tested ✅
**Quality Gate**: Architecture Documentation Complete
---
*EuConquisto Composer MCP Server PoC - Complete Architecture Documentation*
*TASK-F002 Phase 3 Documentation | Implementation Patterns & Design Decisions | © 2025 EuConquisto Development Team*