@specverse/engines 4.3.5 → 5.0.1

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

@@ -1,148 +1,374 @@
-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));
+import { existsSync, mkdirSync, writeFileSync } from "fs";
+import { join } from "path";
 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);
+  const srcDir = join(mcpDir, "src");
+  if (!existsSync(srcDir)) mkdirSync(srcDir, { recursive: true });
+  const distribution = extractMCPDistribution(spec);
+  const version = distribution?.version || spec?.metadata?.version || spec?.version || "5.0.0";
+  const description = distribution?.description || "SpecVerse MCP server \u2014 exposes the specverse CLI as MCP tools and the live spec schema + docs as MCP resources.";
+  const displayName = distribution?.displayName || "SpecVerse MCP";
+  const cliCommands = extractCLITools(spec);
+  writeFileSync(join(mcpDir, "package.json"), generatePackageJson(version, description));
+  writeFileSync(join(mcpDir, "tsconfig.json"), generateTsconfig());
+  writeFileSync(join(srcDir, "server.ts"), generateServer(displayName, version));
+  writeFileSync(join(srcDir, "cli-runner.ts"), generateCliRunner());
+  writeFileSync(join(srcDir, "resources.ts"), generateResources());
+  writeFileSync(join(srcDir, "tools.ts"), generateTools(cliCommands));
   return `MCP server generated in: ${mcpDir}
-  ${tools.length} tools, ${resources.length} resources, ${cliCommands.length} CLI commands`;
+  ${cliCommands.length} tools (one per CLI command), 2 resources (schema + docs)`;
 }
-function extractMCPTools(spec) {
-  const tools = [];
+function extractCLITools(spec) {
+  const out = [];
   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 componentList = Array.isArray(components) ? components : Object.entries(components).map(([name, data]) => ({ name, ...data }));
+  for (const comp of componentList) {
+    const cliCommands = comp?.commands;
+    if (!cliCommands) continue;
+    for (const [, rootDef] of Object.entries(cliCommands)) {
+      const subcommands = rootDef?.subcommands || {};
+      for (const [subName, subDef] of Object.entries(subcommands)) {
+        const sub = subDef;
+        const nestedSubs = sub?.subcommands;
+        if (nestedSubs && Object.keys(nestedSubs).length > 0) {
+          for (const [nestedName, nestedDef] of Object.entries(nestedSubs)) {
+            out.push(buildCLITool([subName, nestedName], nestedDef));
           }
+        } else {
+          out.push(buildCLITool([subName], sub));
         }
       }
     }
   }
-  const cliCmds = extractCLICommands(spec);
-  for (const cmd of cliCmds) {
-    tools.push({
-      name: `specverse-${cmd}`,
-      description: `Execute specverse ${cmd} command`,
-      isEntityTool: false
-    });
+  return out;
+}
+function buildCLITool(cliArgs, def) {
+  const name = cliArgs.join("_");
+  const description = def?.description || `Run specverse ${cliArgs.join(" ")}`;
+  const properties = {};
+  const required = [];
+  const args = def?.arguments || {};
+  const positionalEntries = Object.entries(args).filter(([, a]) => a.positional).sort(([, a], [, b]) => (a.position || 0) - (b.position || 0));
+  const positional = positionalEntries.map(([k]) => k);
+  for (const [argName, arg] of Object.entries(args)) {
+    properties[argName] = {
+      type: mapArgTypeToJsonSchema(arg.type),
+      description: arg.description || `${argName} argument`
+    };
+    if (arg.required) required.push(argName);
   }
-  if (tools.length === 0) {
-    tools.push(
-      { name: "specverse-validate", description: "Validate a specification", isEntityTool: false },
-      { name: "specverse-create", description: "Create a specification", isEntityTool: false }
-    );
+  const flags = def?.flags || {};
+  for (const [flagName, flag] of Object.entries(flags)) {
+    const propName = flagName.replace(/^--/, "").replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+    properties[propName] = {
+      type: mapArgTypeToJsonSchema(flag.type),
+      description: flag.description || `${flagName} flag`
+    };
+    if (flag.default !== void 0) {
+      properties[propName].default = flag.default;
+    }
   }
-  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 {
+    name,
+    description,
+    cliArgs,
+    positional,
+    inputSchema: {
+      type: "object",
+      properties,
+      ...required.length > 0 ? { required } : {}
     }
+  };
+}
+function mapArgTypeToJsonSchema(type) {
+  if (!type) return "string";
+  const t = type.toLowerCase();
+  if (t === "boolean") return "boolean";
+  if (t === "integer" || t === "number") return "number";
+  return "string";
+}
+function extractMCPDistribution(spec) {
+  const all = [];
+  if (spec?.distributions) {
+    all.push(...Array.isArray(spec.distributions) ? spec.distributions : Object.entries(spec.distributions).map(([name, data]) => ({ name, ...data })));
+  }
+  const components = spec?.components || {};
+  const componentList = Array.isArray(components) ? components : Object.values(components);
+  for (const comp of componentList) {
+    const distributions = comp?.distributions;
+    if (!distributions) continue;
+    all.push(...Array.isArray(distributions) ? distributions : Object.entries(distributions).map(([name, data]) => ({ name, ...data })));
   }
-  return commands;
+  for (const dist of all) if (dist.type === "mcp") return dist;
+  return null;
+}
+function generatePackageJson(version, description) {
+  return JSON.stringify({
+    name: "@specverse/mcp",
+    version,
+    description,
+    type: "module",
+    main: "dist/server.js",
+    bin: { "specverse-mcp": "dist/server.js" },
+    scripts: {
+      build: "tsc",
+      start: "node dist/server.js",
+      clean: "rm -rf dist"
+    },
+    dependencies: {
+      "@modelcontextprotocol/sdk": "^1.17.4",
+      "@specverse/entities": "^5.0.0"
+    },
+    devDependencies: {
+      "@types/node": "^20.19.11",
+      typescript: "^5.9.2"
+    },
+    files: ["dist", "README.md"],
+    engines: { node: ">=18.0.0" },
+    publishConfig: { access: "public" },
+    license: "MIT"
+  }, null, 2) + "\n";
+}
+function generateTsconfig() {
+  return JSON.stringify({
+    compilerOptions: {
+      target: "ES2022",
+      module: "ESNext",
+      moduleResolution: "bundler",
+      esModuleInterop: true,
+      strict: true,
+      skipLibCheck: true,
+      declaration: true,
+      outDir: "./dist",
+      rootDir: "./src",
+      resolveJsonModule: true,
+      // Under moduleResolution: 'bundler' tsc's auto-inclusion of
+      // @types/* packages from node_modules/@types is environment-
+      // dependent — Node 20 on CI doesn't pick up @types/node while
+      // Node 24 locally does. Listing it explicitly forces consistent
+      // resolution everywhere.
+      types: ["node"]
+    },
+    include: ["src/**/*"],
+    exclude: ["node_modules", "dist"]
+  }, null, 2) + "\n";
+}
+function generateServer(displayName, version) {
+  return `#!/usr/bin/env node
+/**
+ * SpecVerse MCP Server \u2014 stdio transport.
+ *
+ * Wires the MCP protocol to the generated tool registry + live resources.
+ * No handwritten business logic \u2014 everything is derived from the spec
+ * (tools from CLI commands) or from @specverse/entities (schema + docs).
+ */
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import {
+  ListToolsRequestSchema,
+  CallToolRequestSchema,
+  ListResourcesRequestSchema,
+  ReadResourceRequestSchema,
+} from '@modelcontextprotocol/sdk/types.js';
+import { TOOLS, callTool } from './tools.js';
+import { RESOURCES, readResource } from './resources.js';
+
+const server = new Server(
+  { name: ${JSON.stringify(displayName)}, version: ${JSON.stringify(version)} },
+  { capabilities: { tools: {}, resources: {} } },
+);
+
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+  tools: TOOLS.map(t => ({
+    name: t.name,
+    description: t.description,
+    inputSchema: t.inputSchema,
+  })),
+}));
+
+server.setRequestHandler(CallToolRequestSchema, async (req: { params: { name: string; arguments?: Record<string, unknown> } }) => {
+  const { name, arguments: args } = req.params;
+  return callTool(name, args ?? {});
+});
+
+server.setRequestHandler(ListResourcesRequestSchema, async () => ({
+  resources: RESOURCES.map(r => ({
+    uri: r.uri,
+    name: r.name,
+    description: r.description,
+    mimeType: r.mimeType,
+  })),
+}));
+
+server.setRequestHandler(ReadResourceRequestSchema, async (req: { params: { uri: string } }) => {
+  return readResource(req.params.uri);
+});
+
+const transport = new StdioServerTransport();
+await server.connect(transport);
+`;
 }
-function generateToolRegistry(tools, resources, cliCommands) {
+function generateCliRunner() {
   return `/**
- * Spec-Driven MCP Registry
- * Generated from SpecVerse self-specification.
+ * Thin specverse CLI runner.
  *
- * Tools, resources, and CLI command mappings derived from the spec.
+ * Each MCP tool maps to a specverse CLI command + a set of user-supplied
+ * arguments. The tool registry tells us which argument keys are positional
+ * (declared in the spec as \`positional: true\`) \u2014 those get emitted in
+ * order before any flags, matching the CLI's expected argv shape. The
+ * specverse binary must be on PATH (the AI client that launches the
+ * server inherits env from its parent).
  */
