小工具MCP服务器
一个模型上下文协议（MCP）服务器，通过让AI助手直接访问您的设计系统中的创建、修改和测试UI组件，为Flutter Widgetbook开发提供动力。
> 这是实验性的，不应该在你的生产应用程序/设计系统中使用 > > 在制品
概述
Widgetbook MCP服务器弥合了AI助手和Flutter Widgetbook项目之间的差距，实现了强大的新工作流程，包括：
- 自动化UI文档：为小部件生成样板代码和用例
- 会话式UI原型设计：交互式、基于对话的UI设计和修改
- 自动化UI回归测试：UI组件的全面视觉测试
- 上下文感知代码生成：遵循现有设计系统模式的AI生成代码
特性
核心能力
- 小部件发现 (
widgetbook.list_widgets)：列出项目中所有可用的小部件 - 小部件检查 (
widgetbook.get_widget_details)：检索特定小部件的详细信息，包括属性和用例 - 用例管理 (
widgetbook.get_widget_use_cases)：获取小部件的所有现有用例 - 代码生成 (
widgetbook.generate_use_case_code)：生成新的WidgetbookUseCase代码片段 - 代码修改 (
widgetbook.modify_widget_use_case)：修改现有用例属性 - 测试 (
widgetbook.run_use_case_test)：执行特定用例的测试 - 屏幕截图生成 (
widgetbook.generate_screenshot)：捕获用例的可视化快照
性能与安全
- 快速响应时间：所有操作的目标响应时间低于500ms
- 安全通信：MCP协议确保对项目文件的安全访问
- 直观的API：遵循MCP最佳实践的一致、逻辑结构
安装
先决条件
- Dart SDK 3.0.0或更高版本
- 依赖Widgetbook的Flutter项目
- Git（用于克隆存储库）
从pub.dev安装
// TODO从源代码安装
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用法
MCP客户端配置
使用已编译的可执行文件
添加到MCP客户端配置（例如Cursor）：
{
"mcpServers": {
"widgetbook": {
"command": "path/to/compiled/widgetbook-mcp-server",
"args": ["--project-path", "/path/to/your/flutter/project"]
}
}
}直接来源
添加到MCP客户端配置（例如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参考
工具
widgetbook.list_widgets
列出Widgetbook项目中所有可用的小部件。
参数： 无
退货：
[
{
"name": "ProductCard",
"description": "A card component for displaying product information"
}
]widgetbook.get_widget_details
检索特定小部件的详细信息。
参数：
widget_name（string，必填）：小部件的唯一名称
退货：
{
"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
生成新的WidgetbookUseCase代码片段。
参数：
widget_name（string，必填）：小部件的名称property_values（object，必填）：属性名称到值的映射
退货：
{
"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
捕获特定用例的屏幕截图。
参数：
widget_name（string，必填）：小部件的名称use_case_name（string，必填）：用例的名称
退货：
{
"use_case_name": "dark_theme",
"image_data": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJ...",
"file_path": ".widgetbook/screenshots/ProductCard_dark_theme.png"
}资源
widgetbook://project-info
提供有关当前Widgetbook项目的信息。
widgetbook://config
返回当前服务器配置和功能。
小部件手册文件示例
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,
),
),
],
);
}例子
AI助手的基本用法
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 componentHuman: 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 stylingHuman: 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: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.
#### 视觉回归测试
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
### 调试
设置日志级别以获取更详细的信息：
widgetbook-mcp-server --log-level FINE --project-path ./example_project
## 故障排除
### 常见问题
#### “项目路径不存在”
确保提供的路径存在，并且包含一个Flutter项目 `pubspec.yaml`.
#### “不是有效的Flutter项目”
核实一下 `pubspec.yaml` 存在于项目根目录中。
#### “未找到小部件”
检查小部件是否在Widgetbook文件中正确定义并使用 `WidgetbookComponent`.
#### “权限被拒绝”
确保服务器具有对项目目录的读/写访问权限。
### 性能提示
1. **大型项目**：对于具有许多小部件的项目，考虑按功能组织Widgetbook文件
1. **屏幕截图生成**：屏幕截图保存到 `.widgetbook/screenshots/` 避免再生
### 日志记录
启用详细日志记录以调试问题：
Maximum verbosity
widgetbook-mcp-server --log-level FINEST
View specific operations
widgetbook-mcp-server --log-level FINE | grep "WidgetbookAnalyzer"
### 开发设置
1. 克隆存储库
1. 安装依赖项： `dart pub get`
1. 运行测试： `dart test`
1. 构建： `dart compile exe bin/widgetbook_mcp_server.dart`
## 许可证
此项目根据MIT许可证获得许可-请参阅 [许可证](LICENSE) 文件以获取详细信息。
## 支持
- **文档**: [文档](https://github.com/mastersam07/widgetbook_mcp_server)
- **问题**:
- **讨论**: