figma_design

Instructions

Implementation Reference

• mcp_simple_tool/server.py:174-185 (handler)

  The handler function for the 'figma_design' tool. It calls the helper fetch_figma_data with the provided URL and handles exceptions.

  async def get_figma_design(
      url: str,
  ) -> list[types.TextContent | types.ImageContent | types.EmbeddedResource]:
      """Get Figma design data including structure and images."""
      try:
          return fetch_figma_data(url)
      except Exception as e:
          return [types.TextContent(
              type="text",
              text=json.dumps({"error": f"Failed to fetch Figma design: {str(e)}"})
          )]

• mcp_simple_tool/server.py:18-97 (helper)

  Helper function that implements the core logic: parses Figma URL, fetches file structure and image data using Figma API, collects image nodes recursively, fetches image URLs, and returns JSON-structured data.

  def fetch_figma_data(figma_url: str) -> List[types.TextContent]:
      parsed = urlparse(figma_url)
      # Support both '/file/…' and '/design/…' URL formats.
      file_key = re.search(r'/(?:file|design)/([a-zA-Z0-9]+)', parsed.path).group(1)
      qs = parse_qs(parsed.query)
      node_ids = qs.get("node-id", [])
      headers = {"X-FIGMA-TOKEN": os.getenv("FIGMA_ACCESS_TOKEN")}
  
      # Get structure: use nodes endpoint if node-id is provided, else full file.
      if node_ids:
          resp = requests.get(f"https://api.figma.com/v1/files/{file_key}/nodes", headers=headers, params={"ids": ",".join(node_ids)})
          data = resp.json()
          # Structure is returned as a dict mapping each node_id to its document.
          structure = {nid: info["document"] for nid, info in data.get("nodes", {}).items()}
      else:
          resp = requests.get(f"https://api.figma.com/v1/files/{file_key}", headers=headers)
          data = resp.json()
          structure = data.get("document", {})
  
      # Recursively traverse a node to collect those with an image fill.
      def collect_image_nodes(node):
          imgs = []
          if isinstance(node, dict):
              if node.get("fills") and isinstance(node["fills"], list):
                  for fill in node["fills"]:
                      if fill.get("type") == "IMAGE" and "imageRef" in fill:
                          imgs.append({
                              "node_id": node.get("id"),
                              "image_ref": fill.get("imageRef"),
                              "bounding_box": node.get("absoluteBoundingBox", {})
                          })
                          break  # one image fill per node is enough
              for child in node.get("children", []):
                  imgs.extend(collect_image_nodes(child))
          return imgs
  
      # Get all image nodes from the structure.
      image_nodes = []
      if node_ids:
          for doc in structure.values():
              image_nodes.extend(collect_image_nodes(doc))
      else:
          image_nodes = collect_image_nodes(structure)
  
      # Fetch image URLs using the node IDs that have image fills.
      image_node_ids = list({img["node_id"] for img in image_nodes if img.get("node_id")})
      if image_node_ids:
          params = {"ids": ",".join(image_node_ids), "format": "png"}
          img_resp = requests.get(f"https://api.figma.com/v1/images/{file_key}", headers=headers, params=params)
          img_mapping = img_resp.json().get("images", {})
      else:
          img_mapping = {}
  
      # Combine the imageRef details with the fetched image URLs.
      for img in image_nodes:
          nid = img.get("node_id")
          img["image_url"] = img_mapping.get(nid)
  
      # Return both structure and images as TextContent
      result = []
      
      # Add structure data
      result.append(types.TextContent(
          type="text",
          text=json.dumps({
              "type": "structure",
              "data": structure
          }, indent=2)
      ))
      
      # Add image data
      result.append(types.TextContent(
          type="text",
          text=json.dumps({
              "type": "images",
              "data": image_nodes
          }, indent=2)
      ))
  
      return result

• mcp_simple_tool/server.py:232-238 (handler)

  Dispatch logic in the main tool handler (@app.call_tool()) that routes calls to 'figma_design' to the get_figma_design function after input validation.

  elif name == "figma_design":
      if "url" not in arguments:
          return [types.TextContent(
              type="text",
              text="Error: Missing required argument 'url'"
          )]
      return await get_figma_design(arguments["url"])

• mcp_simple_tool/server.py:309-322 (registration)

  Tool registration in @app.list_tools(), including name, description, and input schema.

  types.Tool(
      name="figma_design",
      description="Get Figma design data including structure and images",
      inputSchema={
          "type": "object",
          "required": ["url"],
          "properties": {
              "url": {
                  "type": "string",
                  "description": "The full Figma design URL",
              }
          },
      },
  ),

• mcp_simple_tool/server.py:312-322 (schema)

  Input schema definition for the 'figma_design' tool, specifying required 'url' parameter.

      inputSchema={
          "type": "object",
          "required": ["url"],
          "properties": {
              "url": {
                  "type": "string",
                  "description": "The full Figma design URL",
              }
          },
      },
  ),