@specverse/engines 4.1.5 → 4.1.7

package/dist/libs/instance-factories/tools/templates/mcp/mcp-server-generator.js

@@ -0,0 +1,149 @@
+import { existsSync, mkdirSync, writeFileSync, readdirSync, statSync, copyFileSync } from "fs";
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+const __generatorDir = dirname(fileURLToPath(import.meta.url));
+function generateMCPServer(context) {
+  const { spec, outputDir } = context;
+  const mcpDir = join(outputDir || ".", "tools", "specverse-mcp");
+  if (!existsSync(mcpDir)) mkdirSync(mcpDir, { recursive: true });
+  let staticDir = join(__generatorDir, "static");
+  if (!existsSync(staticDir)) {
+    staticDir = __generatorDir.replace("/dist/libs/", "/libs/");
+    staticDir = join(staticDir, "static");
+  }
+  if (existsSync(staticDir)) {
+    copyRecursive(staticDir, mcpDir);
+  } else {
+    console.warn(`[MCP Generator] Static assets not found at ${staticDir}`);
+  }
+  const tools = extractMCPTools(spec);
+  const resources = extractMCPResources(spec);
+  const cliCommands = extractCLICommands(spec);
+  const registryCode = generateToolRegistry(tools, resources, cliCommands);
+  const registryDir = join(mcpDir, "src", "generated");
+  if (!existsSync(registryDir)) mkdirSync(registryDir, { recursive: true });
+  writeFileSync(join(registryDir, "spec-registry.ts"), registryCode);
+  return `MCP server generated in: ${mcpDir}
+  ${tools.length} tools, ${resources.length} resources, ${cliCommands.length} CLI commands`;
+}
+function extractMCPTools(spec) {
+  const tools = [];
+  const components = spec?.components || {};
+  const componentList = Array.isArray(components) ? components : Object.values(components);
+  if (spec?.services && !Array.isArray(components)) {
+    componentList.push({ services: spec.services, models: spec.models });
+  }
+  for (const component of componentList) {
+    const comp = component;
+    const services = comp?.services;
+    if (services) {
+      const serviceList = Array.isArray(services) ? services : Object.entries(services).map(([n, d]) => ({ name: n, ...d }));
+      for (const service of serviceList) {
+        const operations = service.operations;
+        if (operations) {
+          const opEntries = Array.isArray(operations) ? operations : Object.entries(operations).map(([n, d]) => ({ name: n, ...d }));
+          for (const op of opEntries) {
+            tools.push({
+              name: `${service.name.replace(/Service$/, "").toLowerCase()}-${op.name}`,
+              description: op.description || `${op.name} via ${service.name}`,
+              isEntityTool: false
+            });
+          }
+        }
+      }
+    }
+    const models = comp?.models;
+    if (models) {
+      const modelList = Array.isArray(models) ? models : Object.entries(models).map(([n, d]) => ({ name: n, ...d }));
+      for (const model of modelList) {
+        const behaviors = model.behaviors;
+        if (behaviors) {
+          const behaviorEntries = typeof behaviors === "object" && !Array.isArray(behaviors) ? Object.entries(behaviors).map(([n, d]) => ({ name: n, ...d })) : [];
+          for (const behavior of behaviorEntries) {
+            tools.push({
+              name: `${model.name.toLowerCase()}-${behavior.name}`,
+              description: behavior.description || `${behavior.name} on ${model.name}`,
+              isEntityTool: true
+            });
+          }
+        }
+      }
+    }
+  }
+  const cliCmds = extractCLICommands(spec);
+  for (const cmd of cliCmds) {
+    tools.push({
+      name: `specverse-${cmd}`,
+      description: `Execute specverse ${cmd} command`,
+      isEntityTool: false
+    });
+  }
+  if (tools.length === 0) {
+    tools.push(
+      { name: "specverse-validate", description: "Validate a specification", isEntityTool: false },
+      { name: "specverse-create", description: "Create a specification", isEntityTool: false }
+    );
+  }
+  return tools;
+}
+function extractMCPResources(spec) {
+  return [
+    { uri: "specverse://schema", name: "SpecVerse Schema", description: "JSON Schema for .specly validation" },
+    { uri: "specverse://conventions", name: "Convention Reference", description: "Convention syntax patterns" },
+    { uri: "specverse://library-catalog", name: "Library Catalog", description: "Available SpecVerse libraries" },
+    { uri: "specverse://prompts", name: "Prompt Templates", description: "AI prompt template versions" }
+  ];
+}
+function extractCLICommands(spec) {
+  const commands = [];
+  const components = spec?.components || [];
+  for (const component of Array.isArray(components) ? components : Object.values(components)) {
+    const cliCommands = component?.commands;
+    if (!cliCommands) continue;
+    for (const [, rootDef] of Object.entries(cliCommands)) {
+      const subs = rootDef?.subcommands || {};
+      for (const subName of Object.keys(subs)) {
+        commands.push(subName);
+      }
+    }
+  }
+  return commands;
+}
+function generateToolRegistry(tools, resources, cliCommands) {
+  return `/**
+ * Spec-Driven MCP Registry
+ * Generated from SpecVerse self-specification.
+ *
+ * Tools, resources, and CLI command mappings derived from the spec.
+ */
+
+export const SPEC_TOOLS = ${JSON.stringify(tools, null, 2)};
+
+export const SPEC_RESOURCES = ${JSON.stringify(resources, null, 2)};
+
+export const CLI_COMMANDS = ${JSON.stringify(cliCommands, null, 2)};
+
+export function getToolByName(name: string) {
+  return SPEC_TOOLS.find(t => t.name === name);
+}
+
+export function getResourceByUri(uri: string) {
+  return SPEC_RESOURCES.find(r => r.uri === uri);
+}
+`;
+}
+function copyRecursive(src, dest) {
+  for (const entry of readdirSync(src)) {
+    const srcPath = join(src, entry);
+    const destPath = join(dest, entry);
+    if (statSync(srcPath).isDirectory()) {
+      if (!existsSync(destPath)) mkdirSync(destPath, { recursive: true });
+      copyRecursive(srcPath, destPath);
+    } else {
+      copyFileSync(srcPath, destPath);
+    }
+  }
+}
+export {
+  generateMCPServer as default
+};

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

