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
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
- 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
- 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
- Dart SDK 3.0.0 or higher
- Flutter project with Widgetbook dependency
- Git (for cloning the repository)
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
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"]
}
}
}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",
]
}
}
}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 widgetproperty_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 widgetuse_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"
}widgetbook://project-info
Provides information about the current Widgetbook project.
Returns the current server configuration and capabilities.
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,
),
),
],
);
}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,
);
},
),
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.
# 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/
# 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
Set the log level to get more detailed information:
widgetbook-mcp-server --log-level FINE --project-path ./example_project
"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.
Check that the widget is properly defined in your Widgetbook files and uses WidgetbookComponent.
Ensure the server has read/write access to the project directory.
- Large Projects: For projects with many widgets, consider organizing Widgetbook files by feature
- Screenshot Generation: Screenshots are saved to
.widgetbook/screenshots/ to avoid regeneration
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"
- Clone the repository
- Install dependencies:
dart pub get
- Run tests:
dart test
- Build:
dart compile exe bin/widgetbook_mcp_server.dart
This project is licensed under the MIT License - see the LICENSE file for details.
Комментарии
Комментариев пока нет. Будьте первым.