设计系统分析器
Node.js/TypeScript微服务，使用Playwright自动化从网站中提取设计系统，并为Cursor IDE集成提供MCP（模型上下文协议）接口。
特性
- 网站分析：自动从网站中提取设计标记（颜色、排版、间距、组件）
- 异步处理：提交分析请求并跟踪作业状态
- MCP集成：通过Cursor IDE的MCP协议查询设计系统
- CLI支持：用于触发分析的命令行界面
- Docker就绪：完全容器化，使用docker compose
快速开始
先决条件
- 已安装Docker和Docker Compose
- 至少4GB RAM可用于Docker容器
设置
- 克隆存储库：
git clone
cd design-system-mcp- 配置环境：
cp .env.example .env
# Edit .env and set your API keys- 构建和启动服务：
docker-compose up --build- 验证健康状况：
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": "Analysis job submitted successfully",
"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": "Unauthorized: Invalid or missing API key",
"code": "unauthorized"
}400错误请求：
{
"error": "Invalid request: site_name is required",
"code": "validation_error"
}404未找到：
{
"error": "Job not found",
"code": "not_found"
}500内部服务器错误：
{
"error": "Internal server error",
"code": "internal_error"
}MCP服务器配置
MCP（模型上下文协议）服务器允许Cursor IDE直接查询设计系统。默认情况下，服务器在端口3001上运行（可通过以下方式配置 MCP_PORT 环境变量）。
用于游标IDE（HTTP）
添加到您的Cursor IDE MCP配置中：
{
"mcpServers": {
"design-system-analyzer": {
"url": "http://localhost:3001",
"apiKey": "your-api-key-1"
}
}
}用于游标IDE（HTTPS）
对于使用HTTPS的远程服务器：
{
"mcpServers": {
"design-system-analyzer": {
"url": "https://your-server.com:3001",
"apiKey": "your-api-key-1"
}
}
}集 MCP_PROTOCOL=https 在你的 .env 文件和配置SSL证书。
用于Cursor IDE（SSH隧道）
- 建立SSH隧道：
ssh -L 3001:localhost:3001 user@remote-server- 配置Cursor IDE以使用本地stdio：
{
"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主机上的内容未被容器使用- 测试容器使用隔离
node_modules通过匿名Docker卷 - 这
api集装箱用途node_modules来自Docker镜像（仅限生产依赖） - 如果你有
node_modules在主机上，使用Docker时删除它是安全的
运行测试
测试在Docker容器中运行。测试基础设施包括：
test-server：在端口3002上提供测试夹具HTML页面test：运行剧作家E2E测试
# Start test infrastructure
docker-compose --profile test up -d redis api test-server
# All tests
docker-compose --profile test run --rm test npm test
# Unit tests only
docker-compose --profile test run --rm test npm run test:unit
# Integration tests
docker-compose --profile test run --rm test npm run test:integration
# E2E tests
docker-compose --profile test run --rm test npm run test:e2e看 快速入门指南-测试 有关测试服务的详细信息。
装订和格式化
# Lint
npm run lint
# Fix linting issues
npm run lint:fix
# Format code
npm run format文档
许可证
麻省理工学院