Widgetbook MCP Server

A Model Context Protocol (MCP) server that supercharges Flutter Widgetbook development by giving AI assistants direct access to create, modify, and test UI components in your design system.

This is experimental and shouldnt be used in your production apps/design system

Work in progress

Overview

The Widgetbook MCP Server bridges the gap between AI assistants and Flutter Widgetbook projects, enabling powerful new workflows including:

• Automated UI Documentation: Generate boilerplate code and use cases for widgets
• Conversational UI Prototyping: Interactive, dialogue-based UI design and modification
• Automated UI Regression Testing: Comprehensive visual testing of UI components
• Context-Aware Code Generation: AI-generated code that follows existing design system patterns

Features

Core Capabilities

• Widget Discovery (widgetbook.list_widgets): Lists all available widgets in the project
• Widget Inspection (widgetbook.get_widget_details): Retrieves detailed information about specific widgets, including properties and use cases
• Use Case Management (widgetbook.get_widget_use_cases): Gets all existing use cases for a widget
• Code Generation (widgetbook.generate_use_case_code): Generates new WidgetbookUseCase code snippets
• Code Modification (widgetbook.modify_widget_use_case): Modifies existing use case properties
• Testing (widgetbook.run_use_case_test): Executes tests for specific use cases
• Screenshot Generation (widgetbook.generate_screenshot): Captures visual snapshots of use cases

Performance & Security

• Fast Response Times: Target response time under 500ms for all operations
• Secure Communication: MCP protocol ensures secure access to project files
• Intuitive API: Consistent, logical structure following MCP best practices

Installation

Prerequisites

• Dart SDK 3.0.0 or higher
• Flutter project with Widgetbook dependency
• Git (for cloning the repository)

Install from pub.dev

// TODO

Install from source

git clone https://github.com/mastersam07/widgetbook_mcp_server.git
cd widgetbook_mcp_server
dart pub get
dart compile exe bin/widgetbook_mcp_server.dart -o widgetbook-mcp-server

Usage

MCP Client Configuration

Using compiled executable

Add to your MCP client configuration (e.g., Cursor):

{
  "mcpServers": {
    "widgetbook": {
      "command": "path/to/compiled/widgetbook-mcp-server",
      "args": ["--project-path", "/path/to/your/flutter/project"]
    }
  }
}

From source directly

Add to your MCP client configuration (e.g., Cursor):

{
  "mcpServers": {
    "widgetbook": {
      "command": "dart",
      "args": [
        "run",
        "path/to/widgetbook-mcp-server/bin/widgetbook-mcp-server.dart",
        "--project-path",
        "/path/to/your/flutter/project",
        ]
    }
  }
}

API Reference

Tools

widgetbook.list_widgets

Lists all available widgets in the Widgetbook project.

Parameters: None

Returns:

[
  {
    "name": "ProductCard",
    "description": "A card component for displaying product information"
  }
]

widgetbook.get_widget_details

Retrieves detailed information about a specific widget.

Parameters:

• widget_name (string, required): The unique name of the widget

Returns:

{
  "name": "ProductCard",
  "description": "A card component for displaying product information",
  "properties": [
    {
      "name": "title",
      "type": "String",
      "defaultValue": "Product Title"
    }
  ],
  "use_cases": [
    {
      "name": "default",
      "description": "Default product card",
      "fileName": "product_card.dart"
    }
  ]
}

widgetbook.generate_use_case_code

Generates a new WidgetbookUseCase code snippet.

Parameters:

• widget_name (string, required): The name of the widget
• property_values (object, required): Map of property names to values

Returns:

{
  "file_path": "lib/widgetbooks/product_card.dart",
  "generated_code": "WidgetbookUseCase(\n  name: 'dark_theme',\n  builder: (context) {\n    return ProductCard(\n      title: 'Dark Theme Product',\n    );\n  },\n),"
}

widgetbook.generate_screenshot

Captures a screenshot of a specific use case.

Parameters:

• widget_name (string, required): The name of the widget
• use_case_name (string, required): The name of the use case

Returns:

{
  "use_case_name": "dark_theme",
  "image_data": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJ...",
  "file_path": ".widgetbook/screenshots/ProductCard_dark_theme.png"
}

Resources

widgetbook://project-info

Provides information about the current Widgetbook project.

widgetbook://config

Returns the current server configuration and capabilities.

Example Widgetbook File

