@specverse/engine-realize 3.5.3

package/libs/instance-factories/tools/templates/mcp/static/src/controllers/MCPServerController.ts

@@ -0,0 +1,293 @@
+/**
+ * MCPServerController
+ * Clean implementation with only dynamic CLI tools
+ */
+
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { 
+  ListResourcesRequestSchema,
+  ReadResourceRequestSchema,
+  ListToolsRequestSchema,
+  CallToolRequestSchema 
+} from '@modelcontextprotocol/sdk/types.js';
+
+import { HybridResourcesProvider } from '../services/HybridResourcesProvider.js';
+import { CLIProxyService } from '../services/CLIProxyService.js';
+import { EntityModuleService } from '../services/EntityModuleService.js';
+import { EventEmitter } from '../events/EventEmitter.js';
+import type {
+  MCPServerConfig,
+  SpecVerseResource,
+  ServerStartedEvent,
+  ResourceRequestedEvent,
+  ErrorOccurredEvent
+} from '../types/index.js';
+
+export class MCPServerController {
+  private server: Server;
+  private config: MCPServerConfig;
+  private resourcesProvider: HybridResourcesProvider;
+  private cliProxy: CLIProxyService;
+  private entityModuleService: EntityModuleService;
+  private eventEmitter: EventEmitter;
+
+  constructor(config: MCPServerConfig) {
+    this.config = config;
+    this.eventEmitter = new EventEmitter();
+    
+    // Initialize server
+    this.server = new Server({
+      name: 'specverse-dynamic-cli',
+      version: '1.0.0'
+    }, {
+      capabilities: {
+        resources: {},
+        tools: {}
+      }
+    });
+
+    // Initialize services
+    this.resourcesProvider = new HybridResourcesProvider({
+      mode: 'auto',
+      resourcesPath: config.resources_path
+    });
+
+    // Initialize CLI proxy for dynamic command discovery - this is our main service!
+    this.cliProxy = new CLIProxyService();
+
+    // Initialize entity module service for metadata exposure
+    this.entityModuleService = new EntityModuleService();
+
+    this.setupHandlers();
+  }
+
+  async listResources(): Promise<SpecVerseResource[]> {
+    try {
+      const startTime = Date.now();
+      const resources = await this.resourcesProvider.listResources();
+
+      // Add entity module resources if available
+      if (this.entityModuleService.isAvailable()) {
+        resources.push(...this.entityModuleService.generateResources());
+      }
+
+      this.eventEmitter.emit('resource-requested', {
+        uri: 'LIST_ALL',
+        requestTime: new Date()
+      } as ResourceRequestedEvent);
+
+      if (this.config.logging && this.config.mode !== 'local' && process.env.MCP_DEBUG) {
+        console.error(`Listed ${resources.length} resources in ${Date.now() - startTime}ms`);
+      }
+
+      return resources;
+    } catch (error) {
+      this.eventEmitter.emit('error-occurred', {
+        operation: 'listResources',
+        error: error instanceof Error ? error.message : String(error)
+      } as ErrorOccurredEvent);
+      throw error;
+    }
+  }
+
+  async readResource(uri: string): Promise<SpecVerseResource> {
+    try {
+      const startTime = Date.now();
+
+      // Check entity module resources first
+      if (uri.startsWith('specverse://entities/') && this.entityModuleService.isAvailable()) {
+        const entityResources = this.entityModuleService.generateResources();
+        const resource = entityResources.find(r => r.uri === uri);
+        if (resource) {
+          this.eventEmitter.emit('resource-requested', { uri, requestTime: new Date() } as ResourceRequestedEvent);
+          return resource;
+        }
+      }
+
+      const content = await this.resourcesProvider.getResourceContent(uri);
+      const resources = await this.resourcesProvider.listResources();
+      const resource = resources.find(r => r.uri === uri);
+
+      if (!resource) {
+        throw new Error(`Resource not found: ${uri}`);
+      }
+
+      this.eventEmitter.emit('resource-requested', {
+        uri,
+        requestTime: new Date()
+      } as ResourceRequestedEvent);
+
+      if (this.config.logging && this.config.mode !== 'local' && process.env.MCP_DEBUG) {
+        console.error(`Read resource ${uri} in ${Date.now() - startTime}ms`);
+      }
+
+      return {
+        ...resource,
+        content
+      };
+    } catch (error) {
+      this.eventEmitter.emit('error-occurred', {
+        operation: 'readResource',
+        error: error instanceof Error ? error.message : String(error),
+        context: { uri }
+      } as ErrorOccurredEvent);
+      throw error;
+    }
+  }
+
+  private setupHandlers(): void {
+    // List resources handler
+    this.server.setRequestHandler(ListResourcesRequestSchema, async () => {
+      const resources = await this.listResources();
+      return { resources };
+    });
+
+    // Read resource handler
+    this.server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
+      const resource = await this.readResource(request.params.uri);
+      return {
+        contents: [{
+          uri: resource.uri,
+          mimeType: resource.mimeType,
+          text: resource.content
+        }]
+      };
+    });
+
+    // List tools handler - dynamic CLI tools + entity module tools
+    this.server.setRequestHandler(ListToolsRequestSchema, async () => {
+      let dynamicCliTools: any[] = [];
+      try {
+        dynamicCliTools = await this.cliProxy.generateMCPTools();
+        if (this.config.logging && this.config.mode !== 'local' && process.env.MCP_DEBUG) {
+          console.error(`🔧 Generated ${dynamicCliTools.length} dynamic CLI tools`);
+        }
+      } catch (error) {
+        if (this.config.logging && process.env.MCP_DEBUG) {
+          console.error('⚠️ Failed to generate dynamic CLI tools:', error);
+        }
+      }
+
+      // Add entity module tools
+      if (this.entityModuleService.isAvailable()) {
+        dynamicCliTools.push(...this.entityModuleService.generateTools());
+      }
+
+      return { tools: dynamicCliTools };
+    });
+
+    // Call tool handler - dynamic CLI tools + entity module tools
+    this.server.setRequestHandler(CallToolRequestSchema, async (request) => {
+      try {
+        const { name, arguments: args } = request.params;
+
+        // Entity module tools
+        const entityToolNames = ['specverse_expand_constraint', 'specverse_list_conventions', 'specverse_entity_info'];
+        if (entityToolNames.includes(name) && this.entityModuleService.isAvailable()) {
+          return await this.entityModuleService.executeTool(name, args || {}) as any;
+        }
+
+        // Dynamic CLI tools
+        if (name.startsWith('specverse_')) {
+          const result = await this.cliProxy.executeCommand(name, args || {});
+          return { content: result.content };
+        } else {
+          return {
+            content: [{
+              type: 'text',
+              text: `Error: Unknown tool '${name}'. Only dynamic CLI tools (prefixed with 'specverse_') are supported.`
+            }]
+          };
+        }
+      } catch (error) {
+        return {
+          content: [{
+            type: 'text',
+            text: `Error in tool handler: ${error instanceof Error ? error.message : String(error)}`
+          }]
+        };
+      }
+    });
+  }
+
+  /**
+   * Start the MCP server
+   */
+  async start(): Promise<void> {
+    try {
+      await this.resourcesProvider.initializeResources();
+
+      // Initialize entity module service (non-blocking, fails gracefully)
+      const entityAvailable = await this.entityModuleService.initialize();
+      if (this.config.logging && process.env.MCP_DEBUG) {
+        if (entityAvailable) {
+          const modules = this.entityModuleService.getEntityModules();
+          console.error(`🧩 Entity modules loaded: ${modules.length} modules, ${modules.reduce((s, m) => s + m.inferenceRuleCount, 0)} rules`);
+        } else {
+          console.error('⚠️ Entity modules not available in this deployment');
+        }
+      }
+
+      this.eventEmitter.emit('server-started', {
+        serverName: 'SpecVerse Dynamic CLI',
+        mode: this.config.mode,
+        timestamp: new Date(),
+        featuresEnabled: this.config.features,
+        pid: process.pid
+      } as ServerStartedEvent);
+
+      if (this.config.logging && process.env.MCP_DEBUG) {
+        const mode = this.config.mode || 'local';
+        const resourceCount = this.resourcesProvider.getCachedResourceCount();
+        console.error(`🚀 SpecVerse MCP Server started in ${mode} mode`);
+        console.error(`📚 Loaded ${resourceCount} resources`);
+        console.error(`🔧 Dynamic CLI integration enabled - all tools from CLI`);
+      }
+    } catch (error) {
+      this.eventEmitter.emit('error-occurred', {
+        operation: 'start',
+        error: error instanceof Error ? error.message : String(error)
+      } as ErrorOccurredEvent);
+      throw error;
+    }
+  }
+
+  /**
+   * Stop the MCP server
+   */
+  async stop(): Promise<void> {
+    try {
+      await this.server.close();
+      
+      if (this.config.logging && process.env.MCP_DEBUG) {
+        console.error('🛑 SpecVerse MCP Server stopped');
+      }
+    } catch (error) {
+      this.eventEmitter.emit('error-occurred', {
+        operation: 'stop',
+        error: error instanceof Error ? error.message : String(error)
+      } as ErrorOccurredEvent);
+      throw error;
+    }
+  }
+
+  // Methods expected by the main server
+  getEventEmitter() {
+    return this.eventEmitter;
+  }
+
+  async initialize(): Promise<void> {
+    await this.start();
+  }
+
+  getServer() {
+    return this.server;
+  }
+
+  getMetrics() {
+    return {
+      resourceCount: this.resourcesProvider.getCachedResourceCount(),
+      cliIntegration: true
+    };
+  }
+}

