adoptai-mcp 1.0.0

package/dist/integrations/figma/tools.js

@@ -0,0 +1,1137 @@
+import axios from 'axios';
+import { readFileSync } from 'fs';
+import { dirname, join } from 'path';
+import { fileURLToPath } from 'url';
+import { buildAuthHeaders } from './auth.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const spec = JSON.parse(readFileSync(join(__dirname, '../../specs/figma-api.json'), 'utf8'));
+
+const BASE_V1 = 'https://api.figma.com/v1';
+const BASE_V2 = 'https://api.figma.com/v2';
+
+const EXCLUDED_OPS = new Set([
+  'GET /v1/files/{file_key}',
+  'GET /v1/files/{file_key}/nodes',
+  'GET /v1/images/{file_key}',
+  'GET /v1/files/{file_key}/versions',
+  'GET /v1/files/{file_key}/components',
+  'GET /v1/files/{file_key}/comments',
+  'POST /v1/files/{file_key}/comments',
+  'DELETE /v1/files/{file_key}/comments/{comment_id}',
+  'GET /v1/teams/{team_id}/components',
+  'GET /v1/components/{key}',
+  'GET /v1/teams/{team_id}/component_sets',
+  'GET /v1/teams/{team_id}/styles',
+  'GET /v1/files/{file_key}/variables/local',
+  'GET /v1/files/{file_key}/variables/published',
+  'POST /v1/files/{file_key}/variables',
+]);
+
+function opKey(method, path) {
+  return `${method} ${path}`;
+}
+
+function text(payload) {
+  return { content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }] };
+}
+
+function handleError(err) {
+  const status = err.response?.status;
+  const data = err.response?.data;
+  const msg = data?.message || data?.err || data?.error || err.message;
+  if (status === 401) throw new Error('Token invalid.\nRun: npx adoptai-figma-mcp --client cursor');
+  if (status === 403) throw new Error('Insufficient permissions. Check your token scopes.');
+  if (status === 404) throw new Error('Resource not found. Check your parameters.');
+  if (status === 429) throw new Error('Rate limit exceeded. Please wait and try again.');
+  throw new Error(typeof msg === 'string' ? msg : JSON.stringify(msg) || 'API request failed');
+}
+
+function resolveUrlParts(specPath) {
+  if (specPath.startsWith('/v2/')) return { base: BASE_V2, rel: specPath.slice(3) };
+  if (specPath.startsWith('/v1/')) return { base: BASE_V1, rel: specPath.slice(3) };
+  return { base: BASE_V1, rel: specPath.startsWith('/') ? specPath : `/${specPath}` };
+}
+
+function scrub(params) {
+  const o = {};
+  for (const [k, v] of Object.entries(params)) {
+    if (v !== undefined && k !== '_rawBody') o[k] = v;
+  }
+  return o;
+}
+
+async function apiRequest(method, specPath, params = {}) {
+  const { base, rel } = resolveUrlParts(specPath);
+  let url = base + rel;
+  const headers = { 'Content-Type': 'application/json', ...buildAuthHeaders() };
+  const queryParams = {};
+  const bodyParams = {};
+  const p = typeof params === 'object' && params ? { ...params } : {};
+
+  for (const [key, value] of Object.entries(p)) {
+    if (key === '_rawBody') continue;
+    if (value === undefined) continue;
+    const placeholder = `{${key}}`;
+    if (url.includes(placeholder)) {
+      url = url.split(placeholder).join(encodeURIComponent(String(value)));
+    } else if (['GET', 'DELETE'].includes(method)) {
+      queryParams[key] = value;
+    } else {
+      bodyParams[key] = value;
+    }
+  }
+
+  let data;
+  if (p._rawBody != null && typeof p._rawBody === 'object') {
+    data = p._rawBody;
+  } else if (Object.keys(bodyParams).length) {
+    data = bodyParams;
+  }
+
+  try {
+    const res = await axios({
+      method,
+      url,
+      headers,
+      params: Object.keys(queryParams).length ? queryParams : undefined,
+      data,
+      timeout: 120000,
+    });
+    return res.data;
+  } catch (err) {
+    handleError(err);
+  }
+}
+
+function resolveRef(root, ref) {
+  if (!ref || !ref.startsWith('#/')) return null;
+  const parts = ref.replace('#/', '').split('/');
+  let cur = root;
+  for (const part of parts) {
+    cur = cur?.[part];
+  }
+  return cur;
+}
+
+function operationIdToName(operationId) {
+  if (!operationId) return null;
+  return operationId
+    .replace(/([A-Z])/g, '_$1')
+    .toLowerCase()
+    .replace(/^_/, '')
+    .replace(/[^a-z0-9_]/g, '_')
+    .replace(/_+/g, '_')
+    .substring(0, 60);
+}
+
+function mergeSchemaFromBody(specRoot, schema, properties, required) {
+  if (!schema) return;
+  if (schema.$ref) {
+    mergeSchemaFromBody(specRoot, resolveRef(specRoot, schema.$ref), properties, required);
+    return;
+  }
+  if (schema.allOf) {
+    for (const sub of schema.allOf) mergeSchemaFromBody(specRoot, sub, properties, required);
+    return;
+  }
+  if (schema.properties) {
+    for (const [k, val] of Object.entries(schema.properties)) {
+      if (properties[k]) continue;
+      const t = val?.type || 'string';
+      properties[k] = {
+        type: Array.isArray(t) ? t[0] : t,
+        description: val?.description || `The ${k} field`,
+      };
+      if (val?.enum) properties[k].enum = val.enum;
+    }
+    if (Array.isArray(schema.required)) {
+      for (const r of schema.required) required.add(r);
+    }
+  }
+}
+
+function buildInputSchemaForOperation(specRoot, method, op) {
+  const properties = {};
+  const required = new Set();
+
+  for (const rawParam of op.parameters || []) {
+    let param = rawParam;
+    if (param.$ref) param = resolveRef(specRoot, param.$ref);
+    if (!param?.name) continue;
+    const t = param.schema?.type || param.type || 'string';
+    properties[param.name] = {
+      type: Array.isArray(t) ? t[0] : t,
+      description: param.description || `The ${param.name} parameter`,
+    };
+    if (param.schema?.enum) properties[param.name].enum = param.schema.enum;
+    if (param.required) required.add(param.name);
+  }
+
+  const bodySchema =
+    op.requestBody?.content?.['application/json']?.schema ||
+    op.requestBody?.content?.['application/*+json']?.schema;
+
+  mergeSchemaFromBody(specRoot, bodySchema, properties, required);
+
+  if (['POST', 'PUT', 'PATCH'].includes(method)) {
+    properties._rawBody = {
+      type: 'object',
+      description: 'Optional full JSON body; when set, replaces other body fields.',
+    };
+  }
+
+  return { type: 'object', properties, required: [...required] };
+}
+
+function methodPriority(m) {
+  const order = { GET: 0, POST: 1, PUT: 2, PATCH: 3, DELETE: 4 };
+  return order[m] ?? 5;
+}
+
+function buildGeneratedTools() {
+  const HTTP_METHODS = ['get', 'post', 'put', 'patch', 'delete'];
+  const items = [];
+
+  for (const [specPath, pathItem] of Object.entries(spec.paths || {})) {
+    if (specPath.includes('/oauth/') && (specPath.endsWith('/token') || specPath.includes('/refresh'))) continue;
+
+    for (const method of HTTP_METHODS) {
+      const op = pathItem[method];
+      if (!op || op.deprecated) continue;
+      const M = method.toUpperCase();
+      if (EXCLUDED_OPS.has(opKey(M, specPath))) continue;
+
+      const name =
+        operationIdToName(op.operationId) ||
+        `figma_${M.toLowerCase()}_${specPath.replace(/[^a-z0-9]+/gi, '_')}`;
+      const description = (op.summary || op.description || `${M} ${specPath}`).slice(0, 800);
+
+      items.push({
+        sort: [methodPriority(M), specPath],
+        tool: {
+          name,
+          description,
+          inputSchema: buildInputSchemaForOperation(spec, M, op),
+          handler: async (params) => text(await apiRequest(M, specPath, params)),
+        },
+      });
+    }
+  }
+
+  items.sort((a, b) => (a.sort[0] !== b.sort[0] ? a.sort[0] - b.sort[0] : a.sort[1].localeCompare(b.sort[1])));
+  return items.map((i) => i.tool);
+}
+
+function walkNodes(node, fn, path = []) {
+  if (!node) return;
+  fn(node, path);
+  const ch = node.children;
+  if (Array.isArray(ch)) {
+    for (const c of ch) walkNodes(c, fn, [...path, node.name || node.id || '']);
+  }
+}
+
+function nameMatch(query, name) {
+  if (!name) return false;
+  const pattern = query
+    .replace(/[.+^${}()|[\]\\]/g, '\\$&')
+    .replace(/\*/g, '.*')
+    .replace(/\?/g, '.');
+  try {
+    return new RegExp(`^${pattern}$`, 'i').test(name);
+  } catch {
+    return name.toLowerCase().includes(query.toLowerCase());
+  }
+}
+
+function parseFigmaUrl(figmaUrl) {
+  const out = { file_key: null, node_id: null, team_id: null, project_id: null };
+  try {
+    const u = new URL(figmaUrl.trim());
+    const path = u.pathname;
+    const fileMatch = path.match(/\/(?:file|design|proto)\/([a-zA-Z0-9]+)/);
+    if (fileMatch) out.file_key = fileMatch[1];
+    const teamMatch = path.match(/\/team\/([a-zA-Z0-9]+)/);
+    if (teamMatch) out.team_id = teamMatch[1];
+    const projMatch = path.match(/\/project\/([a-zA-Z0-9]+)/);
+    if (projMatch) out.project_id = projMatch[1];
+    const nid = u.searchParams.get('node-id');
+    if (nid) out.node_id = decodeURIComponent(nid).replace(/-/g, ':');
+  } catch {
+    /* ignore */
+  }
+  return out;
+}
+
+async function extractTokensPayload(file_key, token_format = 'json') {
+  const [localVars, publishedVars, styles, components] = await Promise.all([
+    apiRequest('GET', '/v1/files/{file_key}/variables/local', { file_key }),
+    apiRequest('GET', '/v1/files/{file_key}/variables/published', { file_key }),
+    apiRequest('GET', '/v1/files/{file_key}/styles', { file_key }),
+    apiRequest('GET', '/v1/files/{file_key}/components', { file_key }),
+  ]);
+  return {
+    meta: { file_key, token_format },
+    localVariables: localVars,
+    publishedVariables: publishedVars,
+    styles,
+    components,
+  };
+}
+
+function buildTailwindThemeFromTokens(payload) {
+  const theme = { extend: { colors: {}, fontSize: {}, boxShadow: {} } };
+  const metaStyles = payload.styles?.meta?.styles || [];
+  for (const s of metaStyles) {
+    if (s.styleType === 'FILL' && s.name) {
+      const key = s.name.replace(/\s+/g, '-').toLowerCase();
+      theme.extend.colors[`figma-${key}`] = `var(--figma-style-${(s.key || key).toString().slice(0, 12)})`;
+    }
+  }
+  return theme;
+}
+
+const CUSTOM_TOOLS_FRONT = [
+  {
+    name: 'get_file',
+    description:
+      "Retrieves a Figma file's full document tree including all nodes, styles and components. Use when you need the complete file structure. For just the node tree outline use get_file_nodes. Depth controls how deep the node tree goes — use depth=1 for top-level frames only.",
+    inputSchema: {
+      type: 'object',
+      properties: {
+        file_key: { type: 'string', description: 'Figma file key' },
+        depth: { type: 'number', description: 'Tree depth (default 2)', default: 2 },
+        geometry: { type: 'string', description: 'Set to "paths" for vector data' },
+        version: { type: 'string', description: 'Version id' },
+      },
+      required: ['file_key'],
+    },
+    handler: async (p) => {
+      const { file_key, depth = 2, geometry, version } = p;
+      return text(await apiRequest('GET', '/v1/files/{file_key}', scrub({ file_key, depth, geometry, version })));
+    },
+  },
+  {
+    name: 'get_file_pages',
+    description:
+      'Retrieves only the top-level pages of a Figma file without loading all node content. Much faster than get_file for large files. Use when you need to list pages before drilling into a specific one.',
+    inputSchema: {
+      type: 'object',
+      properties: { file_key: { type: 'string', description: 'Figma file key' } },
+      required: ['file_key'],
+    },
+    handler: async (p) =>
+      text(await apiRequest('GET', '/v1/files/{file_key}', { file_key: p.file_key, depth: 1 })),
+  },
+  {
+    name: 'get_file_components_summary',
+    description:
+      'Returns all published components in a Figma file with their names, node IDs and descriptions. Use to discover available components before fetching specific node details.',
+    inputSchema: {
+      type: 'object',
+      properties: { file_key: { type: 'string', description: 'Figma file key' } },
+      required: ['file_key'],
+    },
+    handler: async (p) =>
+      text(await apiRequest('GET', '/v1/files/{file_key}/components', { file_key: p.file_key })),
+  },
+  {
+    name: 'get_file_versions',
+    description:
+      'Returns the version history of a Figma file with timestamps, author and description for each version. Use to review file history or revert to a specific version.',
+    inputSchema: {
+      type: 'object',
+      properties: { file_key: { type: 'string', description: 'Figma file key' } },
+      required: ['file_key'],
+    },
+    handler: async (p) =>
+      text(await apiRequest('GET', '/v1/files/{file_key}/versions', { file_key: p.file_key })),
+  },
+  {
+    name: 'get_file_nodes',
+    description:
+      'Retrieves specific nodes from a Figma file by their IDs. More efficient than get_file when you only need specific layers. Use after get_file_pages to drill into specific frames.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        file_key: { type: 'string', description: 'Figma file key' },
+        ids: { type: 'string', description: 'Comma-separated node IDs' },
+        depth: { type: 'number', description: 'Optional depth' },
+        geometry: { type: 'string', description: 'Optional geometry e.g. paths' },
+      },
+      required: ['file_key', 'ids'],
+    },
+    handler: async (p) =>
+      text(
+        await apiRequest(
+          'GET',
+          '/v1/files/{file_key}/nodes',
+          scrub({ file_key: p.file_key, ids: p.ids, depth: p.depth, geometry: p.geometry })
+        )
+      ),
+  },
+  {
+    name: 'get_node_css',
+    description:
+      'Retrieves a specific node with full geometry and path data needed to extract CSS properties. Use when you need to generate CSS from a Figma design element.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        file_key: { type: 'string', description: 'Figma file key' },
+        node_id: { type: 'string', description: 'Node id e.g. 1:2' },
+      },
+      required: ['file_key', 'node_id'],
+    },
+    handler: async (p) =>
+      text(
+        await apiRequest('GET', '/v1/files/{file_key}/nodes', {
+          file_key: p.file_key,
+          ids: p.node_id,
+          geometry: 'paths',
+        })
+      ),
+  },
+  {
+    name: 'get_frame_by_name',
+    description:
+      'Finds a specific frame or layer in a Figma file by its name and returns its node data. Useful when you know the frame name but not its node ID.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        file_key: { type: 'string', description: 'Figma file key' },
+        frame_name: { type: 'string', description: 'Exact or wildcard name (*, ?)' },
+        page_name: { type: 'string', description: 'Optional page name filter' },
+      },
+      required: ['file_key', 'frame_name'],
+    },
+    handler: async (p) => {
+      const doc = await apiRequest('GET', '/v1/files/{file_key}', { file_key: p.file_key, depth: 20 });
+      const matches = [];
+      walkNodes(doc.document, (node, pathNames) => {
+        const onPage =
+          !p.page_name || pathNames[0] === p.page_name || pathNames.join('/').includes(p.page_name);
+        if (!onPage) return;
+        if (node.name && nameMatch(p.frame_name, node.name)) {
+          matches.push({
+            id: node.id,
+            name: node.name,
+            type: node.type,
+            path: pathNames.filter(Boolean).join(' / '),
+          });
+        }
+      });
+      if (matches.length === 0) {
+        return text({ matches: [], note: 'No nodes matched; try search_nodes_by_name or adjust depth.' });
+      }
+      const ids = matches.map((m) => m.id).join(',');
+      const detail = await apiRequest('GET', '/v1/files/{file_key}/nodes', { file_key: p.file_key, ids });
+      return text({ matches, nodes: detail });
+    },
+  },
+  {
+    name: 'export_node_as_png',
+    description:
+      'Exports a specific Figma node as a PNG image at a specified scale. Returns the download URL. Use for exporting icons, illustrations or screen designs as PNG.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        file_key: { type: 'string', description: 'Figma file key' },
+        node_id: { type: 'string', description: 'Node id' },
+        scale: { type: 'number', description: 'Scale 0.01–4 (default 2)', default: 2 },
+        use_absolute_bounds: { type: 'boolean', description: 'Use full node bounds' },
+      },
+      required: ['file_key', 'node_id'],
+    },
+    handler: async (p) =>
+      text(
+        await apiRequest(
+          'GET',
+          '/v1/images/{file_key}',
+          scrub({
+            file_key: p.file_key,
+            ids: p.node_id,
+            format: 'png',
+            scale: p.scale ?? 2,
+            use_absolute_bounds: p.use_absolute_bounds,
+          })
+        )
+      ),
+  },
+  {
+    name: 'export_node_as_svg',
+    description:
+      'Exports a Figma node as an SVG file. SVG is best for icons and vector illustrations that need to scale. Returns the download URL.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        file_key: { type: 'string', description: 'Figma file key' },
+        node_id: { type: 'string', description: 'Node id' },
+        svg_outline_text: { type: 'boolean', description: 'Outline text as paths vs text elements' },
+      },
+      required: ['file_key', 'node_id'],
+    },
+    handler: async (p) =>
+      text(
+        await apiRequest(
+          'GET',
+          '/v1/images/{file_key}',
+          scrub({
+            file_key: p.file_key,
+            ids: p.node_id,
+            format: 'svg',
+            svg_outline_text: p.svg_outline_text,
+          })
+        )
+      ),
+  },
+  {
+    name: 'export_node_as_pdf',
+    description:
+      'Exports a Figma frame as a PDF document. Use for design specifications, presentations or print-ready assets.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        file_key: { type: 'string', description: 'Figma file key' },
+        node_id: { type: 'string', description: 'Node id' },
+      },
+      required: ['file_key', 'node_id'],
+    },
+    handler: async (p) =>
+      text(
+        await apiRequest('GET', '/v1/images/{file_key}', {
+          file_key: p.file_key,
+          ids: p.node_id,
+          format: 'pdf',
+        })
+      ),
+  },
+  {
+    name: 'export_multiple_nodes',
+    description:
+      'Exports multiple Figma nodes in one API call. More efficient than individual exports when you need many assets at once. Returns a map of node IDs to download URLs.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        file_key: { type: 'string', description: 'Figma file key' },
+        node_ids: { type: 'array', items: { type: 'string' }, description: 'Node IDs to render' },
+        format: {
+          type: 'string',
+          description: 'png, svg, pdf, or jpg',
+          enum: ['png', 'svg', 'pdf', 'jpg'],
+          default: 'png',
+        },
+        scale: { type: 'number', description: 'Image scale (default 1)', default: 1 },
+      },
+      required: ['file_key', 'node_ids'],
+    },
+    handler: async (p) =>
+      text(
+        await apiRequest(
+          'GET',
+          '/v1/images/{file_key}',
+          scrub({
+            file_key: p.file_key,
+            ids: p.node_ids.join(','),
+            format: p.format ?? 'png',
+            scale: p.scale ?? 1,
+          })
+        )
+      ),
+  },
+  {
+    name: 'get_file_comments',
+    description:
+      'Retrieves all comments on a Figma file with author, content, position and resolved status. Use to review design feedback before a design review meeting.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        file_key: { type: 'string', description: 'Figma file key' },
+        as_md: { type: 'boolean', description: 'Return comments as markdown when applicable' },
+      },
+      required: ['file_key'],
+    },
+    handler: async (p) =>
+      text(await apiRequest('GET', '/v1/files/{file_key}/comments', scrub({ file_key: p.file_key, as_md: p.as_md }))),
+  },
+  {
+    name: 'add_comment',
+    description:
+      'Posts a new comment on a Figma file. Can be placed at a specific canvas position or attached to a node. Use to give design feedback directly in Figma.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        file_key: { type: 'string', description: 'Figma file key' },
+        message: { type: 'string', description: 'Comment text' },
+        client_meta: { type: 'object', description: 'Position: Vector, Region, FrameOffset, or FrameOffsetRegion' },
+        comment_id: { type: 'string', description: 'Parent comment id for replies' },
+        _rawBody: { type: 'object', description: 'Full POST body; overrides message/client_meta/comment_id when set' },
+      },
+      required: ['file_key', 'message'],
+    },
+    handler: async (p) => {
+      if (p._rawBody && typeof p._rawBody === 'object') {
+        return text(
+          await apiRequest('POST', '/v1/files/{file_key}/comments', { file_key: p.file_key, _rawBody: p._rawBody })
+        );
+      }
+      return text(
+        await apiRequest('POST', '/v1/files/{file_key}/comments', {
+          file_key: p.file_key,
+          _rawBody: scrub({ message: p.message, client_meta: p.client_meta, comment_id: p.comment_id }),
+        })
+      );
+    },
+  },
+  {
+    name: 'resolve_comment',
+    description:
+      "Marks a Figma comment as resolved. Use after addressing design feedback to keep the file's comment thread clean. Note: Official docs list GET/POST/DELETE for comments only; this calls PUT { resolved: true } as specified and may 404 if unsupported.",
+    inputSchema: {
+      type: 'object',
+      properties: {
+        file_key: { type: 'string', description: 'Figma file key' },
+        comment_id: { type: 'string', description: 'Comment id' },
+      },
+      required: ['file_key', 'comment_id'],
+    },
+    handler: async (p) =>
+      text(
+        await apiRequest('PUT', '/v1/files/{file_key}/comments/{comment_id}', {
+          file_key: p.file_key,
+          comment_id: p.comment_id,
+          _rawBody: { resolved: true },
+        })
+      ),
+  },
+  {
+    name: 'delete_comment',
+    description:
+      'Permanently deletes a comment from a Figma file. Only the comment author can delete their own comments.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        file_key: { type: 'string', description: 'Figma file key' },
+        comment_id: { type: 'string', description: 'Comment id' },
+      },
+      required: ['file_key', 'comment_id'],
+    },
+    handler: async (p) =>
+      text(
+        await apiRequest('DELETE', '/v1/files/{file_key}/comments/{comment_id}', {
+          file_key: p.file_key,
+          comment_id: p.comment_id,
+        })
+      ),
+  },
+  {
+    name: 'get_team_components',
+    description:
+      'Lists all published components in a Figma team library with names, keys and descriptions. Use to browse available design system components.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        team_id: { type: 'string', description: 'Team id' },
+        page_size: { type: 'number', description: 'Page size (default 30, max 1000)', default: 30 },
+        cursor: { type: 'number', description: 'Maps to Figma after cursor' },
+        after: { type: 'number', description: 'After cursor' },
+        before: { type: 'number', description: 'Before cursor' },
+      },
+      required: ['team_id'],
+    },
+    handler: async (p) =>
+      text(
+        await apiRequest('GET', '/v1/teams/{team_id}/components', scrub({
+          team_id: p.team_id,
+          page_size: p.page_size ?? 30,
+          after: p.cursor ?? p.after,
+          before: p.before,
+        }))
+      ),
+  },
+  {
+    name: 'get_component',
+    description:
+      'Retrieves detailed metadata for a single published Figma component including its node ID, description and containing file. Use after get_team_components to inspect a specific component.',
+    inputSchema: {
+      type: 'object',
+      properties: { key: { type: 'string', description: 'Published component key' } },
+      required: ['key'],
+    },
+    handler: async (p) => text(await apiRequest('GET', '/v1/components/{key}', { key: p.key })),
+  },
+  {
+    name: 'get_team_component_sets',
+    description:
+      'Lists all component sets (variant groups) in a Figma team library. Use to discover component variants before implementing a design system.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        team_id: { type: 'string', description: 'Team id' },
+        page_size: { type: 'number', description: 'Page size (default 30)', default: 30 },
+        cursor: { type: 'number', description: 'Maps to Figma after cursor' },
+        after: { type: 'number' },
+        before: { type: 'number' },
+      },
+      required: ['team_id'],
+    },
+    handler: async (p) =>
+      text(
+        await apiRequest('GET', '/v1/teams/{team_id}/component_sets', scrub({
+          team_id: p.team_id,
+          page_size: p.page_size ?? 30,
+          after: p.cursor ?? p.after,
+          before: p.before,
+        }))
+      ),
+  },
+  {
+    name: 'get_team_styles',
+    description:
+      'Lists all published styles (colors, text, effects, grids) in a Figma team library. Use to extract design tokens like brand colors and typography from the design system.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        team_id: { type: 'string', description: 'Team id' },
+        page_size: { type: 'number', description: 'Page size (default 30)', default: 30 },
+        cursor: { type: 'number', description: 'Maps to Figma after cursor' },
+        after: { type: 'number' },
+        before: { type: 'number' },
+      },
+      required: ['team_id'],
+    },
+    handler: async (p) =>
+      text(
+        await apiRequest('GET', '/v1/teams/{team_id}/styles', scrub({
+          team_id: p.team_id,
+          page_size: p.page_size ?? 30,
+          after: p.cursor ?? p.after,
+          before: p.before,
+        }))
+      ),
+  },
+  {
+    name: 'get_local_variables',
+    description:
+      'Retrieves all local variables defined in a Figma file including their names, types, values and scopes. Use to extract design tokens for design system implementation.',
+    inputSchema: {
+      type: 'object',
+      properties: { file_key: { type: 'string', description: 'Figma file key' } },
+      required: ['file_key'],
+    },
+    handler: async (p) =>
+      text(await apiRequest('GET', '/v1/files/{file_key}/variables/local', { file_key: p.file_key })),
+  },
+  {
+    name: 'get_published_variables',
+    description:
+      'Retrieves all variables published from a Figma file for use in other files. Use to get the canonical design token values that other files reference.',
+    inputSchema: {
+      type: 'object',
+      properties: { file_key: { type: 'string', description: 'Figma file key' } },
+      required: ['file_key'],
+    },
+    handler: async (p) =>
+      text(await apiRequest('GET', '/v1/files/{file_key}/variables/published', { file_key: p.file_key })),
+  },
+  {
+    name: 'create_variables',
+    description:
+      'Creates new variables (design tokens) in a Figma file. Supports creating variable collections, modes and values in one batch call. Use to programmatically build or update a design system.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        file_key: { type: 'string', description: 'Figma file key' },
+        variables: { type: 'array', description: 'VariableChange[] (create actions)' },
+        collections: { type: 'array', description: 'Maps to variableCollections' },
+        modes: { type: 'array', description: 'Maps to variableModes' },
+        variableModeValues: { type: 'array', description: 'Maps to variableModeValues' },
+        _rawBody: { type: 'object', description: 'Full POST body for POST /variables' },
+      },
+      required: ['file_key'],
+    },
+    handler: async (p) => {
+      const body =
+        p._rawBody ||
+        scrub({
+          variableCollections: p.collections,
+          variableModes: p.modes,
+          variables: p.variables,
+          variableModeValues: p.variableModeValues,
+        });
+      return text(
+        await apiRequest('POST', '/v1/files/{file_key}/variables', { file_key: p.file_key, _rawBody: body })
+      );
+    },
+  },
+  {
+    name: 'update_variables',
+    description:
+      'Updates existing variables in a Figma file including their values, scopes and modes. Use to sync design tokens from a code source of truth back into Figma.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        file_key: { type: 'string', description: 'Figma file key' },
+        variables: { type: 'array', description: 'VariableChange[] update/delete actions' },
+        variableCollections: { type: 'array', description: 'Optional collection updates' },
+        variableModes: { type: 'array', description: 'Optional mode updates' },
+        variableModeValues: { type: 'array', description: 'Optional mode value updates' },
+        _rawBody: { type: 'object', description: 'Full POST body for POST /variables' },
+      },
+      required: ['file_key', 'variables'],
+    },
+    handler: async (p) => {
+      const body =
+        p._rawBody ||
+        scrub({
+          variables: p.variables,
+          variableCollections: p.variableCollections,
+          variableModes: p.variableModes,
+          variableModeValues: p.variableModeValues,
+        });
+      return text(
+        await apiRequest('POST', '/v1/files/{file_key}/variables', { file_key: p.file_key, _rawBody: body })
+      );
+    },
+  },
+];
+
+const COMPOSITE_TOOLS = [
+  {
+    name: 'discover_figma_resources',
+    description:
+      'Universal Figma resource discovery. Parses any figma.com URL for file_key, node_id, team_id, project_id; optionally fetches shallow file (depth=1) and team projects.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        figma_url: { type: 'string', description: 'figma.com file/design/proto/team/project URL' },
+        fetch_children: { type: 'boolean', description: 'Fetch related API payloads', default: true },
+      },
+      required: ['figma_url'],
+    },
+    handler: async (p) => {
+      const parsed = parseFigmaUrl(p.figma_url);
+      const result = { parsed, fetched: {} };
+      if (p.fetch_children === false) return text(result);
+      if (parsed.file_key) {
+        result.fetched.file_pages = await apiRequest('GET', '/v1/files/{file_key}', {
+          file_key: parsed.file_key,
+          depth: 1,
+        });
+      }
+      if (parsed.team_id) {
+        try {
+          result.fetched.team_projects = await apiRequest('GET', '/v1/teams/{team_id}/projects', {
+            team_id: parsed.team_id,
+          });
+        } catch (e) {
+          result.fetched.team_projects_error = e.message;
+        }
+      }
+      if (parsed.project_id) {
+        try {
+          result.fetched.project_files = await apiRequest('GET', '/v1/projects/{project_id}/files', {
+            project_id: parsed.project_id,
+          });
+        } catch (e) {
+          result.fetched.project_files_error = e.message;
+        }
+      }
+      return text(result);
+    },
+  },
+  {
+    name: 'extract_design_tokens',
+    description:
+      'Extracts design tokens from a file: local + published variables, file styles, file components. token_format is a hint for consumers.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        file_key: { type: 'string', description: 'Figma file key' },
+        token_format: {
+          type: 'string',
+          enum: ['css', 'js', 'json', 'tailwind'],
+          default: 'json',
+        },
+      },
+      required: ['file_key'],
+    },
+    handler: async (p) => text(await extractTokensPayload(p.file_key, p.token_format || 'json')),
+  },
+  {
+    name: 'convert_tokens_to_tailwind',
+    description:
+      'Runs extract_design_tokens and builds a Tailwind-style theme.extend object (best-effort from style metadata).',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        file_key: { type: 'string', description: 'Figma file key' },
+        include_font_imports: { type: 'boolean', default: true },
+      },
+      required: ['file_key'],
+    },
+    handler: async (p) => {
+      const base = await extractTokensPayload(p.file_key, 'tailwind');
+      const tailwindConfig = { theme: buildTailwindThemeFromTokens(base) };
+      if (p.include_font_imports !== false) tailwindConfig.fontImports = [];
+      return text({ source: base.meta, tailwindConfig, raw: base });
+    },
+  },
+  {
+    name: 'convert_tokens_to_css_variables',
+    description:
+      'Extracts tokens and emits a :root { } CSS snippet with placeholder custom properties (best-effort from variable metadata).',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        file_key: { type: 'string', description: 'Figma file key' },
+        prefix: { type: 'string', default: '--figma' },
+      },
+      required: ['file_key'],
+    },
+    handler: async (p) => {
+      const data = await extractTokensPayload(p.file_key, 'css');
+      const prefix = (p.prefix || '--figma').replace(/\s+/g, '');
+      const lines = [':root {'];
+      const vars = data.localVariables?.meta?.variables || {};
+      for (const [id, v] of Object.entries(vars)) {
+        const name = `${prefix}-${String(v.name || id)
+          .replace(/\s+/g, '-')
+          .toLowerCase()}`;
+        lines.push(`  ${name}: /* ${v.resolvedType || 'value'} */ var(--figma-var-${id.slice(0, 8)});`);
+      }
+      lines.push('}');
+      return text({ css: lines.join('\n'), structured: data });
+    },
+  },
+  {
+    name: 'get_file_full_structure',
+    description:
+      'Pages at depth=1, then per-page subtree at depth=3 via ids filter for navigable outline.',
+    inputSchema: {
+      type: 'object',
+      properties: { file_key: { type: 'string', description: 'Figma file key' } },
+      required: ['file_key'],
+    },
+    handler: async (p) => {
+      const file = await apiRequest('GET', '/v1/files/{file_key}', { file_key: p.file_key, depth: 1 });
+      const pages = file.document?.children || [];
+      const outline = [];
+      for (const page of pages) {
+        const sub = await apiRequest('GET', '/v1/files/{file_key}', {
+          file_key: p.file_key,
+          depth: 3,
+          ids: page.id,
+        });
+        outline.push({
+          page: { id: page.id, name: page.name },
+          subtree: sub.document?.children || sub.nodes || sub,
+        });
+      }
+      return text({ name: file.name, role: file.role, outline });
+    },
+  },
+  {
+    name: 'get_node_with_children',
+    description:
+      'Fetches a node via GET nodes, then walks response for child ids and issues follow-up GET nodes batches up to max_depth rounds.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        file_key: { type: 'string', description: 'Figma file key' },
+        node_id: { type: 'string', description: 'Root node id' },
+        max_depth: { type: 'number', description: 'BFS rounds (default 5)', default: 5 },
+      },
+      required: ['file_key', 'node_id'],
+    },
+    handler: async (p) => {
+      const maxDepth = p.max_depth ?? 5;
+      let frontier = new Set([p.node_id]);
+      const seen = new Set();
+      const chunks = [];
+      let rounds = 0;
+      while (frontier.size && rounds < maxDepth) {
+        const ids = [...frontier].filter((id) => !seen.has(id));
+        if (!ids.length) break;
+        for (const id of ids) seen.add(id);
+        const part = await apiRequest('GET', '/v1/files/{file_key}/nodes', {
+          file_key: p.file_key,
+          ids: ids.join(','),
+        });
+        chunks.push(part);
+        const next = new Set();
+        const nodesObj = part.nodes || {};
+        for (const doc of Object.values(nodesObj)) {
+          walkNodes(doc.document, (n) => {
+            if (n.id && !seen.has(n.id)) next.add(n.id);
+          });
+        }
+        frontier = next;
+        rounds += 1;
+      }
+      return text({ node_id: p.node_id, rounds, merged_chunks: chunks });
+    },
+  },
+  {
+    name: 'export_design_spec',
+    description:
+      'Bundles GET nodes, file styles, comments, and meta for a node_id; returns markdown or JSON.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        file_key: { type: 'string', description: 'Figma file key' },
+        node_id: { type: 'string', description: 'Target node id' },
+        format: { type: 'string', enum: ['md', 'json'], default: 'md' },
+      },
+      required: ['file_key', 'node_id'],
+    },
+    handler: async (p) => {
+      const [nodes, styles, comments, meta] = await Promise.all([
+        apiRequest('GET', '/v1/files/{file_key}/nodes', { file_key: p.file_key, ids: p.node_id }),
+        apiRequest('GET', '/v1/files/{file_key}/styles', { file_key: p.file_key }),
+        apiRequest('GET', '/v1/files/{file_key}/comments', { file_key: p.file_key }),
+        apiRequest('GET', '/v1/files/{file_key}/meta', { file_key: p.file_key }),
+      ]);
+      const spec = { nodes, styles, comments, meta };
+      if (p.format === 'json') return text(spec);
+      const lines = [
+        '# Design spec',
+        '',
+        `File: ${meta.name || p.file_key} · Node: \`${p.node_id}\``,
+        '',
+        '## Node JSON',
+        '```json',
+        JSON.stringify(nodes, null, 2).slice(0, 12000),
+        '```',
+        '',
+        '## Comments (first 20)',
+        JSON.stringify((comments.comments || []).slice(0, 20), null, 2),
+      ];
+      return text({ format: 'md', markdown: lines.join('\n'), raw: spec });
+    },
+  },
+  {
+    name: 'search_nodes_by_name',
+    description:
+      'GET full file document and walk the tree; supports * ? wildcards and optional node_type filter.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        file_key: { type: 'string', description: 'Figma file key' },
+        name_query: { type: 'string', description: 'Pattern (* ?)' },
+        node_type: { type: 'string', description: 'FRAME, COMPONENT, TEXT, …' },
+      },
+      required: ['file_key', 'name_query'],
+    },
+    handler: async (p) => {
+      const file = await apiRequest('GET', '/v1/files/{file_key}', { file_key: p.file_key });
+      const hits = [];
+      walkNodes(file.document, (node, pathNames) => {
+        const okName = nameMatch(p.name_query, node.name || '');
+        const okType = !p.node_type || node.type === p.node_type;
+        if (okName && okType) {
+          hits.push({
+            id: node.id,
+            name: node.name,
+            type: node.type,
+            path: pathNames.filter(Boolean).join(' / '),
+          });
+        }
+      });
+      return text({ count: hits.length, hits: hits.slice(0, 200) });
+    },
+  },
+  {
+    name: 'get_prototype_flows',
+    description:
+      'No dedicated /prototype/flows route; aggregates flowStartingPoints from file JSON (depth=2).',
+    inputSchema: {
+      type: 'object',
+      properties: { file_key: { type: 'string', description: 'Figma file key' } },
+      required: ['file_key'],
+    },
+    handler: async (p) => {
+      const file = await apiRequest('GET', '/v1/files/{file_key}', { file_key: p.file_key, depth: 2 });
+      const flows = [];
+      walkNodes(file.document, (node) => {
+        if (node.flowStartingPoints?.length) {
+          flows.push(
+            ...node.flowStartingPoints.map((f) => ({
+              ...f,
+              pageOrNodeId: node.id,
+              pageOrNodeName: node.name,
+            }))
+          );
+        }
+      });
+      return text({
+        fileName: file.name,
+        prototypeStartingPoint: file.prototypeStartingPoint,
+        flowStartingPoints: flows,
+      });
+    },
+  },
+  {
+    name: 'compare_file_versions',
+    description:
+      'GET file twice with different version ids (depth=4) and diff node id sets (added / removed / common counts).',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        file_key: { type: 'string', description: 'Figma file key' },
+        version_id_1: { type: 'string', description: 'First version id' },
+        version_id_2: { type: 'string', description: 'Second version id' },
+      },
+      required: ['file_key', 'version_id_1', 'version_id_2'],
+    },
+    handler: async (p) => {
+      const [a, b] = await Promise.all([
+        apiRequest('GET', '/v1/files/{file_key}', {
+          file_key: p.file_key,
+          version: p.version_id_1,
+          depth: 4,
+        }),
+        apiRequest('GET', '/v1/files/{file_key}', {
+          file_key: p.file_key,
+          version: p.version_id_2,
+          depth: 4,
+        }),
+      ]);
+      const idsA = new Set();
+      const idsB = new Set();
+      walkNodes(a.document, (n) => {
+        if (n.id) idsA.add(n.id);
+      });
+      walkNodes(b.document, (n) => {
+        if (n.id) idsB.add(n.id);
+      });
+      const added = [...idsB].filter((id) => !idsA.has(id));
+      const removed = [...idsA].filter((id) => !idsB.has(id));
+      const common = [...idsA].filter((id) => idsB.has(id));
+      return text({
+        version_id_1: p.version_id_1,
+        version_id_2: p.version_id_2,
+        summary: { added_count: added.length, removed_count: removed.length, common_count: common.length },
+        sample_added: added.slice(0, 50),
+        sample_removed: removed.slice(0, 50),
+      });
+    },
+  },
+];
+
+function dedupeToolNames(list) {
+  const seen = new Map();
+  return list.map((t) => {
+    let name = t.name;
+    if (seen.has(name)) {
+      let n = 2;
+      while (seen.has(`${name}_v${n}`)) n += 1;
+      name = `${name}_v${n}`;
+    }
+    seen.set(name, true);
+    return { ...t, name };
+  });
+}
+
+const generated = buildGeneratedTools();
+export const tools = dedupeToolNames([...CUSTOM_TOOLS_FRONT, ...generated, ...COMPOSITE_TOOLS]);