sdd-es 2.0.0

package/mcp-figma/package.json

@@ -0,0 +1,7 @@
+{
+  "name": "sdd-figma-mcp",
+  "version": "1.0.0",
+  "description": "MCP server para integración de Figma con SDD-ES — cero dependencias externas",
+  "type": "module",
+  "main": "src/index.js"
+}

package/mcp-figma/src/component-generator.js

@@ -0,0 +1,162 @@
+// @ts-check
+import { existsSync } from "fs";
+import { join } from "path";
+
+/**
+ * @typedef {{ figmaName:string, figmaValue:string, localToken:string|null, matchType:string }} ColorMapping
+ * @typedef {{ type:string, color?:{r:number,g:number,b:number}, fills?:any[], children?:any[], name:string, absoluteBoundingBox?:{width:number,height:number}, style?:any }} FigmaNode
+ * @typedef {{ stack:{ framework:string, cssApproach:string, hasTokenFile:boolean }, colors:Record<string,string>, spacing:Record<string,string>, typography:{ fontFamilies:string[], fontSizes:Record<string,string>, fontWeights:Record<string,string> }, existingComponents:string[], breakpoints:Record<string,string>, shadows:Record<string,string> }} DesignProfile
+ */
+
+/** @param {string} str */
+function toPascalCase(str) {
+  return str.replace(/[^a-zA-Z0-9\s]/g, " ").split(/\s+/).filter(Boolean)
+    .map(w => w[0].toUpperCase() + w.slice(1).toLowerCase()).join("");
+}
+
+/** @param {string} str */
+function toKebabCase(str) {
+  return str.replace(/[^a-zA-Z0-9\s]/g, " ").split(/\s+/).filter(Boolean).join("-").toLowerCase();
+}
+
+/** @param {FigmaNode} node */
+function inferProps(node) {
+  /** @type {Record<string,string>} */
+  const props = {};
+  const name = node.name.toLowerCase();
+  const hasText = (node.children ?? []).some(/** @param {any} c */ c => c.type === "TEXT");
+  if (hasText || /(button|label|title|heading)/.test(name)) props["children"] = "ReactNode";
+  if (/(button|btn|cta|link)/.test(name)) { props["onClick"] = "() => void"; props["disabled"] = "boolean"; }
+  if ((node.children ?? []).some(/** @param {any} c */ c => /(image|img|avatar)/.test(c.name.toLowerCase()))) { props["src"] = "string"; props["alt"] = "string"; }
+  if (/(card|button|badge|chip)/.test(name)) props["variant"] = '"primary" | "secondary" | "ghost"';
+  return props;
+}
+
+/**
+ * @param {ColorMapping|null|undefined} mapping
+ * @param {string} prefix
+ */
+function resolveColorClass(mapping, prefix) {
+  if (!mapping) return "";
+  return mapping.localToken ? `${prefix}-[var(${mapping.localToken})]` : `${prefix}-[${mapping.figmaValue}]`;
+}
+
+/**
+ * Construye el bloque CSS usando variables del proyecto o valores hex como fallback.
+ * @param {string} selector
+ * @param {FigmaNode} node
+ * @param {ColorMapping[]} colorMappings
+ * @returns {string}
+ */
+function buildCSSBlock(selector, node, colorMappings) {
+  const dims = node.absoluteBoundingBox;
+  const lines = [];
+
+  if (dims) {
+    lines.push(`  width: ${Math.round(dims.width)}px;`);
+    lines.push(`  height: ${Math.round(dims.height)}px;`);
+  }
+
+  const bgFill = (node.fills ?? []).find(/** @param {any} f */ f => f.type === "SOLID");
+  if (bgFill?.color) {
+    const hex = `#${Math.round(bgFill.color.r*255).toString(16).padStart(2,"0")}${Math.round(bgFill.color.g*255).toString(16).padStart(2,"0")}${Math.round(bgFill.color.b*255).toString(16).padStart(2,"0")}`;
+    const mapping = colorMappings.find(m => m.figmaValue === hex);
+    lines.push(`  background-color: ${mapping?.localToken ? `var(${mapping.localToken})` : hex};`);
+  }
+
+  const textChild = (node.children ?? []).find(/** @param {any} c */ c => c.type === "TEXT" && c.style);
+  if (textChild?.style) {
+    const s = textChild.style;
+    if (s.fontSize) lines.push(`  font-size: ${s.fontSize}px;`);
+    if (s.fontWeight) lines.push(`  font-weight: ${s.fontWeight};`);
+    if (s.lineHeightPx) lines.push(`  line-height: ${Math.round(s.lineHeightPx)}px;`);
+  }
+
+  if (lines.length === 0) lines.push("  /* estilos del sistema de diseño */");
+
+  return `.${selector} {\n${lines.join("\n")}\n}`;
+}
+
+/**
+ * @param {FigmaNode} node
+ * @param {string} componentName
+ * @param {Record<string,string>} props
+ * @param {ColorMapping[]} colorMappings
+ * @param {string} cssApproach
+ */
+function generateReact(node, componentName, props, colorMappings, cssApproach) {
+  const warnings = [];
+  const dims = node.absoluteBoundingBox;
+  if (!dims) warnings.push("No se pudo leer el bounding box — dimensiones aproximadas.");
+  if (colorMappings.some(m => m.matchType === "new")) warnings.push("Algunos colores de Figma no tienen token equivalente en el proyecto. Se usó el valor hex directo.");
+
+  const hasChildren = "children" in props;
+  const propsStr = Object.entries(props).map(([k,v]) => `${k}${v==="boolean"?"?":""}: ${v}`).join("; ");
+  const propsKeys = Object.keys(props).join(", ") || "className";
+  const cssClass = toKebabCase(componentName);
+
+  /** @type {string|null} */
+  let cssSnippet = null;
+  let code = "";
+
+  if (cssApproach === "tailwind") {
+    const bgFill = (node.fills ?? []).find(/** @param {any} f */ f => f.type === "SOLID");
+    const bgHex = bgFill?.color
+      ? `#${Math.round(bgFill.color.r*255).toString(16).padStart(2,"0")}${Math.round(bgFill.color.g*255).toString(16).padStart(2,"0")}${Math.round(bgFill.color.b*255).toString(16).padStart(2,"0")}`
+      : null;
+    const bgMapping = bgHex ? colorMappings.find(m => m.figmaValue === bgHex) : null;
+    const bgClass = bgMapping ? resolveColorClass(bgMapping, "bg") : "";
+    code = `import React from "react";\n\ninterface ${componentName}Props {\n  ${propsStr || "className?: string"}\n}\n\nexport function ${componentName}({ ${propsKeys} }: ${componentName}Props) {\n  return (\n    <div className="${bgClass} rounded p-4">\n      ${hasChildren ? "{children}" : `{/* contenido de ${node.name} */}`}\n    </div>\n  );\n}\n\nexport default ${componentName};\n`;
+
+  } else if (cssApproach === "css-modules") {
+    code = `import React from "react";\nimport styles from "./${cssClass}.module.css";\n\ninterface ${componentName}Props {\n  ${propsStr || "className?: string"}\n}\n\nexport function ${componentName}({ ${propsKeys} }: ${componentName}Props) {\n  return (\n    <div className={styles.root}>\n      ${hasChildren ? "{children}" : `{/* contenido de ${node.name} */}`}\n    </div>\n  );\n}\n\nexport default ${componentName};\n`;
+    cssSnippet = buildCSSBlock(".root", node, colorMappings);
+
+  } else {
+    // CSS puro — clase global, snippet CSS separado
+    code = `import React from "react";\nimport "./${cssClass}.css";\n\ninterface ${componentName}Props {\n  ${propsStr || "className?: string"}\n}\n\nexport function ${componentName}({ ${propsKeys} }: ${componentName}Props) {\n  return (\n    <div className="${cssClass}">\n      ${hasChildren ? "{children}" : `{/* contenido de ${node.name} */}`}\n    </div>\n  );\n}\n\nexport default ${componentName};\n`;
+    cssSnippet = buildCSSBlock(`.${cssClass}`, node, colorMappings);
+  }
+
+  return { filename: `${componentName}.tsx`, code, warnings, cssSnippet };
+}
+
+/**
+ * @param {FigmaNode} node
+ * @param {string} componentName
+ * @param {Record<string,string>} props
+ */
+function generateVue(node, componentName, props) {
+  const propsBlock = Object.entries(props).map(([k,v]) => `${k}?: ${v}`).join("\n  ");
+  const hasChildren = "children" in props;
+  const code = `<template>\n  <div class="root">\n    ${hasChildren ? "<slot />" : `<!-- contenido de ${node.name} -->`}\n  </div>\n</template>\n\n<script setup lang="ts">\ninterface Props {\n  ${propsBlock}\n}\ndefineProps<Props>();\n</script>\n\n<style scoped>\n.root {\n  /* estilos del sistema de diseño */\n}\n</style>\n`;
+  return { filename: `${componentName}.vue`, code, warnings: /** @type {string[]} */ ([]), cssSnippet: /** @type {string|null} */ (null) };
+}
+
+/**
+ * @param {FigmaNode} node
+ * @param {DesignProfile} profile
+ * @param {ColorMapping[]} colorMappings
+ */
+function generateComponent(node, profile, colorMappings) {
+  const componentName = toPascalCase(node.name) || "FigmaComponent";
+  const props = inferProps(node);
+  return profile.stack.framework === "vue"
+    ? generateVue(node, componentName, props)
+    : generateReact(node, componentName, props, colorMappings, profile.stack.cssApproach);
+}
+
+/** @param {DesignProfile} profile */
+function suggestImprovements(profile) {
+  const improvements = [];
+  if (Object.keys(profile.colors).length === 0) improvements.push({ priority: "alta", area: "Tokens de color", description: "No se detectaron tokens de color", action: "Define colores como CSS variables o en tailwind.config.js" });
+  if (!profile.stack.hasTokenFile) improvements.push({ priority: "alta", area: "Token file", description: "No existe archivo único de tokens", action: "Crea src/tokens.ts con exports de colores, tipografía y espaciado" });
+  if (profile.existingComponents.length === 0) improvements.push({ priority: "alta", area: "Componentes base", description: "No se encontró librería de componentes", action: "Crea src/components con Button, Input, Card" });
+  if (Object.keys(profile.spacing).length === 0) improvements.push({ priority: "media", area: "Espaciado", description: "No se detectaron tokens de espaciado", action: "Define escala de espaciado (4, 8, 16, 24, 32px)" });
+  if (Object.keys(profile.breakpoints).length === 0) improvements.push({ priority: "media", area: "Breakpoints", description: "No se detectaron breakpoints como tokens", action: "Define breakpoints en tailwind.config.js o custom media queries" });
+  if (profile.typography.fontFamilies.length === 0) improvements.push({ priority: "media", area: "Tipografía", description: "No se detectó fuente declarada como token", action: "Define --font-sans o fontFamily en tailwind.config.js" });
+  if (Object.keys(profile.shadows).length === 0) improvements.push({ priority: "baja", area: "Sombras", description: "No se detectaron tokens de sombra", action: "Define sombras estándar (sm, md, lg)" });
+  return improvements;
+}
+
+export { generateComponent, suggestImprovements };

