generate_svg

Instructions

Implementation Reference

• src/index.ts:103-201 (registration)

  Registration of the 'generate_svg' tool in the ListToolsRequestSchema handler, including its description and input schema.

  {
    name: "generate_svg",
    description:
      "Generate one or more SVGs from a text prompt using QuiverAI. Returns raw SVG markup.\n\n" +
      "## Prompt guide\n\n" +
      "A good prompt has three parts: **subject** (specific object), **style** (aesthetic keywords), and **color palette** (hex codes if possible).\n\n" +
      "### What works\n" +
      "- Use concrete, famous physical objects the model has seen (AirPods, Nike Dunks, Shure SM7B, Montblanc pen, Leica camera, Nest thermostat, espresso machines). " +
      "Cylindrical/round objects explode especially cleanly in isometric style.\n" +
      "- Name the style explicitly: 'line art', 'hand drawn', 'duotone', 'flat monochrome icon', 'geometric', 'minimalist', 'isometric', 'blueprint'.\n" +
      "- Specify colors with hex codes: 'background: #e9edc9 and logo in #fb8500'.\n" +
      "- Add composition framing: 'centered icon', 'wide horizontal logo'.\n" +
      "- Prompt modifiers: 'geometric' → angular shapes, 'detailed' → more elements, 'simple' → clearer shapes, 'minimalist' → fewer details, 'flat monochrome' → single-color, 'duotone' → two-color.\n\n" +
      "### What does NOT work\n" +
      "- NEVER mention 'AI', 'machine learning', 'voice assistant', 'workflow automation', or abstract software concepts — produces garbage. Use physical metaphors instead (microphone for voice, watch movement for precision).\n" +
      "- Abstract concepts without physical objects: 'knowledge graph', 'automation pipeline', 'data flow'.\n" +
      "- Obscure B2B hardware the model hasn't seen (e.g. Loxone Miniserver → generic blob).\n" +
      "- 'minimalist line icon' constraints — model ignores them and fills with color.\n\n" +
      "### Iteration strategy\n" +
      "Start specific, not vague. Bad: 'Tech logo'. Better: 'Tech startup logo with geometric shapes, blue gradient'. " +
      "Best: 'SaaS productivity logo with connected geometric nodes, electric blue to purple gradient, clean modern style'.\n\n" +
      "### Verified template\n" +
      "`exploded isometric view of a {FAMOUS_OBJECT}, technical blueprint drawing, thin line art, dotted grid background, labeled components, engineering illustration`\n\n" +
      "### Known issues\n" +
      "- ~1 in 10 generations have corrupted SVG tails (malformed XML). Generate 3+ variants as insurance.\n" +
      "- Model may ignore 'no fills'/'monochrome' and hardcode its own palette. Post-process with find/replace for brand colors.\n" +
      "- First call may 504 — retry succeeds.",
    inputSchema: {
      type: "object",
      required: ["prompt", "model"],
      properties: {
        prompt: {
          type: "string",
          description:
            "WHAT to generate. Be specific: name a concrete famous object, add style keywords, and specify colors with hex codes. " +
            "Example: 'Heraldic lion crest with ornate medieval style details and gold gradient accents'. " +
            "Never use abstract concepts like 'AI agent' or 'workflow' — use physical metaphors instead.",
        },
        model: {
          type: "string",
          description:
            "Model ID to use. Recommended: 'arrow-preview' (Arrow 1.0, #1 on SVG Arena). Use list_models to discover all options.",
        },
        instructions: {
          type: "string",
          description:
            "HOW it should look — style guidance separate from the subject. Think of prompt as 'what' and instructions as 'how'. " +
            "Example: prompt='Japanese crane', instructions='Use a warm muted palette with detailed feather work'.",
        },
        n: {
          type: "number",
          description:
            "Number of SVG variants to generate (max 16). Recommended: 3+ at higher temperature for best results, since ~1 in 10 generations can have corrupted tails.",
        },
        temperature: {
          type: "number",
          description:
            "Sampling temperature (0–2). Lower (0.4) = more consistent, higher (0.9) = more creative variation. Use 0.9 with n≥3 for exploration.",
        },
        references: {
          type: "array",
          description:
            "Up to 4 reference images for style, color, and composition guidance. " +
            "References pull palette/color hints from the image, but style keywords ('blueprint', 'isometric', 'flat') must still be in the text prompt — references alone won't change drawing style.",
          items: {
            type: "object",
            oneOf: [
              {
                required: ["url"],
                properties: {
                  url: {
                    type: "string",
                    description: "HTTP/HTTPS image URL.",
                  },
                },
              },
              {
                required: ["base64"],
                properties: {
                  base64: {
                    type: "string",
                    description: "Base64-encoded image data.",
                  },
                },
              },
            ],
          },
        },
        outputPath: {
          type: "string",
          description:
            "Optional absolute file path to save the SVG(s) to disk. " +
            "If omitted, SVG markup is returned in the response only. " +
            "For multiple variants (n > 1), files are saved with _1, _2 … suffixes. " +
            "Parent directories are created automatically.",
        },
      },
    },
  },

