VA Design System Monitor

VA Design System Monitor

用于监控 VA Design System 组件状态、成熟度级别并生成实现示例的综合工具。**现在可直接从 VA 官方 Storybook 获取真实示例！**既可作为 npm 包使用，也可作为用于 AI 集成的 MCP（Model Context Protocol）服务使用。

✨ 主要功能

• 🎯 真实官方示例：直接从 VA 的 Storybook 仓库获取实际 HTML 示例
• 📊 组件状态监控：跟踪成熟度级别和使用建议
• 🔧 智能回退：官方示例不可用时生成智能示例
• 🚀 多种接口：CLI、编程 API 和 MCP 服务
• 🔒 可用于生产环境：针对 vets-website 和 va-application-template 基础设施构建
• 🌐 跨版本兼容：支持 Node 14.15.0+ 至 Node 22+

🚀 快速开始

选项 1：NPM 包（推荐）

全局安装以使用命令行：

# Install globally
npm install -g va-design-system-monitor

# Get real examples from VA Storybook
va-components examples va-radio
va-components examples va-button

# Check component status and properties  
va-components check va-modal
va-components props va-accordion
va-components list recommended

或在项目中本地安装：

# Install locally
npm install va-design-system-monitor

# Use with npx
npx va-components examples va-radio

# Or use programmatically
import { getOfficialExamples, checkComponent } from 'va-design-system-monitor';

// Get real examples from VA Storybook
const radioExamples = await getOfficialExamples('va-radio');
console.log(radioExamples.examples); // Real HTML from official stories!

选项 2：本地开发

克隆并使用便捷的 npm 脚本：

# Clone the repository
git clone <repository-url>
cd va-design-system-monitor

# Install dependencies  
npm install

# Quick setup for MCP (auto-configures Cursor & Claude Desktop)
npm run setup:npm        # For published package (recommended)
npm run setup:local      # For local development
npm run setup:manual     # Show manual config instructions

🎯 超简单 MCP 设置

自动设置（推荐）

# After cloning the repo, just run:
npm run setup:npm
# This auto-configures both Cursor and Claude Desktop!

手动配置 MCP

如果你更喜欢手动设置，请将以下内容添加到 MCP 配置中：

Cursor：

• macOS/Linux：~/.cursor/mcp.json
• Windows：%USERPROFILE%\.cursor\mcp.json（路径可能因安装方式而异）

{
  "servers": {
    "va-design-system-monitor": {
      "command": "npx",
      "args": ["-y", "va-design-system-monitor"],
      "env": {}
    }
  }
}

Claude Desktop：

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json
• Linux：~/.config/claude-desktop/config.json

macOS/Windows 格式：

{
  "mcpServers": {
    "va-design-system-monitor": {
      "command": "npx",
      "args": ["-y", "va-design-system-monitor"],
      "env": {}
    }
  }
}

Linux 格式：

{
  "mcp": {
    "servers": {
      "va-design-system-monitor": {
        "command": "npx",
        "args": ["-y", "va-design-system-monitor"],
        "env": {}
      }
    }
  }
}

⚡ 便捷的 NPM 脚本

设置与服务

npm run setup            # Auto-setup MCP (local development)
npm run setup:npm        # Auto-setup MCP (npm package)
npm run setup:manual     # Show manual setup instructions
npm run server           # Start MCP server
npm run mcp              # Alias for server

快速命令（无需参数！）

npm run quick:button     # Check + examples for va-button
npm run quick:alert      # Check + examples for va-alert  
npm run quick:modal      # Check + examples for va-modal

组件检查

npm run check            # Check any component (you provide name)
npm run check:button     # Check va-button specifically
npm run check:alert      # Check va-alert specifically
npm run check:modal      # Check va-modal specifically

获取示例

npm run examples         # Examples for any component
npm run examples:button  # va-button examples
npm run examples:alert   # va-alert examples

列表与报告

npm run list:recommended # List production-ready components
npm run list:caution     # List components needing caution
npm run report           # Full status report

开发

