# 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.

- **Type:** MCP server
- **Install:** `agentstack add mcp-mastersam07-widgetbook-mcp-server`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [Mastersam07](https://agentstack.voostack.com/s/mastersam07)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [Mastersam07](https://github.com/Mastersam07)
- **Source:** https://github.com/Mastersam07/widgetbook_mcp_server
- **Website:** https://github.com/mastersam07/widgetbook_mcp_server

## Install

```sh
agentstack add mcp-mastersam07-widgetbook-mcp-server
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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

```bash
// TODO
```

### Install from source

```bash
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):

```json
{
  "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):

```json
{
  "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:**
```json
[
  {
    "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:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "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

```dart
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

```bash
# 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

```bash
# 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:

```bash
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
3. **Screenshot Generation**: Screenshots are saved to `.widgetbook/screenshots/` to avoid regeneration

### Logging

Enable detailed logging to debug issues:

```bash
# 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](LICENSE) file for details.

## Support

- **Documentation**: [Docs](https://github.com/mastersam07/widgetbook_mcp_server)
- **Issues**: [GitHub Issues](https://github.com/mastersam07/widgetbook_mcp_server/issues)
- **Discussions**: [GitHub Discussions](https://github.com/mastersam07/widgetbook_mcp_server/discussions)

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [Mastersam07](https://github.com/Mastersam07)
- **Source:** [Mastersam07/widgetbook_mcp_server](https://github.com/Mastersam07/widgetbook_mcp_server)
- **License:** MIT
- **Homepage:** https://github.com/mastersam07/widgetbook_mcp_server

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-mastersam07-widgetbook-mcp-server
- Seller: https://agentstack.voostack.com/s/mastersam07
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.