+import { spawn } from 'child_process';
+
+export interface CliResult {
+  stdout: string;
+  stderr: string;
+  code: number | null;
+}
 
-export const SPEC_TOOLS = ${JSON.stringify(tools, null, 2)};
+export function runCli(
+  cliArgs: string[],
+  positional: string[],
+  userArgs: Record<string, any>,
+  cwd?: string,
+): Promise<CliResult> {
+  const argv = [...cliArgs];
 
-export const SPEC_RESOURCES = ${JSON.stringify(resources, null, 2)};
+  // 1. Positional args first, in spec-declared order. Undefined values
+  //    are skipped \u2014 commander will surface missing-required errors.
+  for (const key of positional) {
+    const v = userArgs[key];
+    if (v === undefined || v === null) continue;
+    argv.push(String(v));
+  }
 
-export const CLI_COMMANDS = ${JSON.stringify(cliCommands, null, 2)};
+  // 2. Remaining keys become --flag or --flag value.
+  const positionalSet = new Set(positional);
+  for (const [k, v] of Object.entries(userArgs)) {
+    if (positionalSet.has(k)) continue;
+    if (v === undefined || v === null) continue;
+    if (typeof v === 'boolean') {
+      if (v) argv.push(\`--\${k}\`);
+    } else {
+      argv.push(\`--\${k}\`, String(v));
+    }
+  }
 
-export function getToolByName(name: string) {
-  return SPEC_TOOLS.find(t => t.name === name);
+  return new Promise<CliResult>(resolve => {
+    const child = spawn('specverse', argv, { cwd: cwd || process.cwd(), env: process.env });
+    let stdout = '';
+    let stderr = '';
+    child.stdout.on('data', (d: Buffer) => { stdout += d.toString(); });
+    child.stderr.on('data', (d: Buffer) => { stderr += d.toString(); });
+    child.on('close', (code: number | null) => resolve({ stdout, stderr, code }));
+    child.on('error', (err: Error) => resolve({ stdout, stderr: stderr + '\\n' + err.message, code: -1 }));
+  });
+}
+`;
 }
+function generateTools(tools) {
+  return `/**
+ * Tool registry \u2014 one MCP tool per specverse CLI subcommand.
+ * Generated from the spec at realize time.
+ */
+import { runCli } from './cli-runner.js';
 
-export function getResourceByUri(uri: string) {
-  return SPEC_RESOURCES.find(r => r.uri === uri);
+export interface Tool {
+  name: string;
+  description: string;
+  cliArgs: string[];
+  positional: string[];
+  inputSchema: Record<string, any>;
+}
+
+export const TOOLS: Tool[] = ${JSON.stringify(tools, null, 2)};
+
+const BY_NAME = new Map<string, Tool>(TOOLS.map(t => [t.name, t]));
+
+export async function callTool(name: string, args: Record<string, any>) {
+  const tool = BY_NAME.get(name);
+  if (!tool) {
+    return {
+      isError: true,
+      content: [{ type: 'text', text: \`Unknown tool: \${name}\` }],
+    };
+  }
+  const { stdout, stderr, code } = await runCli(tool.cliArgs, tool.positional, args);
+  if (code !== 0) {
+    return {
+      isError: true,
+      content: [{ type: 'text', text: \`specverse \${tool.cliArgs.join(' ')} exited \${code}\\n\\n\${stderr || stdout}\` }],
+    };
+  }
+  return {
+    content: [{ type: 'text', text: stdout || '(no output)' }],
+  };
 }
 `;
 }
-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);
-    }
+function generateResources() {
+  return `/**
+ * Resource registry \u2014 exposes the live SpecVerse schema + user guide as
+ * MCP resources. Read lazily from @specverse/entities at request time so
+ * the contents always match the installed entities version.
+ */
+import { readFileSync } from 'fs';
+import { createRequire } from 'module';
+import { dirname, join } from 'path';
+
+const require = createRequire(import.meta.url);
+
+export interface Resource {
+  uri: string;
+  name: string;
+  description: string;
+  mimeType: string;
+  resolve: () => { text: string; mimeType: string };
+}
+
+function resolveEntitiesFile(relative: string): string {
+  const pkg = require.resolve('@specverse/entities/package.json');
+  return join(dirname(pkg), relative);
+}
+
+export const RESOURCES: Resource[] = [
+  {
+    uri: 'specverse://schema',
+    name: 'SpecVerse JSON Schema',
+    description: 'JSON Schema (draft 2020-12) for validating .specly files \u2014 composed from entity-module fragments.',
+    mimeType: 'application/json',
+    resolve: () => ({
+      text: readFileSync(resolveEntitiesFile('schema/SPECVERSE-SCHEMA.json'), 'utf8'),
+      mimeType: 'application/json',
+    }),
+  },
+  {
+    uri: 'specverse://guide',
+    name: 'SpecVerse Complete Guide',
+    description: 'The canonical user guide \u2014 spec language, convention patterns, CLI reference.',
+    mimeType: 'text/markdown',
+    resolve: () => ({
+      text: readFileSync(resolveEntitiesFile('schema/SPECVERSE-COMPLETE-GUIDE.md'), 'utf8'),
+      mimeType: 'text/markdown',
+    }),
+  },
+];
+
+const BY_URI = new Map<string, Resource>(RESOURCES.map(r => [r.uri, r]));
+
+export async function readResource(uri: string) {
+  const resource = BY_URI.get(uri);
+  if (!resource) {
+    throw new Error(\`Unknown resource URI: \${uri}\`);
   }
+  const { text, mimeType } = resource.resolve();
+  return {
+    contents: [{ uri, mimeType, text }],
+  };
+}
+`;
 }
 export {
   generateMCPServer as default