package/libs/instance-factories/tools/templates/mcp/static/src/events/EventEmitter.ts

@@ -0,0 +1,90 @@
+/**
+ * EventEmitter
+ * Clean implementation for handling application events
+ */
+
+import type {
+  ServerStartedEvent,
+  ToolCalledEvent,
+  ResourceRequestedEvent,
+  ErrorOccurredEvent
+} from '../types/index.js';
+
+export type EventType = 'server-started' | 'tool-called' | 'resource-requested' | 'error-occurred' | 'orchestrator-initialized' | 'orchestrator-execution-completed' | 'orchestrator-execution-failed';
+
+export interface OrchestratorInitializedEvent {
+  type: 'orchestrator-initialized';
+  capabilities: any;
+}
+
+export interface OrchestratorExecutionCompletedEvent {
+  type: 'orchestrator-execution-completed';
+  operation: string;
+  executionTime: number;
+  success: boolean;
+}
+
+export interface OrchestratorExecutionFailedEvent {
+  type: 'orchestrator-execution-failed';
+  operation: string;
+  error: string;
+  executionTime: number;
+}
+
+export type EventData = ServerStartedEvent | ToolCalledEvent | ResourceRequestedEvent | ErrorOccurredEvent | OrchestratorInitializedEvent | OrchestratorExecutionCompletedEvent | OrchestratorExecutionFailedEvent;
+
+export type EventHandler<T = EventData> = (event: T) => void | Promise<void>;
+
+export class EventEmitter {
+  private listeners: Map<EventType, EventHandler[]> = new Map();
+
+  on<T extends EventData>(eventType: EventType, handler: EventHandler<T>): void {
+    if (!this.listeners.has(eventType)) {
+      this.listeners.set(eventType, []);
+    }
+    this.listeners.get(eventType)!.push(handler as EventHandler);
+  }
+
+  off<T extends EventData>(eventType: EventType, handler: EventHandler<T>): void {
+    const handlers = this.listeners.get(eventType);
+    if (handlers) {
+      const index = handlers.indexOf(handler as EventHandler);
+      if (index !== -1) {
+        handlers.splice(index, 1);
+      }
+    }
+  }
+
+  async emit(eventType: EventType, data: EventData): Promise<void> {
+    const handlers = this.listeners.get(eventType);
+    if (handlers) {
+      const promises = handlers.map(handler => {
+        try {
+          const result = handler(data);
+          return Promise.resolve(result);
+        } catch (error) {
+          console.error(`Error in event handler for ${eventType}:`, error);
+          return Promise.resolve();
+        }
+      });
+
+      await Promise.allSettled(promises);
+    }
+  }
+
+  removeAllListeners(eventType?: EventType): void {
+    if (eventType) {
+      this.listeners.delete(eventType);
+    } else {
+      this.listeners.clear();
+    }
+  }
+
+  listenerCount(eventType: EventType): number {
+    return this.listeners.get(eventType)?.length || 0;
+  }
+
+  eventNames(): EventType[] {
+    return Array.from(this.listeners.keys());
+  }
+}

