Sketch Context MCP

🚀 Sketch Context MCP

Sketch Context MCP是一个模型上下文协议（MCP）服务器，用于将Sketch设计与Cursor、Cline或Windsurf等集成开发环境（IDE）集成。它允许IDE访问和解释Sketch设计文件，实现由人工智能驱动的从设计到代码的工作流程。

🚀 快速开始

前提条件

• Node.js（v14 或更高版本）
• Sketch（v70 或更高版本）
• Cursor IDE、VS Code 或类似软件
• 一个Sketch账户（本地）或使用API访问（Sketch Cloud文件）

安装

# 全局安装
npm install -g sketch-context-mcp

# 使用本地Sketch文件运行
sketch-context-mcp --local-file=/path/to/your/file.sketch

# 使用Sketch Cloud访问运行
sketch-context-mcp --sketch-api-key=<your-sketch-api-key>

或者直接使用npx运行：

npx sketch-context-mcp --local-file=/path/to/your/file.sketch

安装Sketch插件

1. 从发布页面下载最新版本的插件。
2. 双击.sketchplugin文件，将其安装到Sketch中。
3. 该插件将在Sketch的“插件”>“Sketch Context MCP”中可用。

与Cursor集成

要在Cursor中使用此工具，请按以下步骤操作：

1. 使用Sketch文件启动MCP服务器：

   sketch-context-mcp --local-file=/path/to/your/file.sketch
   

2. 在Sketch中打开插件：
   • 转到“插件”>“Sketch Context MCP”>“打开MCP界面”。
   • 输入服务器端口（默认：3333）。
   • 点击“连接”。
3. 在Cursor中连接到MCP服务器：
   • 转到“设置”>“功能”>“上下文”。
   • 添加一个新的MCP服务器，URL为：http://localhost:3333/sse。
   • 点击“连接”。
4. 在Cursor编辑器中，你现在可以：
   • 通过ID引用组件：“显示ID为12345的组件”。
   • 列出所有组件：“列出设计中的所有组件”。
   • 获取特定元素的详细信息：“描述标题中的按钮”。
   • 创建新元素：“创建一个宽度为200、高度为100的矩形”。

✨ 主要特性

• 支持解析本地和云端的Sketch文件。
• 能够提取组件/符号。
• 支持资产管理和自动下载。
• 通过Sketch插件支持选择链接。
• 通过WebSocket和SSE实现实时更新。
• 提供用于将Sketch连接到Cursor的交互式用户界面。
• 可以解析本地和Sketch Cloud托管的文件。
• 能够提取文档结构和组件信息。
• 可以通过ID访问特定节点。
• 列出Sketch文件中的所有组件。
• 可以通过Cursor的命令创建矩形、文本和其他元素。

📦 安装指南

安装依赖

• Node.js（v14 或更高版本）
• Sketch（v70 或更高版本）
• Cursor IDE、VS Code 或类似软件
• 一个Sketch账户（本地）或使用API访问（Sketch Cloud文件）

安装命令

# 全局安装
npm install -g sketch-context-mcp

# 使用本地Sketch文件运行
sketch-context-mcp --local-file=/path/to/your/file.sketch

# 使用Sketch Cloud访问运行
sketch-context-mcp --sketch-api-key=<your-sketch-api-key>

或者直接使用npx运行：

npx sketch-context-mcp --local-file=/path/to/your/file.sketch

安装Sketch插件

1. 从发布页面下载最新版本的插件。
2. 双击.sketchplugin文件，将其安装到Sketch中。
3. 该插件将在Sketch的“插件”>“Sketch Context MCP”中可用。

💻 使用示例

基础用法

在Cursor中使用Sketch Context MCP的基础操作示例：

# 启动MCP服务器
sketch-context-mcp --local-file=/path/to/your/file.sketch

在Sketch中连接到服务器，然后在Cursor中连接到MCP服务器，即可开始使用。

高级用法

在Cursor中使用自然语言命令创建和修改设计元素：

# 创建一个宽度为300、高度为200的蓝色矩形
"Create a blue rectangle with width 300 and height 200"

# 添加一个内容为 'Hello World' 的文本层
"Add a text layer with the content 'Hello World'"

📚 详细文档

组件

本项目由两个主要组件组成：

1. MCP服务器：一个Node.js服务器，实现了模型上下文协议，用于向Cursor IDE提供Sketch文件数据。
2. Sketch插件：一个带有用户界面的Sketch插件，通过WebSocket与MCP服务器进行通信。

可用的MCP工具

服务器为Cursor提供了以下工具：

• get_file：检索Sketch文件或其中特定节点的内容。
• list_components：列出Sketch文件中的所有组件/符号。
• get_selection：获取当前所选元素的信息。
• create_rectangle：创建具有指定尺寸和属性的新矩形。
• create_text：创建具有自定义内容和样式的新文本元素。

这些工具使Cursor能够：

• 访问和检查Sketch设计文件。
• 查询特定的组件和图层。
• 通过自然语言命令创建和修改设计元素。
• 与Sketch保持实时同步。

支持的功能