@@ -0,0 +1,232 @@
+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";
+class MCPServerController {
+  server;
+  config;
+  resourcesProvider;
+  cliProxy;
+  entityModuleService;
+  eventEmitter;
+  constructor(config) {
+    this.config = config;
+    this.eventEmitter = new EventEmitter();
+    this.server = new Server({
+      name: "specverse-dynamic-cli",
+      version: "1.0.0"
+    }, {
+      capabilities: {
+        resources: {},
+        tools: {}
+      }
+    });
+    this.resourcesProvider = new HybridResourcesProvider({
+      mode: "auto",
+      resourcesPath: config.resources_path
+    });
+    this.cliProxy = new CLIProxyService();
+    this.entityModuleService = new EntityModuleService();
+    this.setupHandlers();
+  }
+  async listResources() {
+    try {
+      const startTime = Date.now();
+      const resources = await this.resourcesProvider.listResources();
+      if (this.entityModuleService.isAvailable()) {
+        resources.push(...this.entityModuleService.generateResources());
+      }
+      this.eventEmitter.emit("resource-requested", {
+        uri: "LIST_ALL",
+        requestTime: /* @__PURE__ */ new Date()
+      });
+      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)
+      });
+      throw error;
+    }
+  }
+  async readResource(uri) {
+    try {
+      const startTime = Date.now();
+      if (uri.startsWith("specverse://entities/") && this.entityModuleService.isAvailable()) {
+        const entityResources = this.entityModuleService.generateResources();
+        const resource2 = entityResources.find((r) => r.uri === uri);
+        if (resource2) {
+          this.eventEmitter.emit("resource-requested", { uri, requestTime: /* @__PURE__ */ new Date() });
+          return resource2;
+        }
+      }
+      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: /* @__PURE__ */ new Date()
+      });
+      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 }
+      });
+      throw error;
+    }
+  }
+  setupHandlers() {
+    this.server.setRequestHandler(ListResourcesRequestSchema, async () => {
+      const resources = await this.listResources();
+      return { resources };
+    });
+    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
+        }]
+      };
+    });
+    this.server.setRequestHandler(ListToolsRequestSchema, async () => {
+      let dynamicCliTools = [];
+      try {
+        dynamicCliTools = await this.cliProxy.generateMCPTools();
+        if (this.config.logging && this.config.mode !== "local" && process.env.MCP_DEBUG) {
+          console.error(`\u{1F527} Generated ${dynamicCliTools.length} dynamic CLI tools`);
+        }
+      } catch (error) {
+        if (this.config.logging && process.env.MCP_DEBUG) {
+          console.error("\u26A0\uFE0F Failed to generate dynamic CLI tools:", error);
+        }
+      }
+      if (this.entityModuleService.isAvailable()) {
+        dynamicCliTools.push(...this.entityModuleService.generateTools());
+      }
+      return { tools: dynamicCliTools };
+    });
+    this.server.setRequestHandler(CallToolRequestSchema, async (request) => {
+      try {
+        const { name, arguments: args } = request.params;
+        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 || {});
+        }
+        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() {
+    try {
+      await this.resourcesProvider.initializeResources();
+      const entityAvailable = await this.entityModuleService.initialize();
+      if (this.config.logging && process.env.MCP_DEBUG) {
+        if (entityAvailable) {
+          const modules = this.entityModuleService.getEntityModules();
+          console.error(`\u{1F9E9} Entity modules loaded: ${modules.length} modules, ${modules.reduce((s, m) => s + m.inferenceRuleCount, 0)} rules`);
+        } else {
+          console.error("\u26A0\uFE0F Entity modules not available in this deployment");
+        }
+      }
+      this.eventEmitter.emit("server-started", {
+        serverName: "SpecVerse Dynamic CLI",
+        mode: this.config.mode,
+        timestamp: /* @__PURE__ */ new Date(),
+        featuresEnabled: this.config.features,
+        pid: process.pid
+      });
+      if (this.config.logging && process.env.MCP_DEBUG) {
+        const mode = this.config.mode || "local";
+        const resourceCount = this.resourcesProvider.getCachedResourceCount();
+        console.error(`\u{1F680} SpecVerse MCP Server started in ${mode} mode`);
+        console.error(`\u{1F4DA} Loaded ${resourceCount} resources`);
+        console.error(`\u{1F527} 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)
+      });
+      throw error;
+    }
+  }
+  /**
+   * Stop the MCP server
+   */
+  async stop() {
+    try {
+      await this.server.close();
+      if (this.config.logging && process.env.MCP_DEBUG) {
+        console.error("\u{1F6D1} SpecVerse MCP Server stopped");
+      }
+    } catch (error) {
+      this.eventEmitter.emit("error-occurred", {
+        operation: "stop",
+        error: error instanceof Error ? error.message : String(error)
+      });
+      throw error;
+    }
+  }
+  // Methods expected by the main server
+  getEventEmitter() {
+    return this.eventEmitter;
+  }
+  async initialize() {
+    await this.start();
+  }
+  getServer() {
+    return this.server;
+  }
+  getMetrics() {
+    return {
+      resourceCount: this.resourcesProvider.getCachedResourceCount(),
+      cliIntegration: true
+    };
+  }
+}
+export {
+  MCPServerController
+};

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

@@ -0,0 +1,49 @@
+class EventEmitter {
+  listeners = /* @__PURE__ */ new Map();
+  on(eventType, handler) {
+    if (!this.listeners.has(eventType)) {
+      this.listeners.set(eventType, []);
+    }
+    this.listeners.get(eventType).push(handler);
+  }
+  off(eventType, handler) {
+    const handlers = this.listeners.get(eventType);
+    if (handlers) {
+      const index = handlers.indexOf(handler);
+      if (index !== -1) {
+        handlers.splice(index, 1);
+      }
+    }
+  }
+  async emit(eventType, data) {
+    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) {
+    if (eventType) {
+      this.listeners.delete(eventType);
+    } else {
+      this.listeners.clear();
+    }
+  }
+  listenerCount(eventType) {
+    return this.listeners.get(eventType)?.length || 0;
+  }
+  eventNames() {
+    return Array.from(this.listeners.keys());
+  }
+}
+export {
+  EventEmitter
+};

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

@@ -0,0 +1,18 @@
+import { SpecVerseCleanMCPServer } from "./server/mcp-server.js";
+import { MCPServerController } from "./controllers/MCPServerController.js";
+import { ResourcesProviderService } from "./services/ResourcesProviderService.js";
+import { LibraryToolsService } from "./services/LibraryToolsService.js";
+import { PromptToolsService } from "./services/PromptToolsService.js";
+import { SpecVerseResourceModel } from "./models/SpecVerseResource.js";
+import { LibrarySuggestionModel } from "./models/LibrarySuggestion.js";
+import { EventEmitter } from "./events/EventEmitter.js";
+export {
+  EventEmitter,
+  LibrarySuggestionModel,
+  LibraryToolsService,
+  MCPServerController,
+  PromptToolsService,
+  ResourcesProviderService,
+  SpecVerseCleanMCPServer,
+  SpecVerseResourceModel
+};

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

@@ -0,0 +1,97 @@
+import { z } from "zod";
+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")
+});
+class LibrarySuggestionModel {
+  constructor(name, path, type, description, ai_description, expansion_factor, complexity_level, best_for) {
+    this.name = name;
+    this.path = path;
+    this.type = type;
+    this.description = description;
+    this.ai_description = ai_description;
+    this.expansion_factor = expansion_factor;
+    this.complexity_level = complexity_level;
+    this.best_for = best_for;
+  }
+  static create(data) {
+    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) {
+    const data = JSON.parse(json);
+    return this.create(data);
+  }
+  toJson() {
+    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, scale) {
+    let score = 0;
+    const contextLower = context.toLowerCase();
+    for (const useCase of this.best_for) {
+      if (contextLower.includes(useCase.toLowerCase())) {
+        score += 2;
+      }
+    }
+    const scaleComplexity = this.getScaleComplexity(scale);
+    const complexityScore = this.getComplexityScore();
+    const complexityMatch = Math.abs(complexityScore - scaleComplexity);
+    score += Math.max(0, 3 - complexityMatch);
+    return score;
+  }
+  getScaleComplexity(scale) {
+    switch (scale) {
+      case "personal":
+        return 1;
+      case "business":
+        return 2;
+      case "enterprise":
+        return 3;
+      default:
+        return 2;
+    }
+  }
+  getComplexityScore() {
+    switch (this.complexity_level) {
+      case "low":
+        return 1;
+      case "medium":
+        return 2;
+      case "high":
+        return 3;
+      default:
+        return 2;
+    }
+  }
+  getRelevanceScore() {
+    return this.expansion_factor * this.getComplexityScore();
+  }
+}
+export {
+  LibrarySuggestionModel,
+  LibrarySuggestionSchema
+};

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

@@ -0,0 +1,64 @@
+import { z } from "zod";
+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()
+});
+class SpecVerseResourceModel {
+  constructor(uri, name, description, mimeType, content, metadata) {
+    this.uri = uri;
+    this.name = name;
+    this.description = description;
+    this.mimeType = mimeType;
+    this.content = content;
+    this.metadata = metadata;
+  }
+  static create(data) {
+    const validated = SpecVerseResourceSchema.parse(data);
+    return new SpecVerseResourceModel(
+      validated.uri,
+      validated.name,
+      validated.description,
+      validated.mimeType,
+      validated.content,
+      validated.metadata
+    );
+  }
+  static fromJson(json) {
+    const data = JSON.parse(json);
+    return this.create(data);
+  }
+  toJson() {
+    return JSON.stringify({
+      uri: this.uri,
+      name: this.name,
+      description: this.description,
+      mimeType: this.mimeType,
+      content: this.content,
+      metadata: this.metadata
+    });
+  }
+  withContent(content) {
+    return new SpecVerseResourceModel(
+      this.uri,
+      this.name,
+      this.description,
+      this.mimeType,
+      content,
+      this.metadata
+    );
+  }
+  matches(uri) {
+    return this.uri === uri;
+  }
+  isLoaded() {
+    return this.content !== void 0;
+  }
+}
+export {
+  SpecVerseResourceModel,
+  SpecVerseResourceSchema
+};