package/libs/instance-factories/tools/templates/mcp/static/src/index.ts

@@ -0,0 +1,24 @@
+/**
+ * SpecVerse AI Support MCP Server - Clean Implementation
+ * Main exports for the clean implementation
+ */
+
+// Core exports
+export { SpecVerseCleanMCPServer } from './server/mcp-server.js';
+export { MCPServerController } from './controllers/MCPServerController.js';
+
+// Service exports
+export { ResourcesProviderService } from './services/ResourcesProviderService.js';
+export { LibraryToolsService } from './services/LibraryToolsService.js';
+export { PromptToolsService } from './services/PromptToolsService.js';
+
+// Model exports
+export { SpecVerseResourceModel } from './models/SpecVerseResource.js';
+export { LibrarySuggestionModel } from './models/LibrarySuggestion.js';
+
+// Event system exports
+export { EventEmitter } from './events/EventEmitter.js';
+export type { EventType, EventData, EventHandler } from './events/EventEmitter.js';
+
+// Type exports
+export type * from './types/index.js';

package/libs/instance-factories/tools/templates/mcp/static/src/interfaces/ResourceProvider.ts

@@ -0,0 +1,15 @@
+/**
+ * ResourceProvider Interface
+ * Common interface for resource providers (filesystem, embedded, hybrid)
+ */
+
+import type { SpecVerseResource, MCPToolResult } from '../types/index.js';
+
+export interface ResourceProvider {
+  initializeResources(): Promise<void>;
+  listResources(): Promise<SpecVerseResource[]>;
+  getResourceContent(uri: string): Promise<string>;
+  readResource(uri: string): Promise<MCPToolResult>;
+  isResourceAvailable(uri: string): boolean;
+  getCachedResourceCount(): number;
+}

