generate_from_template

Instructions

Implementation Reference

• packages/mcp/src/tools.ts:300-353 (handler)

  The MCP tool handler for 'generate_from_template'. It extracts args (template, locale, scale, format, seed), calls generateFromTemplate() to build a GenerateRequest, invokes generate() to produce data, and optionally formats the output (CSV/SQL).

  async function handleGenerateFromTemplate(
    args: Record<string, unknown>
  ): Promise<ToolResult> {
    const { template, locale, scale, format, seed } = args as {
      template: string;
      locale?: string;
      scale?: number;
      format?: string;
      seed?: number;
    };
  
    if (!template) {
      return err("'template' is required. Available templates: ecommerce, blog, saas, social");
    }
  
    let request: GenerateRequest;
    try {
      request = generateFromTemplate({
        template,
        locale: locale as GenerateRequest["locale"],
        scale,
        format: format as GenerateRequest["format"],
        seed,
      });
    } catch (e) {
      return err(`Template error: ${e instanceof Error ? e.message : String(e)}`);
    }
  
    const result = await generate(request);
    if (!result.success) {
      if ("errors" in result) {
        return err(
          `Generation failed:\n${result.errors
            .map((e) => `  - ${e.field}: ${e.message}`)
            .join("\n")}`
        );
      }
      return err(`Generation failed: circular dependency between tables: ${result.cycle.join(" -> ")}`);
    }
  
    // Optionally format output
    if (format && format !== "json") {
      const sqlDialect = args.sql_dialect as string | undefined;
      const formatted = formatOutput(
        result.result,
        request.tables,
        format as "csv" | "sql",
        sqlDialect as "postgres" | "mysql" | "sqlite" | undefined
      );
      return ok(formatted.body);
    }
  
    return ok({ data: result.result.data, meta: result.result.meta });
  }

• src/lib/engine/templates/index.ts:50-86 (helper)

  The core generateFromTemplate() helper function. It looks up the template in TEMPLATE_REGISTRY, applies the scale multiplier to each table's count (clamped 0.01-100), and builds a GenerateRequest with optional overrides for locale, format, sql_dialect, and seed.

  export function generateFromTemplate(options: TemplateGenerateOptions): GenerateRequest {
    const template = TEMPLATE_REGISTRY[options.template];
    if (!template) {
      throw new Error(`Unknown template: "${options.template}"`);
    }
  
    const rawScale = options.scale ?? 1;
    if (rawScale < 0) {
      throw new Error(`Invalid scale: ${rawScale}. Scale must be a positive number (e.g. 0.5 for half, 2 for double).`);
    }
    const scale = Math.min(Math.max(rawScale, 0.01), 100);
  
    const tables = template.schema.tables.map((table) => ({
      ...table,
      count: Math.max(1, Math.round(table.count * scale)),
    }));
  
    const request: GenerateRequest = {
      ...template.schema,
      tables,
    };
  
    if (options.locale !== undefined) {
      request.locale = options.locale;
    }
    if (options.format !== undefined) {
      request.format = options.format;
    }
    if (options.sql_dialect !== undefined) {
      request.sql_dialect = options.sql_dialect;
    }
    if (options.seed !== undefined) {
      request.seed = options.seed;
    }
  
    return request;
  }

• src/lib/engine/templates/types.ts:1-28 (schema)

  Type definitions for TemplateGenerateOptions (what generateFromTemplate accepts) and TemplateDefinition/TemplateSummary (template registry structure).

  import type { GenerateRequest, Locale, OutputFormat, SqlDialect } from "../types";
  
  export interface TemplateDefinition {
    id: string;
    name: string;
    description: string;
    tables: string[]; // table names
    default_counts: Record<string, number>;
    schema: GenerateRequest;
  }
  
  export interface TemplateSummary {
    id: string;
    name: string;
    description: string;
    tables: string[];
    default_counts: Record<string, number>;
  }
  
  export interface TemplateGenerateOptions {
    template: string;
    locale?: Locale;
    scale?: number; // multiplier for all table counts
    format?: OutputFormat;
    sql_dialect?: SqlDialect;
    seed?: number;
  }

• packages/mcp/src/tools.ts:152-185 (schema)

  MCP tool inputSchema definition for generate_from_template, defining the JSON schema for template, locale, scale, format, and seed parameters.

  {
    name: "generate_from_template",
    description:
      "Generate test data using a pre-built template. Available templates: ecommerce, blog, saas, social. Use 'scale' to multiply record counts.",
    inputSchema: {
      type: "object",
      properties: {
        template: {
          type: "string",
          description:
            "Template ID: ecommerce, blog, saas, or social",
        },
        locale: {
          type: "string",
          description: "Locale for generated data. Default: en",
        },
        scale: {
          type: "number",
          description:
            "Multiplier for all table record counts. E.g. scale=10 generates 10x the default rows.",
        },
        format: {
          type: "string",
          enum: ["json", "csv", "sql"],
          description: "Output format. Default: json",
        },
        seed: {
          type: "number",
          description: "PRNG seed for reproducible output.",
        },
      },
      required: ["template"],
    },
  },

• packages/mcp-server/src/index.ts:331-406 (registration)

  MCP server registration of the 'generate_from_template' tool using server.tool() with Zod schema validation and a handler that calls the API endpoint POST /api/v1/generate.

  // Tool: generate_from_template
  // ---------------------------------------------------------------------------
  
  server.tool(
    "generate_from_template",
    `Generate test data using a pre-built schema template.
  
  Pick a template (ecommerce, blog, saas, social) and optionally adjust the scale,
  locale, format, and seed. The template handles all the table definitions,
  field types, and foreign key relationships for you.
  
  Scale multiplier: 1.0 = default counts, 2.0 = double, 0.5 = half.
  Example: ecommerce template at scale 2.0 generates 100 users, 200 products, etc.`,
    {
      template: z
        .enum(["ecommerce", "blog", "saas", "social"])
        .describe("Template name"),
      scale: z
        .number()
        .optional()
        .default(1.0)
        .describe("Scale multiplier for record counts (default 1.0)"),
      locale: z
        .string()
        .optional()
        .describe("Default locale (en, de, fr, es, etc.)"),
      format: z
        .enum(["json", "csv", "sql"])
        .optional()
        .default("json")
        .describe("Output format"),
      sql_dialect: z
        .enum(["postgres", "mysql", "sqlite"])
        .optional()
        .describe("SQL dialect (only when format=sql)"),
      seed: z
        .number()
        .optional()
        .describe("Seed for reproducible output"),
    },
    async (params) => {
      // Templates are resolved server-side via the generate endpoint
      // We construct a request with the template parameter
      const body: Record<string, unknown> = {
        template: params.template,
        scale: params.scale,
      };
      if (params.locale) body.locale = params.locale;
      if (params.format) body.format = params.format;
      if (params.sql_dialect) body.sql_dialect = params.sql_dialect;
      if (params.seed !== undefined) body.seed = params.seed;
  
      const res = await apiCall("POST", "/api/v1/generate", body);
  
      if (!res.ok) {
        return {
          content: [
            {
              type: "text" as const,
              text: `API error (${res.status}): ${JSON.stringify(res.data, null, 2)}`,
            },
          ],
          isError: true,
        };
      }
  
      return {
        content: [
          {
            type: "text" as const,
            text: JSON.stringify(res.data, null, 2),
          },
        ],
      };
    }
  );