refero_design_md

Instructions

Implementation Reference

• src/tools/design-md.ts:40-70 (handler)

  Main handler for refero_design_md. Resolves an identifier via resolveAndFetch, renders the style as markdown via renderDesignMd, and optionally writes to vault/05-Projects/<name>/DESIGN.md.

  export async function handleDesignMd(args: DesignMdArgs): Promise<DesignMdResult> {
    const identifier = asIdentifier(args.identifier);
    const projectName = asProjectName(args.save_to_project);
  
    const full = await resolveAndFetch(identifier);
    const markdown = renderDesignMd(full);
  
    if (!projectName) {
      return {
        identifier,
        siteName: full.siteName,
        styleId: full.id,
        markdown,
      };
    }
  
    // resolveProjectDir throws PathSafetyError on bad input — let it propagate
    // so the MCP error envelope surfaces a useful message to the caller.
    const targetDir = resolveProjectDir(projectName);
    await mkdir(targetDir, { recursive: true });
    const targetPath = join(targetDir, "DESIGN.md");
    await writeFile(targetPath, markdown, "utf8");
  
    return {
      identifier,
      siteName: full.siteName,
      styleId: full.id,
      markdown,
      savedTo: targetPath,
    };
  }

• src/tools/design-md.ts:13-24 (schema)

  Input types (DesignMdArgs: identifier, save_to_project) and output shape (DesignMdResult) for the tool.

  export interface DesignMdArgs {
    identifier?: unknown;
    save_to_project?: unknown;
  }
  
  export interface DesignMdResult {
    identifier: string;
    siteName: string;
    styleId: string;
    markdown: string;
    savedTo?: string;
  }

• src/server.ts:75-94 (registration)

  Tool registration in the TOOLS array with name 'refero_design_md', description, inputSchema (identifier required, save_to_project optional).

  {
    name: "refero_design_md",
    description:
      "Render a Refero style as an agent-friendly DESIGN.md (frontmatter, north star, color table, fonts, dos/donts, tags). When `save_to_project` is set, writes the file to <vault>/05-Projects/<NAME>/DESIGN.md.",
    inputSchema: {
      type: "object",
      properties: {
        identifier: {
          type: "string",
          description: "uuid, hostname/URL, or site name to render.",
        },
        save_to_project: {
          type: "string",
          description: "Vault project folder name (e.g. \"PARZVL\"). Sanitized; must be [A-Za-z0-9_.-].",
        },
      },
      required: ["identifier"],
      additionalProperties: false,
    },
  },

• src/server.ts:166-167 (registration)

  Dispatch case in the CallToolRequestSchema switch that routes 'refero_design_md' to handleDesignMd.

  case "refero_design_md":
    return handleDesignMd(a);

• src/design-md.ts:51-144 (helper)

  The pure renderDesignMd function that takes a FullStyle and produces the DESIGN.md markdown string (frontmatter, north star, colors table, fonts, dos/donts, tags, footer).

  export function renderDesignMd(full: FullStyle): string {
    const ds = full.fullResult.designSystem;
    const detailUrl = `${REFERO_DETAIL_BASE}/${full.id}`;
    const extractedAt = isoDay(full.previewVideoCapturedAt ?? full.createdAt);
  
    // ---- Frontmatter ----
    const fmLines: string[] = [
      "---",
      `source_url: ${yamlEscape(full.url)}`,
      `site_name: ${yamlEscape(full.siteName)}`,
      `extracted_at: ${yamlEscape(extractedAt)}`,
      `theme: ${yamlEscape(ds.theme ?? full.colorScheme)}`,
    ];
    if (full.industry) fmLines.push(`industry: ${yamlEscape(full.industry)}`);
    fmLines.push(`tags: ${yamlList(ds.tags ?? [])}`);
    fmLines.push("---", "");
  
    // ---- Heading + north star ----
    const lines: string[] = [
      ...fmLines,
      `# ${full.siteName}`,
      "",
    ];
    if (full.northStar && full.northStar.trim()) {
      for (const ln of full.northStar.trim().split(/\r?\n/)) {
        lines.push(`> ${ln}`);
      }
      lines.push("");
    }
  
    // ---- Colors ----
    const colors = ds.colors ?? [];
    if (colors.length > 0) {
      lines.push(
        "## Colors",
        "",
        "| Hex | Name | Role | Group |",
        "| --- | --- | --- | --- |",
        ...colors.map(colorRow),
        "",
      );
    }
  
    // ---- Fonts ----
    const fonts = ds.fonts ?? full.fonts ?? [];
    if (fonts.length > 0) {
      lines.push(
        "## Fonts",
        "",
        ...fonts.map((f) => `- ${f}`),
        "",
      );
    }
  
    // ---- Do ----
    if ((ds.dos ?? []).length > 0) {
      lines.push(
        "## Do",
        "",
        ...ds.dos.map((d) => `- ${d}`),
        "",
      );
    }
  
    // ---- Don't ----
    if ((ds.donts ?? []).length > 0) {
      lines.push(
        "## Don't",
        "",
        ...ds.donts.map((d) => `- ${d}`),
        "",
      );
    }
  
    // ---- Tags ----
    if ((ds.tags ?? []).length > 0) {
      lines.push(
        "## Tags",
        "",
        ds.tags.map((t) => `\`${t}\``).join(" · "),
        "",
      );
    }
  
    // ---- Footer ----
    lines.push(
      "---",
      "",
      `Generated by refero-mcp from ${detailUrl} on ${extractedAt}`,
      "",
    );
  
    return lines.join("\n");
  }