package/libs/instance-factories/tools/templates/mcp/static/src/models/LibrarySuggestion.ts

@@ -0,0 +1,106 @@
+/**
+ * LibrarySuggestion Model
+ * Clean implementation from extracted specification
+ */
+
+import { z } from 'zod';
+import type { LibrarySuggestion } from '../types/index.js';
+
+export const LibrarySuggestionSchema = z.object({
+  name: z.string().min(1, 'Name is required'),
+  path: z.string().min(1, 'Path is required'),
+  type: z.enum(['deployment', 'domain', 'manifest', 'type', 'standard']),
+  description: z.string().min(1, 'Description is required'),
+  ai_description: z.string().min(1, 'AI description is required'),
+  expansion_factor: z.number().min(1, 'Expansion factor must be >= 1'),
+  complexity_level: z.enum(['low', 'medium', 'high']),
+  best_for: z.array(z.string()).min(1, 'Must specify at least one use case')
+});
+
+export class LibrarySuggestionModel {
+  private constructor(
+    public readonly name: string,
+    public readonly path: string,
+    public readonly type: 'deployment' | 'domain' | 'manifest' | 'type' | 'standard',
+    public readonly description: string,
+    public readonly ai_description: string,
+    public readonly expansion_factor: number,
+    public readonly complexity_level: 'low' | 'medium' | 'high',
+    public readonly best_for: string[]
+  ) {}
+
+  static create(data: LibrarySuggestion): LibrarySuggestionModel {
+    const validated = LibrarySuggestionSchema.parse(data);
+    
+    return new LibrarySuggestionModel(
+      validated.name,
+      validated.path,
+      validated.type,
+      validated.description,
+      validated.ai_description,
+      validated.expansion_factor,
+      validated.complexity_level,
+      validated.best_for
+    );
+  }
+
+  static fromJson(json: string): LibrarySuggestionModel {
+    const data = JSON.parse(json);
+    return this.create(data);
+  }
+
+  toJson(): string {
+    return JSON.stringify({
+      name: this.name,
+      path: this.path,
+      type: this.type,
+      description: this.description,
+      ai_description: this.ai_description,
+      expansion_factor: this.expansion_factor,
+      complexity_level: this.complexity_level,
+      best_for: this.best_for
+    });
+  }
+
+  matchesContext(context: string, scale: string): number {
+    let score = 0;
+    const contextLower = context.toLowerCase();
+    
+    // Check if library type matches context
+    for (const useCase of this.best_for) {
+      if (contextLower.includes(useCase.toLowerCase())) {
+        score += 2;
+      }
+    }
+    
+    // Check complexity match with scale
+    const scaleComplexity = this.getScaleComplexity(scale);
+    const complexityScore = this.getComplexityScore();
+    const complexityMatch = Math.abs(complexityScore - scaleComplexity);
+    score += Math.max(0, 3 - complexityMatch);
+    
+    return score;
+  }
+
+  private getScaleComplexity(scale: string): number {
+    switch (scale) {
+      case 'personal': return 1;
+      case 'business': return 2;
+      case 'enterprise': return 3;
+      default: return 2;
+    }
+  }
+
+  private getComplexityScore(): number {
+    switch (this.complexity_level) {
+      case 'low': return 1;
+      case 'medium': return 2;
+      case 'high': return 3;
+      default: return 2;
+    }
+  }
+
+  getRelevanceScore(): number {
+    return this.expansion_factor * this.getComplexityScore();
+  }
+}

