Navigator v3.4.0 Release Notes

Navigator v3.4.0 Release Notes

Release Date: 2025-10-22 Type: Minor Release - Feature Addition

🎉 Major Feature: Direct Figma MCP Integration

Navigator's product-design skill now connects directly to Figma Desktop via Python, eliminating manual orchestration overhead.

What's New

Direct Python → Figma MCP Client

• ✨ Zero Orchestration: Python connects to Figma MCP automatically (no Claude middleware)
• ✨ One-Command Setup: ./setup.sh installs everything in 30 seconds
• ✨ Progressive Refinement: Smart token usage (fetches only needed data)
• ✨ Production Ready: Full error handling, diagnostics, and documentation

Performance Improvements:

• 95% reduction in orchestration steps (15-20 → 1)
• 92% reduction in token usage (150k → 12k)
• 75% faster design reviews (15 min → 5 min)

New Files

Skills:

• skills/product-design/requirements.txt - Python dependencies (mcp>=1.2.1)
• skills/product-design/setup.sh - Automated installation script
• skills/product-design/functions/figma_mcp_client.py - MCP client wrapper (309 lines)
• skills/product-design/functions/test_mcp_connection.py - Connection diagnostic

Documentation:

• skills/product-design/README.md - Quick start and features
• skills/product-design/INSTALL.md - Detailed installation guide
• skills/product-design/GETTING-STARTED.md - 5-minute quickstart
• skills/product-design/SKILL.md - Updated workflow documentation

Analysis & Research:

• .agent/design-system/figma-mcp-integration-report.md - Technical analysis
• .agent/design-system/mcp-sdk-summary.md - MCP SDK documentation
• .agent/design-system/implementation-summary.md - Implementation details

Breaking Changes

Product Design Skill

New Requirements:

1. Python 3.10+ (previously optional)
2. Figma Desktop with MCP enabled (for automated workflow)
3. Python dependencies: mcp>=1.2.1

Migration:

cd skills/product-design
./setup.sh  # Installs all dependencies

Figma Setup:

1. Install Figma Desktop (https://www.figma.com/downloads/)
2. Figma → Preferences → Enable "Enable local MCP Server"

Backward Compatibility: Manual workflow (without Figma Desktop) still available.

Installation

New Users

cd skills/product-design
./setup.sh

What it does:

1. Checks Python 3.10+ installed
2. Creates virtual environment
3. Installs mcp SDK and dependencies
4. Verifies Figma Desktop connection
5. Tests MCP server availability

Existing Users (Upgrade)

Same command - setup.sh handles everything:

cd skills/product-design
./setup.sh

Usage

Before (v3.3.1)

User: "Review Figma design: [URL]"

Claude:
  1. Call get_metadata → save /tmp/metadata.json
  2. Call get_variable_defs → save /tmp/variables.json
  3. Call get_code_connect_map → save /tmp/code_connect.json
  4. Run python design_analyzer.py --input /tmp/metadata.json
  5. Run python token_extractor.py --input /tmp/variables.json
  ... 15-20 steps total ...

Time: 15-20 minutes

After (v3.4.0)

User: "Review Figma design: [URL]"

Python (automatic):
  - Connect to Figma MCP
  - Progressive refinement (smart data fetching)
  - Return complete analysis

Time: 5 minutes (75% faster)

Technical Details

Architecture Changes

MCP Client:

• Official Anthropic MCP SDK (pip install mcp)
• Streamable HTTP transport (http://127.0.0.1:3845/mcp)
• Async context manager for connection lifecycle
• Automatic JSON parsing and error handling

Available Figma Tools:

1. get_metadata() - Component structure (XML)
2. get_variable_defs() - Design tokens
3. get_code_connect_map() - Component → code mappings
4. get_design_context() - UI code generation
5. get_screenshot() - Visual snapshots
6. create_design_system_rules() - Design system automation

Code Example:

from figma_mcp_client import FigmaMCPClient

async with FigmaMCPClient() as client:
    # Get metadata (low tokens)
    metadata = await client.get_metadata()

    # Progressive refinement
    for component in high_complexity_components:
        detail = await client.get_design_context(component.id)

    # Get design tokens
    tokens = await client.get_variable_defs()

Bug Fixes

• Fixed screenshot handling to support image content (not just text)
• Added proper error handling for Figma Desktop not running
• Improved connection diagnostics and error messages

Dependencies

New Dependencies (Product Design Skill)

mcp>=1.2.1          # Official MCP SDK
anyio>=4.0.0        # Async I/O (transitive)
httpx>=0.25.0       # HTTP client (transitive)
pydantic>=2.0.0     # Data validation (transitive)

Installed automatically via ./setup.sh

System Requirements

• Python: 3.10+ (was 3.8+ previously)
• Figma Desktop: v116.0.0+ (new requirement)
• OS: macOS, Linux, Windows (unchanged)

Documentation

New Documentation

• README.md - Features, architecture, examples
• INSTALL.md - Installation guide with troubleshooting
• GETTING-STARTED.md - 5-minute quickstart

Updated Documentation

• SKILL.md - Updated workflow, prerequisites, installation

Technical Reports

• Figma MCP Integration Report - Complete technical analysis
• MCP SDK Summary - SDK documentation and API reference
• Implementation Summary - Build details and validation results

Testing

Validation

✅ Setup Script: Tested on macOS 15.0.0 ✅ MCP Connection: Validated with Figma Desktop v125.9.10 ✅ Real Design Test: Successfully extracted data from production Figma file ✅ All 6 MCP Tools: Verified working

Test Results

Linear Invoices Design (production test):

• ✅ Connected to Figma MCP server
• ✅ Extracted 26 elements, 14 reusable components
• ✅ Identified StatiticsCard (3x), Avatar (2x), Navigation (1x)
• ✅ Generated 79,968 byte screenshot (PNG)

Known Limitations

1. Figma Desktop Required: Web app not supported

   • Workaround: Manual workflow still available

2. Local Only: MCP server only on localhost

   • Intended behavior (security)

3. Code Connect: Requires Figma Enterprise

   • Fallback: Fuzzy name matching

4. Design Tokens: Only if defined in Figma file

   • Normal: Many designs don't use variables yet

Migration Guide

From v3.3.1 to v3.4.0

Step 1: Pull latest code

git pull origin main

Step 2: Run setup script

cd skills/product-design
./setup.sh

Step 3: Enable Figma MCP

Figma → Preferences → Enable local MCP Server

Step 4: Test

"Review this Figma design: [URL]"

Time: 2-3 minutes

Upgrade Path

If Setup Fails

See INSTALL.md for troubleshooting:

• Python version issues
• Figma Desktop not running
• MCP connection errors
• Port conflicts

If You Don't Use Figma

Product-design skill still works without Figma Desktop:

• Manual workflow prompts for design data
• All other Navigator features unchanged

Credits

MCP Integration: Built with Anthropic's official MCP Python SDK Figma Desktop: Uses Figma's local MCP server (v116.0.0+) Testing: Validated with Linear Invoices production design

Next Steps

Future Enhancements (v3.5.0+):

• Refactor existing Python functions to use MCP client directly
• Visual regression testing integration
• Design system drift auto-fix
• Component screenshot comparisons

Feedback

Report issues: https://github.com/navigator-plugin/navigator/issues

Include:

• Python version: python3 --version
• Figma version: Figma → Help → About Figma
• Output from: python3 functions/test_mcp_connection.py

Version Compatibility

Full Changelog: https://github.com/navigator-plugin/navigator/compare/v3.3.1...v3.4.0

Previous Release: v3.3.1