Jira-Figma MCP

A TypeScript Model Context Protocol (MCP) server for integrating Jira and Figma with AI systems. This MCP allows AI systems to retrieve Jira tickets, extract Figma links, and fetch the corresponding component designs.

Features

• Official MCP SDK Integration: Built with the ModelContextProtocol SDK for standardized AI interaction
• Multiple Transport Options:
  • HTTP/SSE for web-based AI integration
  • Stdio for direct AI integration
• Jira Integration: Connect to Jira to retrieve tickets
• Figma Integration:
  • Parse Figma URLs and fetch design information
  • Simplify complex Figma responses into a more usable format
• Enhanced Figma Extraction:
  • Robust URL extraction from Jira tickets (finds links in descriptions, comments, and custom fields)
  • Comprehensive parsing of Figma URLs to extract file keys and node IDs
  • Automatic deduplication of design references
• Enhanced Figma Processing:
  • Robust type checking for Figma API responses
  • Improved color conversion utilities (HEX, RGBA, HSL)
  • Advanced node visibility detection
  • Smart paint parsing for gradients, images, and solids
  • Advanced text styling extraction
  • Variable management system for reusable styles
• Standard MCP Interface: Implements standard MCP tools for Jira and Figma interaction
• Caching: Efficient caching of API calls for improved performance
• Parameter Validation: Runtime schema validation using Zod
• Structured Error Handling: Provides clear error messages in MCP-compliant format

Prerequisites

• Node.js (v18 or newer recommended)
• Jira account with API token
• Figma account with personal access token

Installation

1. Clone this repository:

   git clone https://github.com/flexapp/auto-fe-engineer-mcp.git

2. Install dependencies:

   yarn

3. Create a .env file in the project root with the following variables (see .env.example):

   # Jira Configuration
   JIRA_HOST=https://your-jira-instance.atlassian.net
   [email protected]
   JIRA_API_TOKEN=your-jira-api-token
   JIRA_FIGMA_FIELD_NAME=Figma Link
   
   # Figma Configuration
   FIGMA_ACCESS_TOKEN=your-figma-personal-access-token
   
   # Server Configuration
   PORT=3000
   CACHE_TTL=3600

Usage

Running the MCP Server

HTTP/SSE Mode (for web-based AI integration)

yarn build
yarn start

Stdio Mode (for direct AI integration)

yarn build
yarn start:stdio

For development:

yarn dev         # HTTP/SSE mode
yarn dev:stdio   # Stdio mode

Using npx to Run Remotely

You can use npx to run the MCP server without installation:

# Run the MCP server in HTTP/SSE mode
npx auto-fe-engineer-mcp

# Run in stdio mode
npx auto-fe-engineer-mcp --stdio

This will automatically download and run the latest version of the MCP server. You will still need to configure environment variables:

# Create a .env file in your current directory
echo "JIRA_HOST=https://your-jira-instance.atlassian.net
[email protected]
JIRA_API_TOKEN=your-jira-api-token
JIRA_FIGMA_FIELD_NAME=Figma Link
FIGMA_ACCESS_TOKEN=your-figma-personal-access-token
PORT=3000
CACHE_TTL=3600" > .env

# Then run the MCP
npx auto-fe-engineer-mcp

You can also install it globally for easier access:

# Install globally
npm install -g auto-fe-engineer-mcp

# Run anywhere
auto-fe-engineer-mcp

MCP Tools

The MCP exposes the following tools for AI systems:

Jira Tools

• get_ticket: Gets detailed information about a specific Jira ticket

  {
    ticket_id: string; // The Jira ticket ID (e.g., PROJECT-123)
  }

Figma Tools

• get_figma_data: Gets structured data from a Figma file

  {
    fileKey: string,   // The key of the Figma file to fetch
    nodeId?: string,   // The ID of the node to fetch (optional)
    depth?: number     // How many levels deep to traverse the node tree (optional)
  }

Linking Tools

• get_designs_for_ticket: Gets Figma design information linked to a Jira ticket

  {
    ticket_id: string, // The Jira ticket ID (e.g., PROJECT-123)
    depth?: number     // Depth to traverse the Figma node tree (optional)
  }

Connecting to the MCP

HTTP/SSE Mode

1. Connect to the SSE endpoint at http://localhost:3000/mcp/sse (or your configured PORT)
2. Send JSON-RPC messages to http://localhost:3000/mcp/messages

Stdio Mode

1. Connect to the process's standard input/output
2. Send and receive JSON-RPC messages directly

Example message:

{
  "jsonrpc": "2.0",
  "id": "1",
  "method": "get_ticket",
  "params": {
    "ticket_id": "DEMO-123"
  }
}

Using MCP with Cursor AI Agent

Cursor's AI assistant can leverage this MCP to access Jira tickets and Figma designs directly during coding sessions. This enables the AI to reference design specifications when implementing components.

Setup for Cursor AI Integration

1. Ensure the MCP server is running:

   yarn start