• src/index.ts:130-200 (schema)

  Input schema for the generate_svg tool, defining required parameters (prompt, model) and optional parameters (instructions, n, temperature, references, outputPath).

  inputSchema: {
    type: "object",
    required: ["prompt", "model"],
    properties: {
      prompt: {
        type: "string",
        description:
          "WHAT to generate. Be specific: name a concrete famous object, add style keywords, and specify colors with hex codes. " +
          "Example: 'Heraldic lion crest with ornate medieval style details and gold gradient accents'. " +
          "Never use abstract concepts like 'AI agent' or 'workflow' — use physical metaphors instead.",
      },
      model: {
        type: "string",
        description:
          "Model ID to use. Recommended: 'arrow-preview' (Arrow 1.0, #1 on SVG Arena). Use list_models to discover all options.",
      },
      instructions: {
        type: "string",
        description:
          "HOW it should look — style guidance separate from the subject. Think of prompt as 'what' and instructions as 'how'. " +
          "Example: prompt='Japanese crane', instructions='Use a warm muted palette with detailed feather work'.",
      },
      n: {
        type: "number",
        description:
          "Number of SVG variants to generate (max 16). Recommended: 3+ at higher temperature for best results, since ~1 in 10 generations can have corrupted tails.",
      },
      temperature: {
        type: "number",
        description:
          "Sampling temperature (0–2). Lower (0.4) = more consistent, higher (0.9) = more creative variation. Use 0.9 with n≥3 for exploration.",
      },
      references: {
        type: "array",
        description:
          "Up to 4 reference images for style, color, and composition guidance. " +
          "References pull palette/color hints from the image, but style keywords ('blueprint', 'isometric', 'flat') must still be in the text prompt — references alone won't change drawing style.",
        items: {
          type: "object",
          oneOf: [
            {
              required: ["url"],
              properties: {
                url: {
                  type: "string",
                  description: "HTTP/HTTPS image URL.",
                },
              },
            },
            {
              required: ["base64"],
              properties: {
                base64: {
                  type: "string",
                  description: "Base64-encoded image data.",
                },
              },
            },
          ],
        },
      },
      outputPath: {
        type: "string",
        description:
          "Optional absolute file path to save the SVG(s) to disk. " +
          "If omitted, SVG markup is returned in the response only. " +
          "For multiple variants (n > 1), files are saved with _1, _2 … suffixes. " +
          "Parent directories are created automatically.",
      },
    },
  },

• src/index.ts:278-321 (handler)

  Handler for the generate_svg tool: destructures args, calls quiver.createSVGs.generateSVG(), validates response with assertSvgResponse, formats SVG content, and optionally writes files using writeSvgs helper.

  if (name === "generate_svg") {
    const { prompt, model, instructions, n, temperature, references, outputPath } =
      args as {
        prompt: string;
        model: string;
        instructions?: string;
        n?: number;
        temperature?: number;
        references?: Array<{ url?: string; base64?: string }>;
        outputPath?: string;
      };
  
    const response = await quiver.createSVGs.generateSVG({
      prompt,
      model,
      instructions,
      n,
      temperature,
      stream: false,
      references: references?.map((ref) =>
        ref.url !== undefined
          ? { url: ref.url }
          : { base64: ref.base64! }
      ),
    });
  
    const result = response.result;
    assertSvgResponse(result);
  
    const rawSvgs = result.data.map((d) => d.svg);
    const content = rawSvgs.map((svg, i) => ({
      type: "text" as const,
      text: n && n > 1 ? `<!-- SVG ${i + 1} -->\n${svg}` : svg,
    }));
  
    if (outputPath) {
      const paths = await writeSvgs(rawSvgs, outputPath);
      content.push({
        type: "text" as const,
        text: `Saved to: ${paths.join(", ")}`,
      });
    }
  
    return { content };

• src/index.ts:28-42 (helper)

  Helper type-guard assertion function that validates the QuiverAI API response has the expected shape (an object with a data array of svg strings). Used by the generate_svg handler.

  function assertSvgResponse(
    result: unknown
  ): asserts result is { data: Array<{ svg: string }> } {
    if (
      typeof result !== "object" ||
      result === null ||
      !("data" in result) ||
      !Array.isArray((result as Record<string, unknown>).data)
    ) {
      const err = result as { message?: string };
      throw new Error(
        `QuiverAI API error: ${err.message ?? JSON.stringify(result)}`
      );
    }
  }

• src/index.ts:74-97 (helper)

  Helper function that writes SVG string(s) to disk, handling single vs. multiple file naming with _1, _2 suffixes.

  async function writeSvgs(
    svgs: string[],
    outputPath: string
  ): Promise<string[]> {
    await mkdir(dirname(outputPath), { recursive: true });
  
    if (svgs.length === 1) {
      const p = outputPath.endsWith(".svg") ? outputPath : `${outputPath}.svg`;
      await writeFile(p, svgs[0], "utf-8");
      return [p];
    }
  
    const ext = extname(outputPath);
    const base = ext ? outputPath.slice(0, -ext.length) : outputPath;
    const suffix = ext || ".svg";
  
    const paths: string[] = [];
    for (let i = 0; i < svgs.length; i++) {
      const p = `${base}_${i + 1}${suffix}`;
      await writeFile(p, svgs[i], "utf-8");
      paths.push(p);
    }
    return paths;
  }