部件书_mcp服务器

Name: 部件书_mcp服务器
Author: Mastersam07

作者：Mastersam074 星标更新：2025-08-18

安装使用来源：spider==github.com

项目介绍

Widgetbook 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)：捕获用例的视觉快照

性能与安全

快速响应时间：所有操作的目标响应时间低于500毫秒
安全通信：MCP协议确保对项目文件的安全访问
直观的API：遵循MCP最佳实践的一致且逻辑的结构

安装

先决条件

Dart SDK 3.0.0 或更高版本
包含Widgetbook依赖的Flutter项目
Git（用于克隆仓库）

从pub.dev安装

// 待定

从源码安装

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": "用于显示产品信息的卡片组件"
  }
]

`widgetbook.get_widget_details`

获取特定小部件的详细信息。

参数：

widget_name（字符串，必需）：小部件的唯一名称

返回值：

{
  "name": "ProductCard",
  "description": "用于显示产品信息的卡片组件",
  "properties": [
    {
      "name": "title",
      "type": "String",
      "defaultValue": "产品标题"
    }
  ],
  "use_cases": [
    {
      "name": "default",
      "description": "默认的产品卡片",
      "fileName": "product_card.dart"
    }
  ]
}

`widgetbook.generate_use_case_code`

生成一个新的WidgetbookUseCase代码片段。

参数：

widget_name（字符串，必需）：小部件的名称
property_values（对象，必需）：属性名称到值的映射

返回值：

{
  "file_path": "lib/widgetbooks/product_card.dart",
  "generated_code": "WidgetbookUseCase(\n  name: 'dark_theme',\n  builder: (context) {\n    return ProductCard(\n      title: '暗色主题产品',\n    );\n  },\n),"
}

`widgetbook.generate_screenshot`

捕获特定用例的截图。

参数：

widget_name（字符串，必需）：小部件的名称
use_case_name（字符串，必需）：用例的名称

返回值：

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

资源

`widgetbook://project-info`

提供当前Widgetbook项目的相关信息。

`widgetbook://config`

返回当前服务器配置和功能。

示例Widgetbook文件

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: '标题',
            initialValue: '示例产品',
          ),
          price: context.knobs.double.slider(
            label: '价格',
            initialValue: 29.99,
            min: 0,
            max: 1000,
          ),
        ),
      ),
      WidgetbookUseCase(
        name: 'Dark Theme',
        builder: (context) => ProductCard(
          title: '暗色主题产品',
          price: 49.99,
          isDarkMode: true,
        ),
      ),
    ],
  );
}

示例

基本用法与AI助手

人类：列出我项目中的所有小部件

AI：我将检查您的Widgetbook项目以查找可用的小部件。

[使用widgetbook.list_widgets]

找到项目中的3个小部件：
- ProductCard：用于显示产品信息的卡片组件
- UserProfile：用户资料展示组件
- NavigationButton：可复用的导航按钮组件

人类：给我展示ProductCard小部件的详细信息

AI：[使用widgetbook.get_widget_details，widget_name: "ProductCard"]

ProductCard小部件的详细信息：

描述：用于显示产品信息的卡片组件
属性：4
用例：2

属性：
- title (String)：示例产品
- price (double)：29.99
- imageUrl (String)：https://example.com/image.jpg
- isDarkMode (bool)：false

用例：
- Default：默认的产品卡片配置
- Dark Theme：具有暗色主题样式的卡片

人类：为ProductCard生成一个新的用例，标题为“高级产品”，价格为99.99

AI：[使用widgetbook.generate_use_case_code]

为ProductCard生成的用例代码：

文件：lib/widgetbooks/product_card.dart

代码：
```dart
WidgetbookUseCase(
  name: 'title_高级产品_price_99.99',
  builder: (context) {
    final title = '高级产品';
    final price = 99.99;
    return ProductCard(
      title: title,
      price: price,
    );
  },
),

高级工作流程

自动测试

人类：运行ProductCard默认用例的测试

AI：[使用widgetbook.run_use_case_test]

“Default”（默认）用例的测试结果：

状态：通过
详情：所有测试均成功通过。

视觉回归测试

人类：生成ProductCard暗色主题用例的截图

AI：[使用widgetbook.generate_screenshot]

为“Dark Theme”（暗色主题）生成的截图：

文件：.widgetbook/screenshots/ProductCard_Dark Theme.png
图像数据长度：15847个字符（base64）

您可以解码base64数据以查看截图。

开发

运行测试

# 运行所有测试
dart test

# 运行特定测试文件
dart test test/unit/services/widgetbook_analyzer_test.dart

# 运行集成测试
dart test test/integration/

构建

# 构建可执行文件
dart compile exe bin/widgetbook_mcp_server.dart -o widgetbook-mcp-server

# 为不同平台构建
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

故障排除

常见问题

“项目路径不存在”

确保提供的路径存在并且包含一个包含pubspec.yaml的Flutter项目。

“不是有效的Flutter项目”

验证pubspec.yaml是否存在于项目根目录。

“未找到小部件”

检查小部件是否在Widgetbook文件中正确定义，并使用WidgetbookComponent。

“权限被拒绝”

确保服务器对项目目录具有读写权限。

性能提示

大型项目：对于拥有许多小部件的项目，考虑按特性组织Widgetbook文件
截图生成：截图保存在.widgetbook/screenshots/以避免重新生成

日志记录

启用详细日志以调试问题：

# 最大详细程度
widgetbook-mcp-server --log-level FINEST

# 查看特定操作
widgetbook-mcp-server --log-level FINE | grep "WidgetbookAnalyzer"

开发环境设置

克隆仓库
安装依赖项：dart pub get
运行测试：dart test
构建：dart compile exe bin/widgetbook_mcp_server.dart

许可证

此项目采用MIT许可证——详见LICENSE文件。

支持

文档：文档
问题：GitHub问题
讨论：GitHub讨论