@specverse/engines 4.3.5 → 5.0.1

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

@@ -1,190 +1,441 @@
 /**
- * MCP Server Generator
+ * MCP Server Generator (lean)
  *
- * Generates a Model Context Protocol server from the SpecVerse spec.
- * Ships the core server framework as static assets, generates tool/resource
- * registration from the spec's ToolsSupport and CLI components.
+ * Generates a Model Context Protocol server fully from the SpecVerse spec.
+ *
+ * Design: the MCP server is a thin wrapper around the specverse CLI. Every
+ * CLI command declared in the spec becomes an invocable MCP tool; the live
+ * JSON schema + user guide from @specverse/entities are served as MCP
+ * resources. No static framework to maintain — everything is emitted from
+ * the spec so a new CLI command auto-appears as a new MCP tool on the next
+ * realize.
  */
 
 import type { TemplateContext } from '@specverse/types';
-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';
 
 export default function generateMCPServer(context: TemplateContext): string {
   const { spec, outputDir } = context;
 
   const mcpDir = join(outputDir || '.', 'tools', 'specverse-mcp');
-  if (!existsSync(mcpDir)) mkdirSync(mcpDir, { recursive: true });
-
-  // 1. Copy static MCP server framework
-  // Check both source location (libs/) and compiled location (dist/libs/)
-  let staticDir = join(__generatorDir, 'static');
-  if (!existsSync(staticDir)) {
-    // Compiled JS is in dist/libs/ — static assets are in libs/
-    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 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 — exposes the specverse CLI as MCP tools and the live spec schema + docs as MCP resources.';
+  const displayName = distribution?.displayName || 'SpecVerse MCP';
 
-  // 2. Generate tool registry from spec
-  const tools = extractMCPTools(spec);
-  const resources = extractMCPResources(spec);
-  const cliCommands = extractCLICommands(spec);
+  const cliCommands = extractCLITools(spec);
 
-  // 3. Generate a spec-driven registration file
-  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);
+  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}\n  ${tools.length} tools, ${resources.length} resources, ${cliCommands.length} CLI commands`;
+  return `MCP server generated in: ${mcpDir}\n  ${cliCommands.length} tools (one per CLI command), 2 resources (schema + docs)`;
 }
 
-function extractMCPTools(spec: any): Array<{ name: string; description: string; isEntityTool: boolean }> {
-  const tools: Array<{ name: string; description: string; isEntityTool: boolean }> = [];
-  const components = spec?.components || {};
-  const componentList = Array.isArray(components) ? components : Object.values(components);
+// ─── spec extraction ───────────────────────────────────────────────────────
 
-  // Also check top-level services (AI-optimized spec format)
-  if (spec?.services && !Array.isArray(components)) {
-    componentList.push({ services: spec.services, models: spec.models } as any);
-  }
+/**
+ * Flatten the spec's CLI commands (components[*].commands[*].subcommands[*])
+ * into one entry per invocable leaf. Each becomes an MCP tool.
+ *
+ * - `validate <file>` → name `validate`, cliArgs `['validate']`
+ * - `gen diagrams <file>` → name `gen_diagrams`, cliArgs `['gen', 'diagrams']`
+ *
+ * Arguments/flags declared in the spec become the tool's JSON-Schema input.
+ */
+function extractCLITools(spec: any): CLITool[] {
+  const out: CLITool[] = [];
+  const components = spec?.components || {};
+  const componentList = Array.isArray(components)
+    ? components
+    : Object.entries(components).map(([name, data]) => ({ name, ...(data as any) }));
 
-  for (const component of componentList) {
-    const comp = component as any;
-
-    // Extract from services — each service operation becomes an MCP tool
-    const services = comp?.services;
-    if (services) {
-      const serviceList = Array.isArray(services) ? services : Object.entries(services).map(([n, d]) => ({ name: n, ...(d as any) }));
-      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 as any) }));
-          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,
-            });
-          }
-        }
-      }
-    }
+  for (const comp of componentList) {
+    const cliCommands = (comp as any)?.commands;
+    if (!cliCommands) continue;
 
-    // Extract from model behaviors — each behavior becomes an MCP tool
-    const models = comp?.models;
-    if (models) {
-      const modelList = Array.isArray(models) ? models : Object.entries(models).map(([n, d]) => ({ name: n, ...(d as any) }));
-      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 as any) }))
-            : [];
-          for (const behavior of behaviorEntries) {
-            tools.push({
-              name: `${model.name.toLowerCase()}-${behavior.name}`,
-              description: behavior.description || `${behavior.name} on ${model.name}`,
-              isEntityTool: true,
-            });
+    for (const [, rootDef] of Object.entries(cliCommands as Record<string, any>)) {
+      const subcommands = (rootDef as any)?.subcommands || {};
+      for (const [subName, subDef] of Object.entries(subcommands as Record<string, any>)) {
+        const sub = subDef as any;
+        const nestedSubs = sub?.subcommands;
+        if (nestedSubs && Object.keys(nestedSubs).length > 0) {
+          for (const [nestedName, nestedDef] of Object.entries(nestedSubs as Record<string, any>)) {
+            out.push(buildCLITool([subName, nestedName], nestedDef as any));
           }
+        } else {
+          out.push(buildCLITool([subName], sub));
         }
       }
     }
   }
+  return out;
+}
 
-  // Also extract from CLI commands
-  const cliCmds = extractCLICommands(spec);
-  for (const cmd of cliCmds) {
-    tools.push({
-      name: `specverse-${cmd}`,
-      description: `Execute specverse ${cmd} command`,
-      isEntityTool: false,
-    });
+interface CLITool {
+  name: string;                // MCP tool name (underscored)
+  description: string;
+  cliArgs: string[];           // argv pieces before user args (["gen","diagrams"])
+  positional: string[];        // input-schema keys to emit as positional argv, in order
+  inputSchema: Record<string, any>;
+}
+
+function buildCLITool(cliArgs: string[], def: any): CLITool {
+  const name = cliArgs.join('_');
+  const description = def?.description || `Run specverse ${cliArgs.join(' ')}`;
+  const properties: Record<string, any> = {};
+  const required: string[] = [];
+
+  const args = def?.arguments || {};
+  // Collect positionals in declaration order, respecting an optional
+  // `position` field (rank ascending; default 0). Named flags that
+  // happen to share a key with a positional are impossible — the spec
+  // forbids it.
+  const positionalEntries: Array<[string, any]> = Object.entries(args as Record<string, any>)
+    .filter(([, a]) => (a as any).positional)
+    .sort(([, a], [, b]) => ((a as any).position || 0) - ((b as any).position || 0));
+  const positional: string[] = positionalEntries.map(([k]) => k);
+
+  for (const [argName, arg] of Object.entries(args as Record<string, any>)) {
+    properties[argName] = {
+      type: mapArgTypeToJsonSchema((arg as any).type),
+      description: (arg as any).description || `${argName} argument`,
+    };
+    if ((arg as any).required) required.push(argName);
   }
 
-  // Default fallback
-  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 as Record<string, any>)) {
+    const propName = flagName.replace(/^--/, '').replace(/-([a-z])/g, (_, c: string) => c.toUpperCase());
+    properties[propName] = {
+      type: mapArgTypeToJsonSchema((flag as any).type),
+      description: (flag as any).description || `${flagName} flag`,
+    };
+    if ((flag as any).default !== undefined) {
+      properties[propName].default = (flag as any).default;
+    }
   }
-  return tools;
+
+  return {
+    name,
+    description,
+    cliArgs,
+    positional,
+    inputSchema: {
+      type: 'object',
+      properties,
+      ...(required.length > 0 ? { required } : {}),
+    },
+  };
 }
 
-function extractMCPResources(spec: any): Array<{ uri: string; name: string; description: string }> {
-  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 mapArgTypeToJsonSchema(type?: string): string {
+  if (!type) return 'string';
+  const t = type.toLowerCase();
+  if (t === 'boolean') return 'boolean';
+  if (t === 'integer' || t === 'number') return 'number';
+  return 'string';
 }
 
-function extractCLICommands(spec: any): string[] {
-  const commands: string[] = [];
-  const components = spec?.components || [];
-  for (const component of Array.isArray(components) ? components : Object.values(components)) {
-    const cliCommands = (component as any)?.commands;
-    if (!cliCommands) continue;
-    for (const [, rootDef] of Object.entries(cliCommands as Record<string, any>)) {
-      const subs = (rootDef as any)?.subcommands || {};
-      for (const subName of Object.keys(subs)) {
-        commands.push(subName);
-      }
-    }
+function extractMCPDistribution(spec: any): any | null {
+  const all: any[] = [];
+  if (spec?.distributions) {
+    all.push(...(Array.isArray(spec.distributions)
+      ? spec.distributions
+      : Object.entries(spec.distributions).map(([name, data]) => ({ name, ...(data as any) }))));
+  }
+  const components = spec?.components || {};
+  const componentList = Array.isArray(components) ? components : Object.values(components);
+  for (const comp of componentList) {
+    const distributions = (comp as any)?.distributions;
+    if (!distributions) continue;
+    all.push(...(Array.isArray(distributions)
+      ? distributions
+      : Object.entries(distributions).map(([name, data]) => ({ name, ...(data as any) }))));
   }
-  return commands;
+  for (const dist of all) if ((dist as any).type === 'mcp') return dist;
+  return null;
+}
+
+// ─── emitted files ─────────────────────────────────────────────────────────
+
+function generatePackageJson(version: string, description: string): string {
+  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 generateToolRegistry(
-  tools: Array<{ name: string; description: string; isEntityTool: boolean }>,
-  resources: Array<{ uri: string; name: string; description: string }>,
-  cliCommands: string[]
-): string {
+function generateTsconfig(): string {
+  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: string, version: string): string {
+  return `#!/usr/bin/env node
+/**
+ * SpecVerse MCP Server — stdio transport.
+ *
+ * Wires the MCP protocol to the generated tool registry + live resources.
+ * No handwritten business logic — 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 generateCliRunner(): string {
   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\`) — 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 function runCli(
+  cliArgs: string[],
+  positional: string[],
+  userArgs: Record<string, any>,
+  cwd?: string,
+): Promise<CliResult> {
+  const argv = [...cliArgs];
 
-export const SPEC_TOOLS = ${JSON.stringify(tools, null, 2)};
+  // 1. Positional args first, in spec-declared order. Undefined values
+  //    are skipped — 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));
+  }
+
+  // 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 const SPEC_RESOURCES = ${JSON.stringify(resources, null, 2)};
+  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 }));
+  });
+}
+`;
+}
 
-export const CLI_COMMANDS = ${JSON.stringify(cliCommands, null, 2)};
+function generateTools(tools: CLITool[]): string {
+  return `/**
+ * Tool registry — one MCP tool per specverse CLI subcommand.
+ * Generated from the spec at realize time.
+ */
+import { runCli } from './cli-runner.js';
 