npm run dev              # Start server with file watching
npm run dev:watch        # Alias for dev
npm run dev:cli          # CLI with file watching

📋 CLI 命令

组件状态与信息

# Check component status and maturity
va-components check va-button

# Get all component properties/props
va-components props va-button

# Generate implementation examples
va-components examples va-button

# Validate multiple components
va-components validate va-button va-alert va-card

# Lint components for issues
va-components lint va-modal va-table

发现与报告

# List components by status
va-components list recommended
va-components list caution
va-components list stable

# Generate comprehensive report
va-components report
va-components report --json

JSON 输出

在任意命令中添加 --json 以便以编程方式使用：

va-components check va-button --json
va-components examples va-alert --json

🔧 编程 API

基本用法

import { 
  checkComponent, 
  validateComponents, 
  getComponentProperties,
  getComponentExamples 
} from 'va-design-system-monitor';

// Check a single component
const button = await checkComponent('va-button');
console.log(button.status); // 'STABLE'

// Get component properties
const props = await getComponentProperties('va-button');
console.log(props.properties); // Array of property objects

// Generate examples
const examples = await getComponentExamples('va-button');
console.log(examples.examples); // Array of implementation examples

// Validate multiple components
const results = await validateComponents(['va-button', 'va-alert']);
console.log(results.summary); // Validation summary

高级用法

import { VAComponentMonitor } from 'va-design-system-monitor';

const monitor = new VAComponentMonitor({
  cacheTimeout: 10 * 60 * 1000, // 10 minutes
  definitionsUrl: 'custom-url' // Optional custom URL
});

// Get all components
const components = await monitor.getComponents();

// Generate report
const report = await monitor.generateReport();

// Check production readiness
const isReady = await monitor.isProductionReady('va-button');

🤖 MCP 服务（AI 集成）

作为 MCP 服务运行时，可使用以下工具：

可用工具

• get_component_status - 获取组件的状态和成熟度
• getComponentProperties - 获取组件属性/props
• getComponentExamples - 生成实现示例
• list_recommended_components - 列出可用于生产环境的组件
• list_caution_components - 列出需要谨慎使用的组件
• get_components_by_status - 按状态筛选组件
• validate_components_in_code - 验证组件列表
• generate_component_report - 生成综合状态报告

AI 使用示例

向 AI 助手提问：

• “展示 va-button 的属性”
• “为 va-alert 组件生成示例”
• “哪些 VA 组件适合在生产环境中使用？”
• “验证这些组件：va-button、va-modal、va-card”

🎯 输出示例

组件状态

{
  "name": "Button",
  "tagName": "va-button", 
  "status": "STABLE",
  "maturityLevel": "deployed",
  "recommendation": "Safe for production use - actively deployed"
}

组件属性

{
  "component": {
    "name": "Button",
    "tagName": "va-button",
    "status": "STABLE"
  },
  "properties": [
    {
      "name": "text",
      "type": "string",
      "optional": true,
      "description": "The text displayed on the button"
    },
    {
      "name": "disabled",
      "type": "boolean", 
      "optional": true,
      "description": "If true, the click event will not fire"
    }
  ]
}

实现示例

{
  "component": {
    "name": "Button",
    "tagName": "va-button",
    "status": "STABLE"
  },
  "examples": [
    {
      "title": "Basic Usage",
      "description": "Simple example showing essential action functionality",
      "code": "<va-button text=\"Submit Application\"></va-button>",
      "framework": "HTML/Web Components"
    },
    {
      "title": "Accessibility Enhanced", 
      "description": "Example with enhanced screen reader support",
      "code": "<va-button text=\"Submit Application\" label=\"Submit your disability benefits application\"></va-button>",
      "framework": "HTML/Web Components"
    }
  ]
}

📦 安装与设置

全局安装

npm install -g va-design-system-monitor

项目本地安装

npm install va-design-system-monitor

MCP 服务设置

1. 克隆代码库：

   git clone <repository-url>
   cd va-design-system-monitor
   npm install
   

