nakkas

Instructions

Implementation Reference

• src/index.ts:211-284 (handler)

  Registration of the 'save' tool in src/index.ts.

  // Tool: save
  // ---------------------------------------------------------------------------
  
  server.registerTool(
    "save",
    {
      title: "Save Content",
      description: `
  Save rendered content to disk. Format-aware: can save as text or render to raster image.
  
  IMPORTANT: Use this only AFTER iterating on the design with render and preview.
  Do not save on the first render. Preview and refine your work first.
  
  **Format detection:**
  - 'auto' (default): infers format from file extension. .svg saves as text, .png renders to image.
  - 'svg': saves content as a UTF-8 text file
  - 'png': renders the content (assumed SVG) to a PNG image, then saves it
  
  If the file already exists, a numeric counter is appended before the extension
  to prevent overwriting: design.svg becomes design-1.svg, then design-2.svg.
  The actual saved path is returned in the response.
      `.trim(),
      inputSchema: z.object({
        content: z
          .string()
          .describe(
            "Content to save. This is typically the output of a render tool such as render_svg."
          ),
        outputPath: z
          .string()
          .describe(
            "File path to save to. The directory must already exist. " +
              "If the file already exists, a numeric counter is appended before the extension: " +
              "design.svg becomes design-1.svg, then design-2.svg, and so on. " +
              "The actual saved path is returned in the response."
          ),
        format: z
          .enum(["auto", "svg", "png"])
          .default("auto")
          .describe(
            "Output format. " +
              "'auto' infers from file extension (.svg saves as text, .png renders to image). " +
              "'svg' saves content as a UTF-8 text file. " +
              "'png' renders SVG content to a PNG image before saving."
          ),
        width: z
          .number()
          .positive()
          .optional()
          .describe(
            "For raster formats (png): render width in pixels. " +
              "Defaults to the source content's own declared dimensions."
          ),
      }),
    },
    async ({ content, outputPath, format, width }) => {
      const start = Date.now();
      try {
        const savedPath = await saveContent(content, outputPath, format, width);
        const elapsed = Date.now() - start;
        console.error(`[nakkas] save OK — ${savedPath}, ${elapsed}ms`);
        return {
          content: [{ type: "text", text: `Saved to: ${savedPath}` }],
        };
      } catch (err) {
        const message = err instanceof Error ? err.message : String(err);
        console.error(`[nakkas] save ERROR — ${message}`);
        return {
          content: [{ type: "text", text: `Error saving file: ${message}` }],
          isError: true,
        };
      }
    }
  );

• src/save.ts:53-70 (handler)

  The implementation logic of the 'save' tool, which delegates to saveContent in src/save.ts.

  export async function saveContent(
    content: string,
    outputPath: string,
    format: "auto" | "svg" | "png",
    width?: number
  ): Promise<string> {
    const resolved = await resolveOutputPath(outputPath);
    const effectiveFormat = format === "auto" ? inferFormat(resolved) : format;
  
    if (effectiveFormat === "png") {
      const pngBuffer = svgToPng(content, width);
      await writeFile(resolved, pngBuffer);
    } else {
      await writeFile(resolved, content, "utf-8");
    }
  
    return resolved;
  }

• src/save.ts:19-35 (helper)

  Helper for resolving output paths with automatic filename incrementing for collision prevention.

  export async function resolveOutputPath(requested: string): Promise<string> {
    const exists = (p: string) =>
      access(p)
        .then(() => true)
        .catch(() => false);
  
    if (!(await exists(requested))) return requested;
  
    const dir = dirname(requested);
    const ext = extname(requested);
    const stem = basename(requested, ext);
  
    for (let i = 1; ; i++) {
      const candidate = join(dir, `${stem}-${i}${ext}`);
      if (!(await exists(candidate))) return candidate;
    }
  }