2. When using Cursor AI, you can directly request Jira tickets and Figma designs with commands like:

   • get figma from jira PROJECT-123 - Fetches designs linked to a specific Jira ticket
   • show me the design for ticket PROJECT-123 - Retrieves and displays design information

3. The AI agent will:

   • Connect to the MCP server
   • Retrieve the requested Jira ticket information
   • Extract Figma links from the ticket
   • Fetch and process the Figma design data
   • Present relevant design specifications for implementation

4. Use the retrieved design details to guide front-end implementation:

   • Component structure
   • Styling information (colors, fonts, spacing)
   • Layout specifications
   • Interactive elements

Example Workflow

1. Start a new component implementation task
2. Ask Cursor AI: get figma from jira CE2-1234
3. The AI will retrieve design specs and can help you implement the component according to the design
4. Reference specific design elements during implementation: "What's the font size for the heading?"
5. The AI can reference the design data to provide accurate implementation guidance

Example Requests

Get a Jira Ticket

{
  "jsonrpc": "2.0",
  "id": "1",
  "method": "get_ticket",
  "params": {
    "ticket_id": "DEMO-123"
  }
}

Get Figma Data

{
  "jsonrpc": "2.0",
  "id": "2",
  "method": "get_figma_data",
  "params": {
    "fileKey": "abcdefghijklmnopqrst",
    "nodeId": "1:234",
    "depth": 3
  }
}

Get Designs for a Jira Ticket

{
  "jsonrpc": "2.0",
  "id": "3",
  "method": "get_designs_for_ticket",
  "params": {
    "ticket_id": "DEMO-123",
    "depth": 2
  }
}

Figma URL Extraction

The server uses a sophisticated approach to extract Figma URLs from Jira tickets:

1. Primary extraction methods:

   • Extracts URLs from href attributes in Jira's rich text fields
   • Finds embedCard references with Figma URLs
   • Parses direct text mentions in descriptions and comments
   • Checks for dedicated Figma link fields (configurable)

2. URL parsing and normalization:

   • Cleans URLs by handling escape sequences and encoding issues
   • Extracts file keys and node IDs for direct Figma API access
   • Removes duplicates for more efficient processing

3. Response format for get_designs_for_ticket:

   {
     "ticket_id": "DEMO-123",
     "ticket_summary": "Create new button component",
     "ticket": {
       /* Full Jira ticket data */
     },
     "designs": [
       {
         "url": "https://www.figma.com/file/abc123/Design-System?node-id=456",
         "fileKey": "abc123",
         "nodeId": "456",
         "design": {
           /* Simplified Figma design data */
         }
       }
     ]
   }

MCP Protocol Compliance

This MCP follows the official Model Context Protocol specifications using the MCP SDK:

• Implements the JSON-RPC 2.0 message format
• Uses the standard MCP content response format
• Provides tool discovery via rpc.discover
• Supports the recommended transport mechanisms (HTTP/SSE and stdio)
• Implements standard MCP tool schema

Simplified Figma Response Format

The MCP simplifies Figma's complex API responses into a more usable format with enhanced type safety:

{
  "name": "Design System",
  "lastModified": "2023-06-15T12:34:56Z",
  "thumbnailUrl": "https://figma-api.example.com/thumbnails/...",
  "nodes": [
    {
      "id": "1:234",
      "name": "Button/Primary",
      "type": "COMPONENT",
      "boundingBox": { "x": 0, "y": 0, "width": 100, "height": 40 },
      "fills": "fill_a1b2c3",
      "borderRadius": "4px",
      "children": [
        {
          "id": "1:235",
          "name": "Label",
          "type": "TEXT",
          "text": "Click me",
          "textStyle": "style_d4e5f6"
        }
      ]
    }
  ],
  "globalVars": {
    "styles": {
      "fill_a1b2c3": [
        {
          "type": "SOLID",
          "hex": "#0066FF",
          "rgba": "rgba(0, 102, 255, 1)"
        }
      ],
      "style_d4e5f6": {
        "fontFamily": "Inter",
        "fontWeight": 600,
        "fontSize": 16,
        "lineHeight": "1.5em",
        "letterSpacing": "0.5%",
        "textCase": "TITLE",
        "textAlignHorizontal": "CENTER",
        "textAlignVertical": "CENTER"
      }
    }
  }
}

Testing

Run tests with:

yarn test

Publishing to npm

If you want to publish this package to npm to enable remote usage with npx, follow these steps:

1. Ensure you have an npm account and are logged in:

   npm login

2. Update the package.json with your information:

   • Set your name or organization in the author field
   • Update the repository URLs if you've forked the repository
   • Adjust the version number following semantic versioning

3. Build the package and publish:

   npm run build
   npm publish

4. After publishing, users can run the MCP using npx:

   npx auto-fe-engineer-mcp

If you need to update the package:

1. Update the code as needed
2. Increment the version in package.json (following semantic versioning)
3. Run npm publish again

For more information on npm publishing, see the npm documentation.