Content
# Sketch MCP Server
**English** | [中文](./README.cn.md)
A Sketch file processing server based on Model Context Protocol (MCP), designed for AI tools to intelligently analyze Sketch design files and generate code.
## ✨ Core Features
- 🎨 **Sketch File Analysis**: Comprehensive parsing of Sketch files, extracting nodes, styles, hierarchies, and complete information
- 🚀 **Smart Token Optimization**: Up to 90% token consumption reduction, significantly lowering AI call costs
- 🔍 **Intelligent Query System**: 16 professional tools for efficient discovery and analysis of design elements
- 🎯 **Symbol Component Support**: Complete Symbol Master and Instance processing capabilities
- 🖼️ **Visual Rendering**: Render design nodes as SVG/PNG images for AI analysis
- 📊 **Detailed Statistical Analysis**: Comprehensive statistics for documents and nodes
- 🔧 **CLI Tool Support**: Support for direct npx calls without installation
## 📦 Installation
### Global Installation (Recommended)
```bash
npm install -g sketch-mcp-server
```
### Using npx (No Installation Required)
```bash
npx sketch-mcp-server
```
### Local Project Installation
```bash
npm install sketch-mcp-server
```
## 🚀 Quick Start
### Command Line Launch
```bash
# Start MCP server (stdio mode)
sketch-mcp-server
# Or use npx
npx sketch-mcp-server
```
### AI Tool Integration
This server is designed for the following AI development environments:
- **Trae AI**: As an MCP server for Sketch file analysis
- **Cursor**: Configure as MCP tool for design-to-code workflow
- **Claude Desktop**: For Sketch file processing and analysis
### Trae AI Configuration Example
Add MCP server configuration in Trae AI:
```json
{
"mcpServers": {
"sketch-mcp-server": {
"command": "npx",
"args": ["sketch-mcp-server"]
}
}
}
```
## 🛠️ Tool List
### 📁 File Loading Tools
| Tool Name | Description |
|-----------|-------------|
| `loadSketchByPath` | Load Sketch file from file system |
| `loadSketchByConfig` | Load Sketch data from configuration object |
### 📊 Document Structure Tools
| Tool Name | Description | Optimization Features |
|-----------|-------------|----------------------|
| `getDocumentStructure` | Get complete document hierarchy | 🚀 Supports field filtering and summary mode |
| `getPageStructure` | Get single page structure | - |
| `listPages` | List all page basic information | - |
### 🎯 Node Query Tools
| Tool Name | Description | Token Optimization |
|-----------|-------------|-------------------|
| `getNodesSummary` | **Smart Node Summary** | 🔥 80-90% Token Reduction |
| `listNodes` | List nodes (with filtering support) | - |
| `listNodesByPage` | List nodes by page | - |
| `findNodesByName` | Search nodes by name | - |
### 🔍 Detailed Information Tools
| Tool Name | Description |
|-----------|-------------|
| `getNodeInfo` | Get detailed information for single node |
| `getMultipleNodeInfo` | Batch get node information (up to 100) |
| `getNodePosition` | Get node position information |
### 🔄 Symbol Component Tools
| Tool Name | Description |
|-----------|-------------|
| `getSymbolMasters` | Get all Symbol Masters |
| `getSymbolInstances` | Get all Symbol Instances |
| `getSymbolMasterBySymbolID` | Find Master by Symbol ID |
| `getSymbolInstanceStyles` | Get instance styles (including override styles) |
### 🎨 Visualization Tools
| Tool Name | Description |
|-----------|-------------|
| `renderNodeAsBase64` | Render node as image (SVG/PNG) |
## 💡 Token Optimization Strategy
### Data Volume Comparison
| Tool/Mode | Token Reduction | Use Case |
|-----------|----------------|----------|
| `getNodesSummary` | 80-90% | Initial analysis, understanding overall structure |
| `getDocumentStructure` (summary mode) | 70-85% | Quick document structure overview |
| `getDocumentStructure` (field filtering) | 30-50% | Structural analysis |
| Full mode | 0% | Detailed design requirements |
### Recommended Workflow
1. **🔍 Quick Analysis**: Use `getNodesSummary` to understand overall design structure
2. **📋 Structure Analysis**: Use field-filtered `getDocumentStructure` to get hierarchical relationships
3. **🎯 Detailed Information**: Get detailed information for specific nodes as needed
4. **👁️ Visual Verification**: Render key components to confirm effects
## 📝 Usage Examples
### Basic Workflow
```javascript
// 1. Load Sketch file
{
"name": "loadSketchByPath",
"arguments": {
"path": "/path/to/design.sketch"
}
}
// 2. Get smart summary (save 80-90% tokens)
{
"name": "getNodesSummary",
"arguments": {
"groupBy": "type",
"includeStats": true,
"maxSamples": 5
}
}
// 3. Get detailed information for specific nodes
{
"name": "getMultipleNodeInfo",
"arguments": {
"nodeIds": ["button-id", "text-id"]
}
}
// 4. Render node as image
{
"name": "renderNodeAsBase64",
"arguments": {
"nodeId": "button-id",
"format": "svg"
}
}
```
### Advanced Optimization Examples
```javascript
// Use field filtering to reduce data volume
{
"name": "getDocumentStructure",
"arguments": {
"fields": ["id", "name", "type", "children"],
"maxDepth": 3,
"summaryMode": false
}
}
// Smart summary grouped by style
{
"name": "getNodesSummary",
"arguments": {
"groupBy": "style",
"includeStats": true,
"maxSamples": 3
}
}
```
## 🎯 Tool Selection Guide
| Use Case | Recommended Tool | Token Efficiency | Description |
|----------|------------------|------------------|-------------|
| Understanding overall structure | `getNodesSummary` | ⭐⭐⭐⭐⭐ | Most efficient overview method |
| Analyzing page hierarchy | `getDocumentStructure` (filtered) | ⭐⭐⭐⭐ | Structured hierarchical information |
| Finding specific nodes | `findNodesByName` | ⭐⭐⭐ | Precise search |
| Getting detailed information | `getMultipleNodeInfo` | ⭐⭐ | Batch retrieval |
| Handling Symbol components | `getSymbolMasters` | ⭐⭐⭐ | Component-based design |
| Visual confirmation | `renderNodeAsBase64` | ⭐⭐ | Intuitive effect viewing |
## 🔧 Development Guide
### Environment Requirements
- Node.js >= 16.0.0
- npm or yarn
### Local Development
```bash
# Clone project
git clone https://github.com/mater1996/sketch-mcp-server.git
cd sketch-mcp-server
# Install dependencies
npm install
# Build project
npm run build
# Run tests
npm test
# Start development server
npm run start:mcp
```
### Available Scripts
```bash
npm run build # Build TypeScript to JavaScript
npm run test # Run test suite
npm run test:coverage # Run tests and generate coverage report
npm run start # Start HTTP server
npm run start:mcp # Start MCP stdio server
npm run release # Release new version
npm run release:dry # Simulate release process
```
## 📚 API Reference
For detailed API documentation, please refer to [Tool Usage Guide](./mcp-prompt.en.txt).
### Development Standards
- Write code in TypeScript
- Follow existing code style
- Add tests for new features
- Update relevant documentation
## 📄 License
MIT License
## 🤝 Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
## 📞 Support
If you encounter any issues or have questions, please:
1. Check the [documentation](./mcp-prompt.en.txt)
2. Search existing [issues](https://github.com/mater1996/sketch-mcp-server/issues)
3. Create a new issue if needed
