Figma MCP

Instructions

Implementation Reference

• src/tools/handlers/agentContext.js:174-302 (handler)

  Main handler function that executes the get_agent_context tool: fetches Figma data, identifies sections, extracts assets/styles/responsibilities, generates agent-specific instructions.

  export async function getAgentContext(
    ctx,
    fileKey,
    pageName,
    frameName,
    sectionId,
    agentIndex = 0,
    totalAgents = 1
  ) {
    const { session, chunker, figmaClient } = ctx;
  
    session.setCurrentFile(fileKey);
    const file = await figmaClient.getFile(fileKey, 3);
    const page = figmaClient.findPageByName(file, pageName);
  
    if (!page) {
      const available = file.document.children.map((p) => p.name).join(", ");
      throw new Error(`Page "${pageName}" not found. Available: ${available}`);
    }
  
    const frameRef = figmaClient.findFrameByName(page, frameName);
    if (!frameRef) {
      const available = (page.children || [])
        .filter((c) => c.type === "FRAME" || c.type === "COMPONENT")
        .map((f) => f.name)
        .join(", ");
      throw new Error(`Frame "${frameName}" not found. Available: ${available}`);
    }
  
    const frame = await figmaClient.getNode(fileKey, frameRef.id);
  
    const sectionGroups = groupNodesBySection(frame.children || []);
  
    const sectionIndex = parseInt(sectionId.split("-")[1], 10);
    if (sectionIndex < 0 || sectionIndex >= sectionGroups.length) {
      throw new Error(`Invalid section ID: ${sectionId}. Available: section-0 to section-${sectionGroups.length - 1}`);
    }
  
    const sectionGroup = sectionGroups[sectionIndex];
    const sectionName = inferSectionName(sectionGroup.nodes[0].name) || `Section ${sectionIndex + 1}`;
  
    const section = {
      id: sectionId,
      name: sectionName,
      bgColor: sectionGroup.bgColor || "#FFFFFF",
      bounds: {
        x: Math.round(sectionGroup.minY),
        y: Math.round(sectionGroup.minY),
        width: frame.absoluteBoundingBox?.width || 0,
        height: Math.round(sectionGroup.maxY - sectionGroup.minY),
      },
    };
  
    const sectionNodeIds = new Set();
    const sectionNodes = [];
  
    for (const node of sectionGroup.nodes) {
      const collectNodeIds = (n) => {
        sectionNodeIds.add(n.id);
        sectionNodes.push(n);
        if (n.children) {
          n.children.forEach(collectNodeIds);
        }
      };
      collectNodeIds(node);
    }
  
    const frameAssets = findAssets(frame, {});
  
    const sectionAssets = extractSectionAssets(Array.from(sectionNodeIds), frameAssets);
  
    const enrichedAssets = {
      icons: sectionAssets.icons.map((a) => buildAssetDetails(a, fileKey, sectionName)),
      images: sectionAssets.images.map((a) => buildAssetDetails(a, fileKey, sectionName)),
    };
  
    const sectionStyles = extractSectionStyles(sectionNodes);
  
    const responsibilities = {
      implements: sectionGroup.nodes.map((n) => n.name),
      coordinates: [],
      skips: [],
    };
  
    const transitionElements = findTransitionElements(sectionGroups, frame.children || []);
    for (const element of transitionElements) {
      if (element.spansSections.includes(sectionId)) {
        responsibilities.coordinates.push(element.name);
      }
    }
  
    const allSectionIndices = new Set();
    for (let i = 0; i < sectionGroups.length; i++) {
      allSectionIndices.add(i);
    }
    allSectionIndices.delete(sectionIndex);
    for (const idx of allSectionIndices) {
      for (const node of sectionGroups[idx].nodes) {
        responsibilities.skips.push(node.name);
      }
    }
  
    const agentInfo = {
      index: agentIndex,
      total: totalAgents,
      isFirst: agentIndex === 0,
      isLast: agentIndex === totalAgents - 1,
    };
  
    const instructions = buildAgentInstructions(section, agentInfo, responsibilities, enrichedAssets, sectionStyles);
  
    const result = {
      section,
      responsibilities,
      assets: enrichedAssets,
      styles: sectionStyles,
      agentInfo,
      instructions,
    };
  
    const response = chunker.wrapResponse(result, {
      step: `Prepared context for Agent ${agentIndex}`,
      progress: `${section.name} section (${agentIndex + 1}/${totalAgents})`,
      nextStep: "Agent can now implement this section with all necessary context",
      alert: `Agent responsible for: ${responsibilities.implements.join(", ")}`,
    });
  
    return { content: [{ type: "text", text: JSON.stringify(response, null, 2) }] };
  }

• src/tools/schemas.js:356-412 (schema)

  Input schema and description for the get_agent_context tool, defining parameters like file_key, page_name, frame_name, section_id, agent_index, total_agents.

    {
      name: "get_agent_context",
      description: `Prepare agent context for parallel implementation of a section.
  
  HOW IT WORKS:
  - Call after analyze_page_structure to identify sections
  - Returns complete context for a single agent to implement one section
  - Handles responsibilities: what to implement vs coordinate
  - Includes icons, styles, and transition element info
  - Generates agent-specific instructions with coordination rules
  
  RETURNS:
  - section: Details (id, name, background color, bounds)
  - responsibilities: what agent implements, coordinates, or skips
  - assets: icons and images in this section
  - styles: colors, fonts, spacing specific to section
  - agent_info: index, total agents, is_first, is_last
  - instructions: detailed markdown instructions for this agent
  
  TYPICAL WORKFLOW:
  1. analyze_page_structure → identify sections
  2. For each section: get_section_screenshot → visual reference
  3. get_agent_context(sectionId, agentIndex) → agent-specific context
  4. Each agent implements using provided context`,
      inputSchema: {
        type: "object",
        properties: {
          file_key: {
            type: "string",
            description: "Figma file key from URL",
          },
          page_name: {
            type: "string",
            description: "Page name (partial match)",
          },
          frame_name: {
            type: "string",
            description: "Frame name (partial match)",
          },
          section_id: {
            type: "string",
            description: "Section ID from analyze_page_structure (e.g., 'section-0')",
          },
          agent_index: {
            type: "number",
            description: "Zero-based agent index (default: 0)",
            default: 0,
          },
          total_agents: {
            type: "number",
            description: "Total number of agents working in parallel (default: 1)",
            default: 1,
          },
        },
        required: ["file_key", "page_name", "frame_name", "section_id"],
      },
    },

• src/index.js:75-84 (registration)

  Tool registration in the main MCP server request handler switch statement, dispatching 'get_agent_context' calls to handlers.getAgentContext.

  case "get_agent_context":
    result = await handlers.getAgentContext(
      this.ctx,
      args.file_key,
      args.page_name,
      args.frame_name,
      args.section_id,
      args.agent_index || 0,
      args.total_agents || 1
    );

• src/tools/handlers/index.js:9-9 (registration)

  Re-export of the getAgentContext handler from agentContext.js, making it available as handlers.getAgentContext.

  export { getAgentContext } from "./agentContext.js";