星战科技xingzhan.cloud
返回市场
设计系统MCP

设计系统MCP

作者：dobryakov8 星标更新：2025-11-15
安装使用来源：spider==github.com

项目介绍

设计系统分析器

一个使用Node.js/TypeScript微服务，通过Playwright自动化从网站中提取设计系统，并提供Cursor IDE集成的MCP（模型上下文协议）接口。

特性

  • 网站分析：自动从网站中提取设计令牌（颜色、字体、间距、组件）
  • 异步处理：提交分析请求并跟踪任务状态
  • MCP集成：通过MCP协议从Cursor IDE查询设计系统
  • CLI支持：命令行界面用于触发分析
  • Docker就绪：完全容器化，使用docker-compose

快速开始

先决条件

  • 已安装Docker和Docker Compose
  • 至少有4GB内存可用给Docker容器

设置

  1. 克隆仓库：
git clone <repository-url>
cd design-system-mcp
  1. 配置环境：
cp .env.example .env
# 编辑.env并设置您的API密钥
  1. 构建并启动服务：
docker-compose up --build
  1. 验证健康状况：
curl http://localhost:3000/health

使用方法

API端点

提交分析请求

提交一个网站进行分析。立即返回一个任务ID。

curl -X POST http://localhost:3000/analyze \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key" \
  -d '{
    "site_name": "example",
    "url": "https://example.com"
  }'

响应 (202 已接受)：

{
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "pending",
  "message": "分析任务已成功提交",
  "correlation_id": "550e8400-e29b-41d4-a716-446655440001"
}

检查任务状态

获取分析任务的当前状态。

curl http://localhost:3000/status/550e8400-e29b-41d4-a716-446655440000 \
  -H "X-API-Key: your-api-key"

响应 (200 OK - 正在进行)：

{
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "in-progress",
  "site_name": "example",
  "url": "https://example.com",
  "submitted_at": "2025-11-13T10:00:00Z",
  "started_at": "2025-11-13T10:00:05Z"
}

响应 (200 OK - 完成)：

{
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "completed",
  "site_name": "example",
  "url": "https://example.com",
  "submitted_at": "2025-11-13T10:00:00Z",
  "started_at": "2025-11-13T10:00:05Z",
  "completed_at": "2025-11-13T10:00:45Z",
  "result_location": "designs/example/design-system.json"
}

响应 (404 未找到)： 任务状态在完成时会立即被删除。如果收到404，表示任务已完成或失败。

健康检查

检查服务健康和队列状态。

curl http://localhost:3000/health

响应 (200 OK)：

{
  "status": "healthy",
  "service": "design-system-analyzer",
  "version": "1.0.0",
  "uptime_seconds": 3600,
  "queue_depth": 2,
  "active_jobs": 1,
  "max_concurrent_jobs": 5
}

使用CLI脚本

CLI脚本会自动处理任务提交和状态轮询：

./scripts/analyze.sh example https://example.com

或者将API密钥作为参数传递：

./scripts/analyze.sh example https://example.com your-api-key

错误响应

所有端点都返回标准错误响应：

401 未经授权：

{
  "error": "未经授权：无效或缺少API密钥",
  "code": "unauthorized"
}

400 不良请求：

{
  "error": "无效请求：site_name是必需的",
  "code": "validation_error"
}

404 未找到：

{
  "error": "任务未找到",
  "code": "not_found"
}

500 内部服务器错误：

{
  "error": "内部服务器错误",
  "code": "internal_error"
}

MCP服务器配置

MCP（模型上下文协议）服务器允许Cursor IDE直接查询设计系统。该服务器默认运行在3001端口（可通过MCP_PORT环境变量配置）。

对于Cursor IDE（HTTP）

添加到您的Cursor IDE MCP配置：

{
  "mcpServers": {
    "design-system-analyzer": {
      "url": "http://localhost:3001",
      "apiKey": "your-api-key-1"
    }
  }
}

对于Cursor IDE（HTTPS）

对于远程服务器使用HTTPS：

{
  "mcpServers": {
    "design-system-analyzer": {
      "url": "https://your-server.com:3001",
      "apiKey": "your-api-key-1"
    }
  }
}

在您的.env文件中设置MCP_PROTOCOL=https并配置SSL证书。

对于Cursor IDE（SSH隧道）

  1. 建立SSH隧道：
ssh -L 3001:localhost:3001 user@remote-server
  1. 配置Cursor IDE以使用本地标准I/O：
{
  "mcpServers": {
    "design-system-analyzer": {
      "command": "ssh",
      "args": ["user@remote-server", "cd /path/to/service && node dist/src/mcp/transport/stdio-transport.js"],
      "env": {
        "API_KEY": "your-api-key-1"
      }
    }
  }
}

故障排除

  • 连接被拒绝：验证MCP服务器是否在配置的端口上运行
  • 未经授权：检查您的API密钥是否与API_KEYS环境变量匹配
  • 超时：确保网络连接和防火墙规则允许访问MCP端口

参见快速入门指南以获取更多详细的配置示例。

开发

安装依赖

注意：对于基于Docker的开发，您不需要在主机上安装依赖项。所有依赖项都在容器中安装。

如果您想在没有Docker的情况下本地开发：

npm install

重要：

  • 主机上的node_modules不会被容器使用
  • 测试容器通过匿名Docker卷使用隔离的node_modules
  • api容器使用Docker镜像中的node_modules（仅生产依赖项）
  • 如果您在主机上有node_modules，在使用Docker时可以安全地删除它

运行测试

测试在Docker容器中运行。测试基础设施包括：

  • test-server：在3002端口上提供测试固定HTML页面
  • test：运行Playwright端到端测试
# 启动测试基础设施
docker-compose --profile test up -d redis api test-server

# 所有测试
docker-compose --profile test run --rm test npm test

# 单元测试
docker-compose --profile test run --rm test npm run test:unit

# 集成测试
docker-compose --profile test run --rm test npm run test:integration

# 端到端测试
docker-compose --profile test run --rm test npm run test:e2e

参见快速入门指南 - 测试以获取关于测试服务的详细信息。

代码检查和格式化

# 代码检查
npm run lint

# 修复代码检查问题
npm run lint:fix

# 格式化代码
npm run format

文档

许可证

MIT