• 本地和云端Sketch文件解析
• 组件/符号提取
• 资产管理和自动下载
• 通过Sketch插件支持选择链接
• 通过WebSocket和SSE实现实时更新
• 用于将Sketch连接到Cursor的交互式用户界面
• 解析本地和Sketch Cloud托管的文件
• 提取文档结构和组件信息
• 通过ID访问特定节点
• 列出Sketch文件中的所有组件
• 通过Cursor的命令创建矩形、文本和其他元素

配置

服务器可以使用环境变量（通过.env文件）或命令行参数进行配置。命令行参数优先于环境变量。

环境变量

• SKETCH_API_KEY：你的Sketch API访问令牌（访问Sketch Cloud文件必需）
• PORT：服务器运行的端口（默认：3333）
• LOCAL_SKETCH_PATH：本地Sketch文件的路径（替代--local-file参数）
• DEBUG_LEVEL：设置日志详细程度（默认：'info'）

命令行参数

• --version：显示版本号
• --sketch-api-key：你的Sketch API访问令牌
• --port：服务器运行的端口
• --stdio：以命令模式运行服务器，而不是默认的HTTP/SSE模式
• --help：显示帮助菜单

使用Sketch插件

连接选项卡

连接选项卡允许你连接到Sketch Context MCP服务器：

1. 输入端口号（默认是3333）。
2. 点击“连接”以建立WebSocket连接。
3. 连接成功后，你将看到带有通道ID的确认消息。
4. 按照说明将Cursor连接到服务器。

选择选项卡

选择选项卡显示Sketch文档中所选图层的信息：

1. 在Sketch文档中选择一个或多个图层。
2. 所选图层将显示在列表中。
3. 点击“复制选择ID”将图层ID复制到剪贴板。
4. 在Cursor中使用这些ID引用特定图层。

关于选项卡

关于选项卡提供了有关插件的信息以及如何使用它的说明。

与Cursor一起使用

一旦Sketch和Cursor都连接到MCP服务器：

1. 在Sketch中选择元素。
2. 使用Sketch Context MCP插件复制它们的ID。
3. 在Cursor中通过ID引用这些元素。

故障排除

常见问题

• 连接错误：确保你的服务器正在运行，并且端口可以访问。
• 身份验证失败：验证你的Sketch API密钥是否正确。
• 文件解析问题：确保你的Sketch文件有效且未损坏。
• WebSocket连接失败：确保端口未被防火墙阻止。

日志

要启用详细日志记录，请设置DEBUG环境变量：

DEBUG=sketch-mcp:* npx sketch-context-mcp

🔧 技术细节

获取Sketch API密钥

Sketch API密钥是访问Sketch Cloud托管文件所需的OAuth访问令牌。按照以下步骤获取和使用该令牌：

步骤1：使用Sketch Cloud进行身份验证

使用你的Sketch Cloud凭证（电子邮件和密码），通过向身份验证端点发出POST请求来生成访问令牌：

curl -X "POST" "https://auth.sketch.cloud/oauth/token" \
  -H 'Content-Type: application/json' \
  -d '{
    "email": "YOUR_EMAIL",
    "password": "YOUR_PASSWORD",
    "grant_type": "password"
  }'

将YOUR_EMAIL和YOUR_PASSWORD替换为你的Sketch Cloud账户凭证。

步骤2：访问令牌

响应将包含一个access_token。此令牌用作你访问Sketch Cloud托管文件的API密钥。

步骤3：使用令牌

为了安全起见，建议将令牌作为环境变量传递：

export SKETCH_API_KEY=<your-access-token>

或者将其作为命令行参数包含：

sketch-context-mcp --sketch-api-key=<your-access-token>

步骤4：刷新令牌

如果你的令牌过期，请使用初始响应中提供的refresh_token获取新的访问令牌。

安全最佳实践

为确保你的API密钥安全，请遵循以下准则：

• 不要硬编码密钥：永远不要将API密钥硬编码到应用程序或源代码中。而是使用环境变量或秘密管理工具。
• 在本地开发中使用.env文件：将你的API密钥存储在.env文件中，并使用dotenv等库加载它：

  SKETCH_API_KEY=<your-access-token>
  

  确保将.env文件添加到.gitignore中，以避免意外暴露。
• 定期轮换令牌：如果你的令牌泄露或被泄露，请立即撤销它并生成一个新的令牌。
• 监控和审计：使用工具扫描你的存储库以查找暴露的凭证（例如，GitHub的秘密扫描功能）。
• 使用短期令牌：如果可能，使用短期令牌并根据需要刷新它们，以最大限度地减少令牌泄露的影响。

在Sketch-Context-MCP中的工作原理

Sketch API密钥是访问Sketch Cloud托管文件所必需的。服务器使用此密钥对Sketch Cloud的请求进行身份验证，并检索必要的设计数据。在进行API请求时，密钥通过Authorization头安全地传递。

📄 许可证

本项目采用MIT许可证 - 有关详细信息，请参阅LICENSE文件。

⚠️ 重要提示

本项目目前处于测试阶段，可能不完全稳定。

💡 使用建议

• 确保你的Node.js和Sketch版本符合要求，以避免兼容性问题。
• 在使用Sketch Cloud文件时，妥善保管好你的API密钥，遵循安全最佳实践。
• 如果遇到问题，可以通过设置DEBUG环境变量查看详细日志，帮助排查问题。