-export function getToolByName(name: string) {
-  return SPEC_TOOLS.find(t => t.name === name);
+export interface Tool {
+  name: string;
+  description: string;
+  cliArgs: string[];
+  positional: string[];
+  inputSchema: Record<string, any>;
 }
 
-export function getResourceByUri(uri: string) {
-  return SPEC_RESOURCES.find(r => r.uri === uri);
+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: string, dest: string) {
-  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(): string {
+  return `/**
+ * Resource registry — 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 — 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 — 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 }],
+  };
+}
+`;
 }

package/libs/instance-factories/tools/templates/vscode/static/extension.ts

@@ -1002,8 +1002,12 @@ async function executeCliCommand(document: vscode.TextDocument, commandName: str
     'cache': 'cache',
     'help': 'help',
     'gen': 'gen',
-    'dev': 'dev', 
+    'dev': 'dev',
     'test': 'test',
+    // realize requires a positional type arg; default the menu action to
+    // "realize all" (full regeneration). Per-entity dispatch is a future
+    // design — see TODO: "Derive realize subtypes from entity registry".
+    'realize': 'realize all',
     
     // Grouped commands - map compressed names to CLI format
     'genyaml': 'gen yaml',
@@ -1018,7 +1022,10 @@ async function executeCliCommand(document: vscode.TextDocument, commandName: str
     'testbatch': 'test batch'
   };
   
-  const cliCommand = commandMap[commandName] || commandName;
+  // Fall through: convert dotted form (e.g. "realize.all") to space-separated
+  // CLI args (e.g. "realize all") so auto-generated subcommand entries work
+  // without needing a commandMap entry for every one.
+  const cliCommand = commandMap[commandName] || commandName.replace(/\./g, ' ');
   
   try {
     const config = vscode.workspace.getConfiguration('specverse');