package/libs/instance-factories/tools/templates/mcp/static/src/models/SpecVerseResource.ts

@@ -0,0 +1,75 @@
+/**
+ * SpecVerseResource Model
+ * Clean implementation from extracted specification
+ */
+
+import { z } from 'zod';
+import type { SpecVerseResource } from '../types/index.js';
+
+export const SpecVerseResourceSchema = z.object({
+  uri: z.string().min(1, 'URI is required').regex(/^specverse:\/\//, 'URI must start with specverse://'),
+  name: z.string().min(1, 'Name is required'),
+  description: z.string().min(1, 'Description is required'),
+  mimeType: z.string().min(1, 'MIME type is required'),
+  content: z.string().optional(),
+  metadata: z.record(z.any()).optional()
+});
+
+export class SpecVerseResourceModel {
+  private constructor(
+    public readonly uri: string,
+    public readonly name: string,
+    public readonly description: string,
+    public readonly mimeType: string,
+    public readonly content?: string,
+    public readonly metadata?: Record<string, any>
+  ) {}
+
+  static create(data: SpecVerseResource): SpecVerseResourceModel {
+    const validated = SpecVerseResourceSchema.parse(data);
+    
+    return new SpecVerseResourceModel(
+      validated.uri,
+      validated.name,
+      validated.description,
+      validated.mimeType,
+      validated.content,
+      validated.metadata
+    );
+  }
+
+  static fromJson(json: string): SpecVerseResourceModel {
+    const data = JSON.parse(json);
+    return this.create(data);
+  }
+
+  toJson(): string {
+    return JSON.stringify({
+      uri: this.uri,
+      name: this.name,
+      description: this.description,
+      mimeType: this.mimeType,
+      content: this.content,
+      metadata: this.metadata
+    });
+  }
+
+  withContent(content: string): SpecVerseResourceModel {
+    return new SpecVerseResourceModel(
+      this.uri,
+      this.name,
+      this.description,
+      this.mimeType,
+      content,
+      this.metadata
+    );
+  }
+
+  matches(uri: string): boolean {
+    return this.uri === uri;
+  }
+
+  isLoaded(): boolean {
+    return this.content !== undefined;
+  }
+}