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環境變量查看詳細日誌，幫助排查問題。