import 'package:flutter/material.dart';
import 'package:widgetbook/widgetbook.dart';
import '../widgets/product_card.dart';

WidgetbookComponent productCardComponent() {
  return WidgetbookComponent(
    name: 'ProductCard',
    useCases: [
      WidgetbookUseCase(
        name: 'Default',
        builder: (context) => ProductCard(
          title: context.knobs.string(
            label: 'Title',
            initialValue: 'Sample Product',
          ),
          price: context.knobs.double.slider(
            label: 'Price',
            initialValue: 29.99,
            min: 0,
            max: 1000,
          ),
        ),
      ),
      WidgetbookUseCase(
        name: 'Dark Theme',
        builder: (context) => ProductCard(
          title: 'Dark Theme Product',
          price: 49.99,
          isDarkMode: true,
        ),
      ),
    ],
  );
}

Examples

Basic Usage with AI Assistant

Human: List all widgets in my project

AI: I'll check your Widgetbook project for available widgets.

[Using widgetbook.list_widgets]

Found 3 widgets in the project:
- ProductCard: A card component for displaying product information
- UserProfile: User profile display component  
- NavigationButton: Reusable navigation button component

Human: Show me details about the ProductCard widget

AI: [Using widgetbook.get_widget_details with widget_name: "ProductCard"]

Widget Details for ProductCard:

Description: A card component for displaying product information
Properties: 4
Use Cases: 2

Properties:
- title (String): Sample Product
- price (double): 29.99
- imageUrl (String): https://example.com/image.jpg
- isDarkMode (bool): false

Use Cases:
- Default: Default product card configuration
- Dark Theme: Product card with dark theme styling

Human: Generate a new use case for ProductCard with title "Premium Product" and price 99.99

AI: [Using widgetbook.generate_use_case_code]

Generated use case code for ProductCard:

File: lib/widgetbooks/product_card.dart

Code:
```dart
WidgetbookUseCase(
  name: 'title_Premium Product_price_99.99',
  builder: (context) {
    final title = 'Premium Product';
    final price = 99.99;
    return ProductCard(
      title: title,
      price: price,
    );
  },
),

Advanced Workflows

Automated Testing

Human: Run tests for the ProductCard default use case

AI: [Using widgetbook.run_use_case_test]

Test Result for "Default" (Default):

Status: PASSED
Details: All tests passed successfully.

Visual Regression Testing

Human: Generate a screenshot of the ProductCard dark theme use case

AI: [Using widgetbook.generate_screenshot]

Screenshot generated for "Dark Theme" (Dark Theme):

File: .widgetbook/screenshots/ProductCard_Dark Theme.png
Image data length: 15847 characters (base64)

You can decode the base64 data to view the screenshot.

Development

Running Tests

# Run all tests
dart test

# Run specific test file
dart test test/unit/services/widgetbook_analyzer_test.dart

# Run integration tests
dart test test/integration/

Building

# Build executable
dart compile exe bin/widgetbook_mcp_server.dart -o widgetbook-mcp-server

# Build for different platforms
dart compile exe bin/widgetbook_mcp_server.dart -o widgetbook-mcp-server-linux
dart compile exe bin/widgetbook_mcp_server.dart -o widgetbook-mcp-server.exe

Debugging

Set the log level to get more detailed information:

widgetbook-mcp-server --log-level FINE --project-path ./example_project

Troubleshooting

Common Issues

"Project path does not exist"

Ensure the provided path exists and contains a Flutter project with pubspec.yaml.

"Not a valid Flutter project"

Verify that pubspec.yaml exists in the project root.

"Widget not found"

Check that the widget is properly defined in your Widgetbook files and uses WidgetbookComponent.

"Permission denied"

Ensure the server has read/write access to the project directory.

Performance Tips

1. Large Projects: For projects with many widgets, consider organizing Widgetbook files by feature
2. Screenshot Generation: Screenshots are saved to .widgetbook/screenshots/ to avoid regeneration

Logging

Enable detailed logging to debug issues:

# Maximum verbosity
widgetbook-mcp-server --log-level FINEST

# View specific operations
widgetbook-mcp-server --log-level FINE | grep "WidgetbookAnalyzer"

Development Setup

1. Clone the repository
2. Install dependencies: dart pub get
3. Run tests: dart test
4. Build: dart compile exe bin/widgetbook_mcp_server.dart

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

• Documentation: Docs
• Issues: GitHub Issues
• Discussions: GitHub Discussions