JinDaGe - sketch-mcp-server MCP Details

article

README

🚀 Sketch MCP 服务器

Sketch MCP 服务器是一个基于模型上下文协议（MCP）的 Sketch 文件处理服务器，专为 AI 工具设计，可智能分析 Sketch 设计文件并生成代码。

🚀 快速开始

命令行启动

# 启动 MCP 服务器（标准输入输出模式）
sketch-mcp-server

# 或者使用 npx
npx sketch-mcp-server

AI 工具集成

此服务器适用于以下 AI 开发环境：

Trae AI：作为 Sketch 文件分析的 MCP 服务器。
Cursor：配置为从设计到代码工作流程的 MCP 工具。
Claude Desktop：用于 Sketch 文件处理和分析。

Trae AI 配置示例

在 Trae AI 中添加 MCP 服务器配置：

{
  "mcpServers": {
    "sketch-mcp-server": {
      "command": "npx",
      "args": ["sketch-mcp-server"]
    }
  }
}

✨ 主要特性

🎨 Sketch 文件分析：全面解析 Sketch 文件，提取节点、样式、层级结构和完整信息。
🚀 智能令牌优化：最多可减少 90% 的令牌消耗，显著降低 AI 调用成本。
🔍 智能查询系统：拥有 16 个专业工具，可高效发现和分析设计元素。
🎯 符号组件支持：具备完整的符号主组件和实例处理能力。
🖼️ 视觉渲染：将设计节点渲染为 SVG/PNG 图像，以便 AI 分析。
📊 详细统计分析：对文档和节点进行全面统计。
🔧 CLI 工具支持：支持直接使用 npx 调用，无需安装。

📦 安装指南

全局安装（推荐）

npm install -g sketch-mcp-server

使用 npx（无需安装）

npx sketch-mcp-server

本地项目安装

npm install sketch-mcp-server

💻 使用示例

基础用法

// 1. 加载 Sketch 文件
{
  "name": "loadSketchByPath",
  "arguments": {
    "path": "/path/to/design.sketch"
  }
}

// 2. 获取智能摘要（节省 80 - 90% 的令牌）
{
  "name": "getNodesSummary",
  "arguments": {
    "groupBy": "type",
    "includeStats": true,
    "maxSamples": 5
  }
}

// 3. 获取特定节点的详细信息
{
  "name": "getMultipleNodeInfo",
  "arguments": {
    "nodeIds": ["button-id", "text-id"]
  }
}

// 4. 将节点渲染为图像
{
  "name": "renderNodeAsBase64",
  "arguments": {
    "nodeId": "button-id",
    "format": "svg"
  }
}

高级用法

// 使用字段过滤减少数据量
{
  "name": "getDocumentStructure",
  "arguments": {
    "fields": ["id", "name", "type", "children"],
    "maxDepth": 3,
    "summaryMode": false
  }
}

// 按样式分组的智能摘要
{
  "name": "getNodesSummary",
  "arguments": {
    "groupBy": "style",
    "includeStats": true,
    "maxSamples": 3
  }
}

🛠️ 工具列表

📁 文件加载工具

| 工具名称 | 描述 | |-----------|-------------| | loadSketchByPath | 从文件系统加载 Sketch 文件 | | loadSketchByConfig | 从配置对象加载 Sketch 数据 |

📊 文档结构工具

| 工具名称 | 描述 | 优化特性 | |-----------|-------------|----------------------| | getDocumentStructure | 获取完整的文档层级结构 | 🚀 支持字段过滤和摘要模式 | | getPageStructure | 获取单页结构 | - | | listPages | 列出所有页面的基本信息 | - |

🎯 节点查询工具

| 工具名称 | 描述 | 令牌优化 | |-----------|-------------|-------------------| | getNodesSummary | 智能节点摘要 | 🔥 减少 80 - 90% 的令牌 | | listNodes | 列出节点（支持过滤） | - | | listNodesByPage | 按页面列出节点 | - | | findNodesByName | 按名称搜索节点 | - |

🔍 详细信息工具

| 工具名称 | 描述 | |-----------|-------------| | getNodeInfo | 获取单个节点的详细信息 | | getMultipleNodeInfo | 批量获取节点信息（最多 100 个） | | getNodePosition | 获取节点的位置信息 |

🔄 符号组件工具

| 工具名称 | 描述 | |-----------|-------------| | getSymbolMasters | 获取所有符号主组件 | | getSymbolInstances | 获取所有符号实例 | | getSymbolMasterBySymbolID | 通过符号 ID 查找主组件 | | getSymbolInstanceStyles | 获取实例样式（包括覆盖样式） |

🎨 可视化工具

| 工具名称 | 描述 | |-----------|-------------| | renderNodeAsBase64 | 将节点渲染为图像（SVG/PNG） |

💡 令牌优化策略

数据量对比

| 工具/模式 | 令牌减少 | 使用场景 | |-----------|----------------|----------| | getNodesSummary | 80 - 90% | 初始分析，了解整体结构 | | getDocumentStructure（摘要模式） | 70 - 85% | 快速查看文档结构 | | getDocumentStructure（字段过滤） | 30 - 50% | 结构分析 | | 完整模式 | 0% | 详细设计要求 |

🎯 工具选择指南

| 使用场景 | 推荐工具 | 令牌效率 | 描述 | |----------|------------------|------------------|-------------| | 了解整体结构 | getNodesSummary | ⭐⭐⭐⭐⭐ | 最有效的概述方法 | | 分析页面层级结构 | getDocumentStructure（过滤） | ⭐⭐⭐⭐ | 结构化的层级信息 | | 查找特定节点 | findNodesByName | ⭐⭐⭐ | 精确搜索 | | 获取详细信息 | getMultipleNodeInfo | ⭐⭐ | 批量检索 | | 处理符号组件 | getSymbolMasters | ⭐⭐⭐ | 基于组件的设计 | | 视觉确认 | renderNodeAsBase64 | ⭐⭐ | 直观查看效果 |

🔧 技术细节

环境要求

Node.js >= 16.0.0
npm 或 yarn

本地开发

# 克隆项目
git clone https://github.com/mater1996/sketch-mcp-server.git
cd sketch-mcp-server

# 安装依赖
npm install

# 构建项目
npm run build

# 运行测试
npm test

# 启动开发服务器
npm run start:mcp

可用脚本

npm run build          # 将 TypeScript 编译为 JavaScript
npm run test           # 运行测试套件
npm run test:coverage  # 运行测试并生成覆盖率报告
npm run start          # 启动 HTTP 服务器
npm run start:mcp      # 启动 MCP 标准输入输出服务器
npm run release        # 发布新版本
npm run release:dry    # 模拟发布过程

📚 详细文档

如需详细的 API 文档，请参考工具使用指南。

开发标准

使用 TypeScript 编写代码。
遵循现有的代码风格。
为新功能添加测试。
更新相关文档。

📄 许可证

本项目采用 MIT 许可证。

🤝 贡献

欢迎贡献代码！请随时提交 Pull Request。

📞 支持

如果您遇到任何问题或有疑问，请：

查看文档。
搜索现有的问题。
如有需要，创建新问题。

sketch-mcp-server