2. 在 Cursor 中配置 MCP：

   • macOS/Linux：~/.cursor/mcp.json
   • Windows：%USERPROFILE%\.cursor\mcp.json（位置可能因安装方式而异）

   {
     "servers": {
       "va-design-system-monitor": {
         "command": "npx",
         "args": ["-y", "va-design-system-monitor"],
         "env": {}
       }
     }
   }
   

3. 在 Claude Desktop 中配置 MCP：

   • macOS：~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows：%APPDATA%\Claude\claude_desktop_config.json
   • Linux：~/.config/claude-desktop/config.json

   macOS/Windows 格式：

   {
     "mcpServers": {
       "va-design-system-monitor": {
         "command": "npx",
         "args": ["-y", "va-design-system-monitor"],
         "env": {}
       }
     }
   }
   

   Linux 格式：

   {
     "mcp": {
       "servers": {
         "va-design-system-monitor": {
           "command": "npx",
           "args": ["-y", "va-design-system-monitor"],
           "env": {}
         }
       }
     }
   }
   

4. 测试连接：

   # Run the MCP server directly
   node bin/mcp-server.js
   

🔍 组件状态级别

• RECOMMENDED - 最佳实践，可用于生产环境
• STABLE - 可安全用于生产环境
• EXPERIMENTAL - 仅用于开发/测试
• AVAILABLE_WITH_ISSUES - 可用，但可能存在问题
• USE_WITH_CAUTION - 存在已知问题或仍在评估中

🛠 开发

# Clone and install
git clone <repository-url>
cd va-design-system-monitor
npm install

# Run CLI locally
node bin/cli.js check va-button

# Run MCP server locally  
node bin/mcp-server.js

# Run tests
npm test

🤝 贡献

我们欢迎 VA 开发者社区的贡献！无论您是在修复 bug、添加功能，还是改进文档，您的帮助都能让这款工具更好地服务所有人。

🚀 贡献者快速入门

# Fork the repository on GitHub, then:
git clone https://github.com/YOUR_USERNAME/va-design-system-monitor.git
cd va-design-system-monitor
npm install

# Create a feature branch
git checkout -b feature/your-feature-name

# Make your changes and test them
npm run test
npm run dev  # Test the CLI locally

# Commit your changes
git add .
git commit -m "feat: add your feature description"

# Push and create a pull request
git push origin feature/your-feature-name

📋 如何贡献

🐛 Bug 报告

• 使用 GitHub 问题跟踪器
• 提供复现步骤、预期行为和实际行为
• 添加相关系统信息（Node 版本、操作系统等）

✨ 功能请求

• 创建带有“enhancement”标签的问题
• 描述使用场景和预期功能
• 提供使用方式示例

🔧 代码贡献

• Fork 代码库并创建功能分支
• 遵循现有代码风格和约定
• 为新功能添加测试
• 根据需要更新文档
• 提交前确保所有测试均通过

🧪 开发工作流

# Run tests
npm test

# Start development server with file watching
npm run dev

# Test CLI commands locally
node bin/cli.js check va-button

# Test MCP server locally
node bin/mcp-server.js

# Build for production
npm run build

📝 代码风格

• 使用 TypeScript 确保类型安全
• 遵循 ESLint 配置
• 编写 清晰、明确的提交消息
• 为公共 API 添加 JSDoc 注释
• 为新功能添加 测试

🎯 我们需要帮助的领域

• 组件覆盖范围：支持更多 VA 组件
• 框架集成：React、Vue、Angular 示例
• 性能：改进缓存和优化
• 文档：提供更多示例和使用场景
• 测试：覆盖边缘情况并添加集成测试

🔒 安全

如果您发现安全漏洞，请通过电子邮件私下联系维护者进行报告，而不要公开创建问题。

📜 行为准则

本项目遵循 Contributor Covenant。请在所有交流中保持尊重和包容。

🏆 致谢

贡献者将在我们的 README 和发行说明中获得认可。感谢您帮助改进 VA 开发工具！

---

有疑问？ 欢迎创建问题或联系维护者。我们随时为您提供帮助！

📝 许可证

MIT 许可证 - 详情请参阅 LICENSE 文件。