package/mcp-figma/src/design-system-analyzer.js

@@ -0,0 +1,247 @@
+// @ts-check
+import { readFileSync, readdirSync, existsSync, statSync } from "fs";
+import { join, extname, basename } from "path";
+
+/**
+ * @typedef {{ framework:string, cssApproach:string, hasTokenFile:boolean }} Stack
+ * @typedef {{ colors:Record<string,string>, spacing:Record<string,string>, typography:{ fontFamilies:string[], fontSizes:Record<string,string>, fontWeights:Record<string,string> }, breakpoints:Record<string,string>, borderRadius:Record<string,string>, shadows:Record<string,string>, existingComponents:string[], stack:Stack, rawSources:string[] }} DesignProfile
+ */
+
+/**
+ * Escanea un nivel de directorio buscando archivos por extensión (sin recursión profunda).
+ * Versión ligera usada solo por detectCSSApproach antes de que findFiles esté disponible.
+ * @param {string} dir
+ * @param {string} ext
+ * @returns {string[]}
+ */
+function shallowFind(dir, ext) {
+  if (!existsSync(dir)) return [];
+  try {
+    return readdirSync(dir)
+      .filter(e => e.endsWith(ext))
+      .map(e => join(dir, e));
+  } catch { return []; }
+}
+
+/** @param {string} projectRoot */
+function detectCSSApproach(projectRoot) {
+  const srcDir = join(projectRoot, "src");
+
+  // Si algún componente importa *.module.css → CSS Modules
+  const srcFiles = [
+    ...shallowFind(srcDir, ".tsx"),
+    ...shallowFind(srcDir, ".jsx"),
+    ...shallowFind(join(srcDir, "components"), ".tsx"),
+    ...shallowFind(join(srcDir, "components"), ".jsx"),
+  ];
+  for (const file of srcFiles.slice(0, 20)) {
+    try {
+      if (/from\s+['"][^'"]+\.module\.css['"]/.test(readFileSync(file, "utf-8"))) return "css-modules";
+    } catch {}
+  }
+
+  // CSS global presente → CSS puro
+  const globalCandidates = [
+    join(projectRoot, "src/index.css"),
+    join(projectRoot, "src/global.css"),
+    join(projectRoot, "src/styles.css"),
+    join(projectRoot, "src/main.css"),
+    join(projectRoot, "styles/main.css"),
+    join(projectRoot, "styles/global.css"),
+  ];
+  if (globalCandidates.some(f => existsSync(f))) return "css";
+
+  // Cualquier .css en src/ → CSS puro
+  if (shallowFind(srcDir, ".css").length > 0) return "css";
+
+  return "css"; // default seguro: CSS puro
+}
+
+/** @param {string} projectRoot */
+function detectFramework(projectRoot) {
+  let pkg = null;
+  try { pkg = JSON.parse(readFileSync(join(projectRoot, "package.json"), "utf-8")); } catch {}
+  const deps = { ...(pkg?.dependencies ?? {}), ...(pkg?.devDependencies ?? {}) };
+
+  const framework =
+    "react" in deps ? "react" :
+    "vue" in deps ? "vue" :
+    "@angular/core" in deps ? "angular" :
+    "svelte" in deps ? "svelte" :
+    "solid-js" in deps ? "solid" : "unknown";
+
+  const cssApproach =
+    "tailwindcss" in deps ? "tailwind" :
+    "styled-components" in deps ? "styled-components" :
+    "@emotion/react" in deps ? "emotion" :
+    "sass" in deps || "node-sass" in deps ? "sass" :
+    detectCSSApproach(projectRoot);
+
+  return { framework, cssApproach };
+}
+
+/**
+ * @param {string} raw
+ * @param {string} section
+ * @returns {Record<string,string>}
+ */
+function extractTailwindSection(raw, section) {
+  /** @type {Record<string,string>} */
+  const result = {};
+  const sectionRe = new RegExp(`['"]?${section}['"]?\\s*:\\s*\\{([^}]+)\\}`, "s");
+  const match = raw.match(sectionRe);
+  if (!match) return result;
+  const pairRe = /['"]?([\w-]+)['"]?\s*:\s*['"]([^'"]+)['"]/g;
+  let m;
+  while ((m = pairRe.exec(match[1])) !== null) result[m[1]] = m[2];
+  return result;
+}
+
+/** @param {string} projectRoot */
+function parseTailwindConfig(projectRoot) {
+  const candidates = ["tailwind.config.js","tailwind.config.ts","tailwind.config.cjs","tailwind.config.mjs"];
+  for (const filename of candidates) {
+    const path = join(projectRoot, filename);
+    if (!existsSync(path)) continue;
+    const raw = readFileSync(path, "utf-8");
+    return {
+      colors: extractTailwindSection(raw, "colors"),
+      spacing: extractTailwindSection(raw, "spacing"),
+      fontSizes: extractTailwindSection(raw, "fontSize"),
+      breakpoints: extractTailwindSection(raw, "screens"),
+      borderRadius: extractTailwindSection(raw, "borderRadius"),
+      shadows: extractTailwindSection(raw, "boxShadow"),
+    };
+  }
+  return {};
+}
+
+/**
+ * @param {string} dir
+ * @param {string[]} extensions
+ * @param {number} maxDepth
+ * @param {number} [depth]
+ * @returns {string[]}
+ */
+function findFiles(dir, extensions, maxDepth, depth = 0) {
+  if (depth > maxDepth || !existsSync(dir)) return [];
+  const results = [];
+  try {
+    for (const entry of readdirSync(dir)) {
+      if ([".", "node_modules", "dist", ".next", ".git"].some(x => entry === x || entry.startsWith("."))) continue;
+      const full = join(dir, entry);
+      if (statSync(full).isDirectory()) results.push(...findFiles(full, extensions, maxDepth, depth + 1));
+      else if (extensions.includes(extname(full))) results.push(full);
+    }
+  } catch {}
+  return results;
+}
+
+/** @param {string} projectRoot */
+function parseCSSVariables(projectRoot) {
+  /** @type {Record<string,string>} */
+  const colors = {};
+  /** @type {Record<string,string>} */
+  const spacing = {};
+  /** @type {Record<string,string>} */
+  const fontSizes = {};
+  /** @type {Record<string,string>} */
+  const fontWeights = {};
+  /** @type {string[]} */
+  const fontFamilies = [];
+  const cssFiles = findFiles(projectRoot, [".css", ".scss", ".sass"], 4);
+  for (const file of cssFiles.slice(0, 20)) {
+    try {
+      const content = readFileSync(file, "utf-8");
+      const varRe = /--([\w-]+)\s*:\s*([^;]+);/g;
+      let m;
+      while ((m = varRe.exec(content)) !== null) {
+        const name = m[1].toLowerCase(), value = m[2].trim();
+        if (/(color|primary|secondary|accent|bg|text|border|surface|brand)/.test(name)) colors[`--${m[1]}`] = value;
+        else if (/(spacing|gap|padding|margin|size)/.test(name)) spacing[`--${m[1]}`] = value;
+        else if (/(font-size|text-size)/.test(name)) fontSizes[`--${m[1]}`] = value;
+        else if (/font-weight/.test(name)) fontWeights[`--${m[1]}`] = value;
+        else if (/font-family/.test(name)) fontFamilies.push(value);
+      }
+    } catch {}
+  }
+  return { colors, spacing, typography: { fontFamilies, fontSizes, fontWeights } };
+}
+
+/** @param {string} projectRoot */
+function findExistingComponents(projectRoot) {
+  const found = [];
+  for (const dir of ["src/components","src/ui","components","ui","src/shared"]) {
+    const full = join(projectRoot, dir);
+    if (!existsSync(full)) continue;
+    for (const f of findFiles(full, [".tsx",".jsx",".vue",".svelte"], 3))
+      found.push(basename(f, extname(f)));
+  }
+  return [...new Set(found)].sort();
+}
+
+/**
+ * @param {string} projectRoot
+ * @returns {DesignProfile}
+ */
+function analyzeDesignSystem(projectRoot) {
+  const { framework, cssApproach } = detectFramework(projectRoot);
+  const tailwindData = cssApproach === "tailwind" ? parseTailwindConfig(projectRoot) : {};
+  const cssData = parseCSSVariables(projectRoot);
+
+  const tokenCandidates = ["src/tokens.ts","src/tokens.js","src/design-tokens.ts","tokens.json","src/theme.ts"];
+  const hasTokenFile = tokenCandidates.some(t => existsSync(join(projectRoot, t)));
+
+  const rawSources = [];
+  if (cssApproach === "tailwind") rawSources.push("tailwind.config");
+  if (Object.keys(cssData.colors).length > 0) rawSources.push("css-variables");
+  if (hasTokenFile) rawSources.push("token-file");
+
+  return {
+    stack: { framework, cssApproach, hasTokenFile },
+    colors: { ...(cssData.colors ?? {}), ...(tailwindData.colors ?? {}) },
+    typography: {
+      fontFamilies: cssData.typography?.fontFamilies ?? [],
+      fontSizes: { ...(cssData.typography?.fontSizes ?? {}), ...(tailwindData.fontSizes ?? {}) },
+      fontWeights: cssData.typography?.fontWeights ?? {},
+    },
+    spacing: { ...(cssData.spacing ?? {}), ...(tailwindData.spacing ?? {}) },
+    breakpoints: tailwindData.breakpoints ?? {},
+    borderRadius: tailwindData.borderRadius ?? {},
+    shadows: tailwindData.shadows ?? {},
+    existingComponents: findExistingComponents(projectRoot),
+    rawSources,
+  };
+}
+
+/**
+ * @param {string} projectRoot
+ * @param {DesignProfile} profile
+ */
+function evaluateUIConsistency(projectRoot, profile) {
+  /** @type {string[]} */
+  const issues = [];
+  /** @type {string[]} */
+  const suggestions = [];
+  let score = 100;
+
+  if (Object.keys(profile.colors).length === 0) { issues.push("No se detectaron tokens de color — los colores pueden estar hardcodeados"); score -= 20; }
+  if (Object.keys(profile.spacing).length === 0) { issues.push("No se detectaron tokens de espaciado"); score -= 10; }
+  if (profile.typography.fontFamilies.length === 0) { issues.push("No se detectó fuente tipográfica declarada como token"); score -= 10; }
+  if (profile.existingComponents.length === 0) { issues.push("No se encontró librería de componentes en src/components o src/ui"); score -= 15; suggestions.push("Crea src/components con componentes base (Button, Input, Card)"); }
+  if (!profile.stack.hasTokenFile) suggestions.push("Centraliza los tokens en src/tokens.ts para tener una única fuente de verdad");
+  if (profile.stack.cssApproach === "unknown") suggestions.push("Define un enfoque de estilos claro: Tailwind, CSS Modules, o CSS Variables");
+
+  const componentCoverage = profile.existingComponents.slice(0, 20).map(name => ({
+    name,
+    hasStory: existsSync(join(projectRoot, `src/components/${name}.stories.tsx`)) || existsSync(join(projectRoot, `src/components/${name}.stories.ts`)),
+    hasTest: existsSync(join(projectRoot, `src/components/${name}.test.tsx`)) || existsSync(join(projectRoot, `src/__tests__/${name}.test.tsx`)),
+  }));
+
+  const withoutTests = componentCoverage.filter(c => !c.hasTest).length;
+  if (withoutTests > 0) { suggestions.push(`${withoutTests} componente(s) sin tests`); score -= Math.min(15, withoutTests * 3); }
+
+  return { score: Math.max(0, score), issues, suggestions, componentCoverage };
+}
+
+export { analyzeDesignSystem, evaluateUIConsistency };

package/mcp-figma/src/figma-client.js

@@ -0,0 +1,75 @@
+// @ts-check
+const FIGMA_API = "https://api.figma.com/v1";
+
+/**
+ * @typedef {{ type: string, color?: { r:number, g:number, b:number, a?:number } }} Fill
+ * @typedef {{ id:string, name:string, type:string, fills?:Fill[], style?:object, children?:FigmaNode[], absoluteBoundingBox?:{width:number,height:number} }} FigmaNode
+ */
+
+function pat() {
+  const token = process.env.FIGMA_PAT;
+  if (!token) throw new Error("FIGMA_PAT no está definido en las variables de entorno");
+  return token;
+}
+
+function headers() {
+  return { "X-Figma-Token": pat(), "Content-Type": "application/json" };
+}
+
+/** @param {string} path */
+async function get(path) {
+  const res = await fetch(`${FIGMA_API}${path}`, { headers: headers() });
+  if (!res.ok) {
+    const body = await res.text();
+    throw new Error(`Figma API ${res.status}: ${body}`);
+  }
+  return res.json();
+}
+
+/** @param {string} fileKey */
+async function getFileMeta(fileKey) {
+  const data = await get(`/files/${fileKey}?depth=1`);
+  return {
+    name: data.name,
+    lastModified: data.lastModified,
+    version: data.version,
+    componentCount: Object.keys(data.components ?? {}).length,
+    styleCount: Object.keys(data.styles ?? {}).length,
+  };
+}
+
+/** @param {string} fileKey */
+async function getFileComponents(fileKey) {
+  const data = await get(`/components/file/${fileKey}`);
+  return data.meta?.components ?? [];
+}
+
+/**
+ * @param {string} fileKey
+ * @param {string} nodeId
+ */
+async function getNodeById(fileKey, nodeId) {
+  return get(`/files/${fileKey}/nodes?ids=${encodeURIComponent(nodeId)}`);
+}
+
+/**
+ * @param {number} r
+ * @param {number} g
+ * @param {number} b
+ * @param {number} [a]
+ */
+function rgbaToHex(r, g, b, a = 1) {
+  const toHex = (/** @type {number} */ n) => Math.round(n * 255).toString(16).padStart(2, "0");
+  const hex = `#${toHex(r)}${toHex(g)}${toHex(b)}`;
+  return a < 1 ? `${hex}${toHex(a)}` : hex;
+}
+
+/** @param {Fill} fill */
+function extractColorFromFill(fill) {
+  if (fill.type === "SOLID" && fill.color) {
+    return rgbaToHex(fill.color.r, fill.color.g, fill.color.b, fill.color.a ?? 1);
+  }
+  return null;
+}
+
+export { getFileMeta, getFileComponents, getNodeById, rgbaToHex, extractColorFromFill };

package/mcp-figma/src/index.js

@@ -0,0 +1,114 @@
+#!/usr/bin/env node
+import { createServer } from "./mcp.js";
+import { analyzeDesignSystem, evaluateUIConsistency } from "./design-system-analyzer.js";
+import { getFileMeta, getFileComponents, getNodeById } from "./figma-client.js";
+import { mapColors, mapTypography, buildMappingReport } from "./style-mapper.js";
+import { generateComponent, suggestImprovements } from "./component-generator.js";
+
+const server = createServer({ name: "sdd-figma-mcp", version: "1.0.0" });
+
+// ── 1. analizar_sistema_diseño ────────────────────────────────────────────────
+server.tool({
+  name: "analizar_sistema_diseño",
+  description: "Analiza el sistema de diseño del proyecto local: framework, CSS, tokens de color, tipografía, espaciado y componentes existentes. Ejecutar SIEMPRE antes de generar código UI.",
+  annotations: { readOnlyHint: true, destructiveHint: false },
+  inputSchema: { type: "object", properties: { project_root: { type: "string", description: "Ruta absoluta a la raíz del proyecto (donde está package.json)" } }, required: ["project_root"] },
+}, async ({ project_root }) => {
+  const p = analyzeDesignSystem(project_root);
+  return { content: [{ type: "text", text: JSON.stringify({ ok: true, stack: p.stack, colores: Object.keys(p.colors).length ? p.colors : "(no detectados)", tipografia: { fuentes: p.typography.fontFamilies, tamaños: Object.keys(p.typography.fontSizes).length ? p.typography.fontSizes : "(no detectados)", pesos: p.typography.fontWeights }, espaciado: Object.keys(p.spacing).length ? p.spacing : "(no detectado)", breakpoints: Object.keys(p.breakpoints).length ? p.breakpoints : "(no detectados)", borderRadius: p.borderRadius, sombras: p.shadows, componentesExistentes: p.existingComponents, fuentesLeidas: p.rawSources }, null, 2) }] };
+});
+
+// ── 2. evaluar_ui_existente ───────────────────────────────────────────────────
+server.tool({
+  name: "evaluar_ui_existente",
+  description: "Score 0-100 de la calidad del sistema de diseño + lista de problemas y sugerencias priorizadas.",
+  annotations: { readOnlyHint: true, destructiveHint: false },
+  inputSchema: { type: "object", properties: { project_root: { type: "string" } }, required: ["project_root"] },
+}, async ({ project_root }) => {
+  const p = analyzeDesignSystem(project_root);
+  const e = evaluateUIConsistency(project_root, p);
+  return { content: [{ type: "text", text: JSON.stringify({ ok: true, score: `${e.score}/100`, problemas: e.issues, sugerencias: e.suggestions, coberturaComponentes: e.componentCoverage }, null, 2) }] };
+});
+
+// ── 3. conectar_figma ─────────────────────────────────────────────────────────
+server.tool({
+  name: "conectar_figma",
+  description: "Verifica PAT y devuelve metadata del archivo Figma (nombre, versión, cantidad de componentes y estilos).",
+  annotations: { readOnlyHint: true, destructiveHint: false },
+  inputSchema: { type: "object", properties: { file_key: { type: "string", description: "Clave del archivo — extraída de la URL: figma.com/file/AQUI/nombre" } }, required: ["file_key"] },
+}, async ({ file_key }) => {
+  const meta = await getFileMeta(file_key);
+  return { content: [{ type: "text", text: JSON.stringify({ ok: true, ...meta }, null, 2) }] };
+});
+
+// ── 4. listar_componentes ─────────────────────────────────────────────────────
+server.tool({
+  name: "listar_componentes",
+  description: "Lista todos los componentes publicados en el archivo Figma. Acepta filtro opcional por nombre.",
+  annotations: { readOnlyHint: true, destructiveHint: false },
+  inputSchema: { type: "object", properties: { file_key: { type: "string" }, filter: { type: "string", description: "Texto para filtrar por nombre (opcional)" } }, required: ["file_key"] },
+}, async ({ file_key, filter }) => {
+  const all = await getFileComponents(file_key);
+  const list = filter ? all.filter(c => c.name.toLowerCase().includes(filter.toLowerCase())) : all;
+  return { content: [{ type: "text", text: JSON.stringify({ ok: true, total: list.length, components: list.map(c => ({ name: c.name, key: c.key, description: c.description || "(sin descripción)" })) }, null, 2) }] };
+});
+
+// ── 5. traer_componente ───────────────────────────────────────────────────────
+server.tool({
+  name: "traer_componente",
+  description: "Trae el detalle completo de un nodo Figma: estructura, fills, estilos de texto, dimensiones e hijos directos.",
+  annotations: { readOnlyHint: true, destructiveHint: false },
+  inputSchema: { type: "object", properties: { file_key: { type: "string" }, node_id: { type: "string", description: "ID del nodo — visible en la URL al seleccionar un frame: ?node-id=AQUI" } }, required: ["file_key", "node_id"] },
+}, async ({ file_key, node_id }) => {
+  const detail = await getNodeById(file_key, node_id);
+  const nd = detail.nodes[node_id];
+  if (!nd) throw new Error(`Nodo ${node_id} no encontrado`);
+  const n = nd.document;
+  return { content: [{ type: "text", text: JSON.stringify({ ok: true, id: n.id, name: n.name, type: n.type, dimensiones: n.absoluteBoundingBox ? { ancho: n.absoluteBoundingBox.width, alto: n.absoluteBoundingBox.height } : null, fills: n.fills ?? [], estiloTexto: n.style ?? null, hijos: (n.children ?? []).map(c => ({ id: c.id, name: c.name, type: c.type, fills: c.fills ?? [] })) }, null, 2) }] };
+});
+
+// ── 6. mapear_estilos ─────────────────────────────────────────────────────────
+server.tool({
+  name: "mapear_estilos",
+  description: "Cruza colores y tipografía de un nodo Figma con los tokens del proyecto. Devuelve mapeo con nivel de confianza y lista de tokens sin equivalente.",
+  annotations: { readOnlyHint: true, destructiveHint: false },
+  inputSchema: { type: "object", properties: { file_key: { type: "string" }, node_id: { type: "string" }, project_root: { type: "string" } }, required: ["file_key", "node_id", "project_root"] },
+}, async ({ file_key, node_id, project_root }) => {
+  const [detail, profile] = await Promise.all([getNodeById(file_key, node_id), Promise.resolve(analyzeDesignSystem(project_root))]);
+  const nd = detail.nodes[node_id];
+  if (!nd) throw new Error(`Nodo ${node_id} no encontrado`);
+  const all = [nd.document, ...(nd.document.children ?? [])];
+  const colorMappings = mapColors(all.filter(n => n.fills?.length).map(n => ({ name: n.name, fills: n.fills })), profile);
+  const typographyMappings = mapTypography(all.filter(n => n.style && n.type === "TEXT").map(n => ({ name: n.name, style: n.style })), profile);
+  return { content: [{ type: "text", text: JSON.stringify({ ok: true, ...buildMappingReport(colorMappings, typographyMappings) }, null, 2) }] };
+});
+
+// ── 7. generar_componente ─────────────────────────────────────────────────────
+server.tool({
+  name: "generar_componente",
+  description: "Genera código del componente (React/Vue) usando los tokens del proyecto. No hardcodea valores de Figma.",
+  annotations: { readOnlyHint: false, destructiveHint: false },
+  inputSchema: { type: "object", properties: { file_key: { type: "string" }, node_id: { type: "string" }, project_root: { type: "string" } }, required: ["file_key", "node_id", "project_root"] },
+}, async ({ file_key, node_id, project_root }) => {
+  const [detail, profile] = await Promise.all([getNodeById(file_key, node_id), Promise.resolve(analyzeDesignSystem(project_root))]);
+  const nd = detail.nodes[node_id];
+  if (!nd) throw new Error(`Nodo ${node_id} no encontrado`);
+  const node = nd.document;
+  const all = [node, ...(node.children ?? [])];
+  const colorMappings = mapColors(all.filter(n => n.fills?.length).map(n => ({ name: n.name, fills: n.fills })), profile);
+  const g = generateComponent(node, profile, colorMappings);
+  const cssExt = profile.stack.cssApproach === "css-modules" ? ".module.css" : ".css";
+  const cssFile = g.cssSnippet ? `src/components/${g.filename.replace(/\.tsx$/, cssExt)}` : null;
+  return { content: [{ type: "text", text: JSON.stringify({ ok: true, filename: g.filename, framework: profile.stack.framework, cssApproach: profile.stack.cssApproach, code: g.code, cssSnippet: g.cssSnippet, advertencias: g.warnings, instrucciones: [`Guarda en src/components/${g.filename}`, ...(cssFile ? [`Crea ${cssFile} con el CSS snippet`] : []), "Revisa los colores y agrega props de accesibilidad según el contexto"] }, null, 2) }] };
+});
+
+// ── 8. sugerir_mejoras ────────────────────────────────────────────────────────
+server.tool({
+  name: "sugerir_mejoras",
+  description: "Lista priorizada (alta/media/baja) de mejoras al sistema de diseño del proyecto.",
+  annotations: { readOnlyHint: true, destructiveHint: false },
+  inputSchema: { type: "object", properties: { project_root: { type: "string" } }, required: ["project_root"] },
+}, async ({ project_root }) => {
+  const improvements = suggestImprovements(analyzeDesignSystem(project_root));
+  return { content: [{ type: "text", text: JSON.stringify({ ok: true, total: improvements.length, porPrioridad: { alta: improvements.filter(i => i.priority === "alta"), media: improvements.filter(i => i.priority === "media"), baja: improvements.filter(i => i.priority === "baja") } }, null, 2) }] };
+});