{"_id":"@yhy2001/figma-mcp-server","_rev":"3-9090d02785111f08089970f0f435495a","name":"@yhy2001/figma-mcp-server","dist-tags":{"latest":"1.1.0"},"versions":{"1.0.0":{"name":"@yhy2001/figma-mcp-server","version":"1.0.0","keywords":["figma","mcp","typescript","ai","design"],"author":"","license":"MIT","_id":"@yhy2001/figma-mcp-server@1.0.0","maintainers":[{"name":"yhy2001","email":"a319139806@163.com"}],"homepage":"https://github.com/1yhy/figma-mcp-server#readme","bugs":{"url":"https://github.com/1yhy/figma-mcp-server/issues"},"bin":{"figma-mcp":"dist/index.js"},"dist":{"shasum":"fd370e6fc1edadaed7e12db150933071e95399a9","tarball":"https://registry.npmjs.org/@yhy2001/figma-mcp-server/-/figma-mcp-server-1.0.0.tgz","fileCount":4,"integrity":"sha512-qHFpHMIOiB+7DF9pvzMhtd+mEC+UXLtKnt+WkQNqlvB8gbY4t7LOpAErcYSjcVhLtyu0OxuJgOPDbogjCk4xnQ==","signatures":[{"sig":"MEUCIQDfPdW57NAYnp/7e8SsnKCsWFmSn0nZG0jcYLIHAu61XgIgEducapVHK3CPIf6t8fyo5pCFkVSheFmF2TVlIk76Yps=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":33642},"main":"dist/index.js","type":"module","engines":{"node":">=18.0.0"},"gitHead":"8ec61bad285a0acadfc5113ebc290e30dab6a51d","scripts":{"dev":"cross-env NODE_ENV=development tsup --watch","lint":"eslint . --ext .ts","build":"tsup","start":"node dist/index.js","format":"prettier --write \"src/**/*.ts\"","dev:cli":"cross-env NODE_ENV=development tsup --watch -- --stdio","inspect":"pnpx @modelcontextprotocol/inspector","mcp-test":"pnpm start -- --stdio","start:cli":"cross-env NODE_ENV=cli node dist/index.js","start:http":"node dist/index.js","test:figma":"tsx test-figma-data.ts","type-check":"tsc --noEmit","pub:release":"pnpm build && npm publish --access public","publish:local":"pnpm build && npm pack","prepublishOnly":"npm run build"},"_npmUser":{"name":"yhy2001","email":"a319139806@163.com"},"repository":{"url":"git+https://github.com/1yhy/figma-mcp-server.git","type":"git"},"_npmVersion":"10.8.2","description":"本地MCP服务器，用于Figma设计与AI编码工具集成","directories":{},"_nodeVersion":"20.18.1","dependencies":{"zod":"^3.24.2","yargs":"^17.7.2","dotenv":"^16.4.7","remeda":"^2.20.1","express":"^4.21.2","cross-env":"^7.0.3","@types/yargs":"^17.0.33","@modelcontextprotocol/sdk":"^1.6.1"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.19.2","jest":"^29.7.0","tsup":"^8.4.0","eslint":"^9.20.1","ts-jest":"^29.2.5","prettier":"^3.5.0","typescript":"^5.7.3","@types/jest":"^29.5.11","@types/node":"^20.17.0","@types/express":"^5.0.0","@figma/rest-api-spec":"^0.24.0","eslint-config-prettier":"^10.0.1","@typescript-eslint/parser":"^8.24.0","@typescript-eslint/eslint-plugin":"^8.24.0"},"_npmOperationalInternal":{"tmp":"tmp/figma-mcp-server_1.0.0_1742706154074_0.620893117687068","host":"s3://npm-registry-packages-npm-production"}},"1.0.1":{"name":"@yhy2001/figma-mcp-server","version":"1.0.1","keywords":["figma","mcp","typescript","ai","design"],"author":"","license":"MIT","_id":"@yhy2001/figma-mcp-server@1.0.1","maintainers":[{"name":"yhy2001","email":"a319139806@163.com"}],"homepage":"https://github.com/1yhy/figma-mcp-server#readme","bugs":{"url":"https://github.com/1yhy/figma-mcp-server/issues"},"bin":{"figma-mcp":"dist/index.js"},"dist":{"shasum":"6ed10e5ecb7b182ad8d9e8b42bf4a9fd5a726fc3","tarball":"https://registry.npmjs.org/@yhy2001/figma-mcp-server/-/figma-mcp-server-1.0.1.tgz","fileCount":5,"integrity":"sha512-hr0c4trPOrkiVCvkdYEiSl2J/V+Lv6TXy0p66AgVLxSOfnvWXmNkiH1naZyRSUVMSXJ4gnKxJerBT/pKN4bFMA==","signatures":[{"sig":"MEUCIGrxmMy2DsygBPDl+oiesnPwSRPLlZdu78MmzVCkVKDQAiEAn3b8kfA1MxHv7DeDqFsdckd6bcKyrVMspBeu1hu5TX0=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":43172},"main":"dist/index.js","type":"module","engines":{"node":">=18.0.0"},"gitHead":"c07b72273dded59e302a74ec54e4f2638b16f1be","scripts":{"dev":"cross-env NODE_ENV=development tsup --watch","lint":"eslint . --ext .ts","build":"tsup","start":"node dist/index.js","format":"prettier --write \"src/**/*.ts\"","dev:cli":"cross-env NODE_ENV=development tsup --watch -- --stdio","inspect":"pnpx @modelcontextprotocol/inspector","mcp-test":"pnpm start -- --stdio","start:cli":"cross-env NODE_ENV=cli node dist/index.js","start:http":"node dist/index.js","test:figma":"tsx test-figma-data.ts","type-check":"tsc --noEmit","pub:release":"pnpm build && npm publish --access public","publish:local":"pnpm build && npm pack","prepublishOnly":"npm run build"},"_npmUser":{"name":"yhy2001","email":"a319139806@163.com"},"repository":{"url":"git+https://github.com/1yhy/figma-mcp-server.git","type":"git"},"_npmVersion":"10.8.2","description":"本地MCP服务器，用于Figma设计与AI编码工具集成","directories":{},"_nodeVersion":"20.18.1","dependencies":{"zod":"^3.24.2","yargs":"^17.7.2","dotenv":"^16.4.7","remeda":"^2.20.1","express":"^4.21.2","cross-env":"^7.0.3","@types/yargs":"^17.0.33","@modelcontextprotocol/sdk":"^1.6.1"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.19.2","jest":"^29.7.0","tsup":"^8.4.0","eslint":"^9.20.1","ts-jest":"^29.2.5","prettier":"^3.5.0","typescript":"^5.7.3","@types/jest":"^29.5.11","@types/node":"^20.17.0","@types/express":"^5.0.0","@figma/rest-api-spec":"^0.24.0","eslint-config-prettier":"^10.0.1","@typescript-eslint/parser":"^8.24.0","@typescript-eslint/eslint-plugin":"^8.24.0"},"_npmOperationalInternal":{"tmp":"tmp/figma-mcp-server_1.0.1_1742918664073_0.3424942278802001","host":"s3://npm-registry-packages-npm-production"}},"1.1.0":{"name":"@yhy2001/figma-mcp-server","version":"1.1.0","description":"MCP server for Figma design integration with AI coding tools","type":"module","main":"dist/index.js","bin":{"figma-mcp":"dist/index.js"},"scripts":{"dev":"cross-env NODE_ENV=development tsup --watch","build":"tsup","start":"node dist/index.js","start:cli":"cross-env NODE_ENV=cli node dist/index.js","start:http":"node dist/index.js","dev:cli":"cross-env NODE_ENV=development tsup --watch -- --stdio","type-check":"tsc --noEmit","lint":"eslint src/","lint:fix":"eslint src/ --fix","format":"prettier --write \"src/**/*.ts\" \"tests/**/*.ts\"","format:check":"prettier --check \"src/**/*.ts\"","test":"vitest run","test:watch":"vitest","test:coverage":"vitest run --coverage","test:ui":"vitest --ui","test:unit":"vitest run tests/unit","test:integration":"vitest run tests/integration","preview":"tsx tests/utils/preview.ts","inspect":"pnpx @modelcontextprotocol/inspector","mcp-test":"pnpm start -- --stdio","prepublishOnly":"pnpm type-check && pnpm lint && pnpm test && pnpm build","pub:release":"pnpm build && npm publish --access public","publish:local":"pnpm build && npm pack","prepare":"husky || true"},"engines":{"node":">=18.0.0"},"repository":{"type":"git","url":"git+https://github.com/1yhy/Figma-Context-MCP.git"},"homepage":"https://github.com/1yhy/Figma-Context-MCP#readme","bugs":{"url":"https://github.com/1yhy/Figma-Context-MCP/issues"},"keywords":["figma","mcp","model-context-protocol","typescript","ai","design","cursor","windsurf","cline","design-to-code"],"author":{"name":"1yhy"},"license":"MIT","dependencies":{"@modelcontextprotocol/sdk":"^1.24.3","cross-env":"^7.0.3","dotenv":"^16.4.7","express":"^4.21.2","remeda":"^2.20.1","yargs":"^17.7.2","zod":"^4.1.13"},"devDependencies":{"@commitlint/cli":"^20.2.0","@commitlint/config-conventional":"^19.0.0","@eslint/js":"^9.39.1","@figma/rest-api-spec":"^0.24.0","@types/express":"^5.0.0","@types/node":"^24.10.1","@types/yargs":"^17.0.33","@typescript-eslint/eslint-plugin":"^8.48.1","@typescript-eslint/parser":"^8.48.1","@vitest/coverage-v8":"^4.0.15","eslint":"^9.39.1","eslint-config-prettier":"^10.0.1","husky":"^9.0.0","lint-staged":"^15.0.0","prettier":"^3.5.0","tsup":"^8.5.1","tsx":"^4.21.0","typescript":"^5.7.3","typescript-eslint":"^8.48.1","vitest":"^4.0.15"},"_id":"@yhy2001/figma-mcp-server@1.1.0","gitHead":"d0c30e2dee55e20aa7f78643b93cfd4088cd46bb","_nodeVersion":"20.19.5","_npmVersion":"10.8.2","dist":{"integrity":"sha512-+f+t+aFZjrpkhIAR4RzJYcAXyvUHzyMZBmtZIxgwwuVRMOqSYcjw0JKwED4S14VonkLYa39sd51EKxIZWV6+JQ==","shasum":"2bb907115969c5ca5a0edab4170e9678287c452e","tarball":"https://registry.npmjs.org/@yhy2001/figma-mcp-server/-/figma-mcp-server-1.1.0.tgz","fileCount":5,"unpackedSize":131968,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIEE/hfbxHFvsKstTS9LaEc4wVmjw4NYEiSg8XW1b088TAiEA9inofm3ebrweJGNFp/X1XNNGhpvBliSIC5jeaBDhJOU="}]},"_npmUser":{"name":"yhy2001","email":"a319139806@163.com"},"directories":{},"maintainers":[{"name":"yhy2001","email":"a319139806@163.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/figma-mcp-server_1.1.0_1764993538282_0.6811385821725904"},"_hasShrinkwrap":false}},"time":{"created":"2025-03-23T05:02:34.008Z","modified":"2025-12-06T03:58:58.619Z","1.0.0":"2025-03-23T05:02:34.381Z","1.0.1":"2025-03-25T16:04:24.264Z","1.1.0":"2025-12-06T03:58:58.417Z"},"bugs":{"url":"https://github.com/1yhy/Figma-Context-MCP/issues"},"license":"MIT","homepage":"https://github.com/1yhy/Figma-Context-MCP#readme","keywords":["figma","mcp","model-context-protocol","typescript","ai","design","cursor","windsurf","cline","design-to-code"],"repository":{"type":"git","url":"git+https://github.com/1yhy/Figma-Context-MCP.git"},"description":"MCP server for Figma design integration with AI coding tools","maintainers":[{"name":"yhy2001","email":"a319139806@163.com"}],"readme":"<h1 align=\"center\">\n  <br>\n  <img src=\"https://upload.wikimedia.org/wikipedia/commons/3/33/Figma-logo.svg\" alt=\"Figma MCP\" width=\"80\">\n  <br>\n  Figma Context MCP\n  <br>\n</h1>\n\n<p align=\"center\">\n  <strong>用于 AI 编码工具与 Figma 设计无缝集成的 MCP 服务器</strong>\n</p>\n\n<p align=\"center\">\n  <a href=\"https://smithery.ai/server/@1yhy/Figma-Context-MCP\">\n    <img src=\"https://smithery.ai/badge/@1yhy/Figma-Context-MCP\" alt=\"Smithery Badge\">\n  </a>\n  <a href=\"https://www.npmjs.com/package/@yhy2001/figma-mcp-server\">\n    <img src=\"https://img.shields.io/npm/v/@yhy2001/figma-mcp-server\" alt=\"npm version\">\n  </a>\n  <a href=\"https://github.com/1yhy/Figma-Context-MCP/blob/main/LICENSE\">\n    <img src=\"https://img.shields.io/github/license/1yhy/Figma-Context-MCP\" alt=\"License\">\n  </a>\n  <a href=\"https://github.com/1yhy/Figma-Context-MCP/stargazers\">\n    <img src=\"https://img.shields.io/github/stars/1yhy/Figma-Context-MCP\" alt=\"Stars\">\n  </a>\n  <img src=\"https://img.shields.io/badge/TypeScript-5.7-blue?logo=typescript\" alt=\"TypeScript\">\n  <img src=\"https://img.shields.io/badge/MCP-1.24-green\" alt=\"MCP SDK\">\n</p>\n\n<p align=\"center\">\n  <a href=\"#功能特性\">功能特性</a> •\n  <a href=\"#快速开始\">快速开始</a> •\n  <a href=\"#mcp-能力\">MCP 能力</a> •\n  <a href=\"#架构\">架构</a> •\n  <a href=\"#文档\">文档</a> •\n  <a href=\"./README.md\">English</a>\n</p>\n\n---\n\n## 这是什么？\n\nFigma Context MCP 是一个 [模型上下文协议 (MCP)](https://modelcontextprotocol.io/) 服务器，用于连接 Figma 设计与 AI 编码助手，如 [Cursor](https://cursor.sh/)、[Windsurf](https://codeium.com/windsurf) 和 [Cline](https://cline.bot/)。\n\n当 AI 工具能够直接访问 Figma 设计数据时，它们能够一次性生成更准确的代码——效果远超使用截图。\n\n> **说明**：本项目基于 [Figma-Context-MCP](https://github.com/GLips/Figma-Context-MCP) 改进，优化了数据结构和智能布局检测算法。\n\n## 功能特性\n\n### 核心能力\n\n| 能力                 | 描述                                       |\n| -------------------- | ------------------------------------------ |\n| **智能布局检测**     | 从绝对定位自动推断 Flexbox/Grid 布局       |\n| **图标合并**         | 智能合并矢量图层为单个可导出图标           |\n| **CSS 生成**         | 将 Figma 样式转换为干净可用的 CSS          |\n| **图片导出**         | 下载带有正确命名的图片和图标               |\n| **多层缓存**         | L1 内存 + L2 磁盘缓存，减少 API 调用       |\n| **设计转代码提示词** | 内置专业提示词模板，指导 AI 生成高质量代码 |\n| **轻量资源访问**     | Resources API 提供低 Token 消耗的数据访问  |\n\n### 核心改进\n\n| 功能     | 改进前       | 改进后                 |\n| -------- | ------------ | ---------------------- |\n| 图标导出 | ~45 个碎片   | 2 个合并（减少 96%）   |\n| 布局检测 | 手动绝对定位 | 自动 Flexbox/Grid 推断 |\n| CSS 输出 | 原始值       | 优化后移除默认值       |\n| API 调用 | 每次请求     | 24 小时智能缓存        |\n\n## 快速开始\n\n### 前提条件\n\n- Node.js >= 18.0.0\n- 具有 API 访问权限的 Figma 账户\n\n### 安装\n\n**通过 Smithery（推荐）**\n\n```bash\nnpx -y @smithery/cli install @1yhy/Figma-Context-MCP --client claude\n```\n\n**通过 npm**\n\n```bash\nnpm install -g @yhy2001/figma-mcp-server\n```\n\n**从源码安装**\n\n```bash\ngit clone https://github.com/1yhy/Figma-Context-MCP.git\ncd Figma-Context-MCP\npnpm install\npnpm build\n```\n\n### 配置\n\n#### 1. 获取 Figma API 令牌\n\n1. 访问 [Figma 账户设置](https://www.figma.com/settings)\n2. 滚动到 \"Personal access tokens\"\n3. 点击 \"Create new token\"\n4. 复制令牌\n\n#### 2. 配置 AI 工具\n\n<details>\n<summary><strong>Cursor / Windsurf / Cline</strong></summary>\n\n添加到 MCP 配置文件：\n\n```json\n{\n  \"mcpServers\": {\n    \"Figma\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@yhy2001/figma-mcp-server\", \"--stdio\"],\n      \"env\": {\n        \"FIGMA_API_KEY\": \"your-figma-api-key\"\n      }\n    }\n  }\n}\n```\n\n</details>\n\n<details>\n<summary><strong>HTTP/SSE 模式（本地开发）</strong></summary>\n\n```bash\n# 启动服务器\nfigma-mcp --figma-api-key=<your-key> --port=3333\n\n# 通过 SSE 连接\n# URL: http://localhost:3333/sse\n```\n\n</details>\n\n### 使用示例\n\n```\n请实现这个 Figma 设计：https://www.figma.com/design/abc123/MyDesign?node-id=1:234\n\n使用 React 和 Tailwind CSS。\n```\n\n---\n\n## MCP 能力\n\n本服务器提供完整的 MCP 能力支持：\n\n```\n┌─────────────────────────────────────────────────────────────┐\n│                  Figma MCP Server v1.0.2                    │\n├─────────────────────────────────────────────────────────────┤\n│  Tools (2)                        AI 调用的操作              │\n│  ├── get_figma_data              获取设计数据                │\n│  └── download_figma_images       下载图片资产                │\n├─────────────────────────────────────────────────────────────┤\n│  Prompts (3)                      用户选择的提示词模板        │\n│  ├── design_to_code              设计转代码完整流程           │\n│  ├── analyze_components          组件结构分析                │\n│  └── extract_styles              样式 Token 提取            │\n├─────────────────────────────────────────────────────────────┤\n│  Resources (5)                    轻量级数据资源              │\n│  ├── figma://help                使用指南                   │\n│  ├── figma://file/{key}          文件元数据 (~200 tokens)    │\n│  ├── figma://file/{key}/styles   设计 Tokens (~500 tokens)  │\n│  ├── figma://file/{key}/components 组件列表 (~300 tokens)   │\n│  └── figma://file/{key}/assets   资产清单 (~400 tokens)     │\n└─────────────────────────────────────────────────────────────┘\n```\n\n### Tools（工具）\n\n| 工具                    | 描述               | 参数                              |\n| ----------------------- | ------------------ | --------------------------------- |\n| `get_figma_data`        | 获取简化的设计数据 | `fileKey`, `nodeId?`, `depth?`    |\n| `download_figma_images` | 下载图片和图标     | `fileKey`, `nodes[]`, `localPath` |\n\n### Prompts（提示词）\n\n内置的专业提示词模板，帮助 AI 生成高质量代码：\n\n| 提示词               | 描述                   | 参数                               |\n| -------------------- | ---------------------- | ---------------------------------- |\n| `design_to_code`     | 完整的设计转代码工作流 | `framework?`, `includeResponsive?` |\n| `analyze_components` | 分析组件结构和复用性   | -                                  |\n| `extract_styles`     | 提取设计 Tokens        | -                                  |\n\n**design_to_code 工作流包含：**\n\n1. **项目分析** - 读取主题配置、全局样式、组件库\n2. **结构分析** - 识别页面模式、组件拆分策略\n3. **ASCII 布局图** - 生成带组件和资产标注的布局蓝图\n4. **资产管理** - 分析、下载和组织图片/图标\n5. **代码生成** - 遵循项目规范生成代码\n6. **无障碍优化** - 语义化 HTML、ARIA 标签\n7. **响应式适配** - 移动端布局调整\n\n### Resources（资源）\n\n轻量级数据访问，节省 Token 消耗：\n\n```bash\n# 获取文件元数据（~200 tokens）\nfigma://file/abc123\n\n# 获取设计 Tokens（~500 tokens）\nfigma://file/abc123/styles\n\n# 获取组件列表（~300 tokens）\nfigma://file/abc123/components\n\n# 获取资产清单（~400 tokens）\nfigma://file/abc123/assets\n```\n\n**Resources vs Tools 对比：**\n\n| 特性       | Tools            | Resources           |\n| ---------- | ---------------- | ------------------- |\n| 控制方     | AI 自动调用      | 用户/客户端主动读取 |\n| Token 消耗 | 较高（完整数据） | 较低（精简摘要）    |\n| 用途       | 执行操作         | 浏览和探索          |\n\n---\n\n## 架构\n\n```\n┌──────────────────────────────────────────────────────────────┐\n│                        MCP Server                            │\n├──────────────────────────────────────────────────────────────┤\n│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐   │\n│  │   Tools     │  │   Prompts   │  │     Resources       │   │\n│  │ (2 个工具)   │  │ (3 个模板)   │  │   (5 个资源)        │   │\n│  └──────┬──────┘  └─────────────┘  └──────────┬──────────┘   │\n│         │                                      │              │\n│         └──────────────────┬───────────────────┘              │\n│                            ▼                                  │\n│  ┌────────────────────────────────────────────────────────┐  │\n│  │                   FigmaService                         │  │\n│  │          API 调用 • 验证 • 错误处理 • 限流              │  │\n│  └────────────────────────┬───────────────────────────────┘  │\n│                           │                                  │\n│         ┌─────────────────┴─────────────────┐                │\n│         ▼                                   ▼                │\n│  ┌─────────────────┐              ┌─────────────────────┐    │\n│  │   CacheManager  │              │    Parser + Algo    │    │\n│  │  L1: LRU 内存    │              │  • 布局检测          │    │\n│  │  L2: 磁盘持久化   │              │  • 图标合并          │    │\n│  └─────────────────┘              │  • CSS 生成          │    │\n│                                   └─────────────────────┘    │\n└──────────────────────────────────────────────────────────────┘\n```\n\n### 缓存系统\n\n两层缓存架构，显著减少 API 调用：\n\n| 层级 | 存储     | 容量               | TTL       | 用途           |\n| ---- | -------- | ------------------ | --------- | -------------- |\n| L1   | 内存 LRU | 100 节点 / 50 图片 | 5-10 分钟 | 热数据快速访问 |\n| L2   | 磁盘     | 500MB              | 24 小时   | 持久化缓存     |\n\n### 布局检测算法\n\n自动将绝对定位转换为语义化的 Flexbox/Grid 布局：\n\n```\n输入（Figma 绝对定位）:\n┌─────────────────────────┐\n│ ■ (10,10)  ■ (110,10)   │\n│ ■ (10,60)  ■ (110,60)   │\n└─────────────────────────┘\n\n输出（推断的 Grid）:\ndisplay: grid\ngrid-template-columns: 100px 100px\ngrid-template-rows: 50px 50px\ngap: 10px\n```\n\n---\n\n## 项目结构\n\n```\nsrc/\n├── algorithms/           # 智能算法\n│   ├── layout/          # 布局检测（Flex/Grid 推断）\n│   └── icon/            # 图标合并检测\n├── core/                 # 核心解析\n│   ├── parser.ts        # Figma 数据解析\n│   ├── style.ts         # CSS 样式生成\n│   ├── layout.ts        # 布局处理\n│   └── effects.ts       # 效果处理\n├── services/             # 服务层\n│   ├── figma.ts         # Figma API 客户端\n│   └── cache/           # 多层缓存系统\n├── prompts/              # MCP 提示词模板\n├── resources/            # MCP 资源处理器\n├── types/                # TypeScript 类型定义\n├── utils/                # 工具函数\n├── server.ts             # MCP 服务器主入口\n└── index.ts              # CLI 入口\n\ntests/\n├── fixtures/             # 测试数据\n│   ├── figma-data/      # Figma API 返回的原始 JSON\n│   └── expected/        # 预期输出快照\n├── integration/          # 集成测试\n│   ├── layout-optimization.test.ts  # 布局优化测试\n│   ├── output-quality.test.ts       # 输出质量验证\n│   └── parser.test.ts               # 解析器测试\n└── unit/                 # 单元测试\n    ├── algorithms/      # 算法测试（布局检测、图标合并）\n    ├── resources/       # 资源处理器测试\n    └── services/        # 服务层测试\n\nscripts/\n└── fetch-test-data.ts   # 获取 Figma 测试数据工具\n```\n\n---\n\n## 文档\n\n### 核心算法\n\n| 中文                                               | English                                               |\n| -------------------------------------------------- | ----------------------------------------------------- |\n| [布局检测算法](./docs/zh-CN/layout-detection.md)   | [Layout Detection](./docs/en/layout-detection.md)     |\n| [图标检测算法](./docs/zh-CN/icon-detection.md)     | [Icon Detection](./docs/en/icon-detection.md)         |\n| [缓存架构设计](./docs/zh-CN/cache-architecture.md) | [Cache Architecture](./docs/en/cache-architecture.md) |\n\n### 研究文档\n\n| 中文                                                      | English                                                             |\n| --------------------------------------------------------- | ------------------------------------------------------------------- |\n| [Grid 布局研究](./docs/zh-CN/grid-layout-research.md)     | [Grid Layout Research](./docs/en/grid-layout-research.md)           |\n| [布局检测研究](./docs/zh-CN/layout-detection-research.md) | [Layout Detection Research](./docs/en/layout-detection-research.md) |\n\n### 架构文档\n\n| 中文                                     | English                                   |\n| ---------------------------------------- | ----------------------------------------- |\n| [系统架构](./docs/zh-CN/architecture.md) | [Architecture](./docs/en/architecture.md) |\n\n---\n\n## 命令行选项\n\n| 选项              | 描述                  | 默认值 |\n| ----------------- | --------------------- | ------ |\n| `--figma-api-key` | Figma API 令牌        | 必需   |\n| `--port`          | HTTP 模式的服务器端口 | 3333   |\n| `--stdio`         | 以 stdio 模式运行     | false  |\n| `--help`          | 显示帮助              | -      |\n\n---\n\n## 贡献指南\n\n欢迎贡献！\n\n```bash\n# 设置\ngit clone https://github.com/1yhy/Figma-Context-MCP.git\ncd Figma-Context-MCP\npnpm install\n\n# 开发\npnpm dev          # 监听模式\npnpm test         # 运行测试（272 个测试用例）\npnpm lint         # 代码检查\npnpm build        # 构建\n\n# 调试\npnpm inspect      # MCP Inspector\n\n# 使用自己的 Figma 数据测试\npnpm tsx scripts/fetch-test-data.ts <fileKey> <nodeId> <outputName>\n\n# 提交（使用约定式提交）\ngit commit -m \"feat: 添加新功能\"\n```\n\n### 提交类型\n\n| 类型       | 描述     |\n| ---------- | -------- |\n| `feat`     | 新功能   |\n| `fix`      | Bug 修复 |\n| `docs`     | 文档更新 |\n| `style`    | 代码风格 |\n| `refactor` | 代码重构 |\n| `test`     | 测试相关 |\n| `chore`    | 其他维护 |\n\n### 使用自己的 Figma 数据测试\n\n你可以使用自己的 Figma 设计来测试布局检测和优化效果：\n\n#### 1. 配置环境变量\n\n```bash\n# 复制环境变量模板\ncp .env.example .env\n\n# 编辑 .env 文件，填入你的配置\nFIGMA_API_KEY=your_figma_api_key_here\nTEST_FIGMA_FILE_KEY=your_file_key      # 可选\nTEST_FIGMA_NODE_ID=your_node_id        # 可选\n```\n\n#### 2. 获取 Figma 节点数据\n\n```bash\n# 方式一：使用命令行参数（推荐）\npnpm tsx scripts/fetch-test-data.ts <fileKey> <nodeId> <outputName>\n\n# 示例：获取指定节点\npnpm tsx scripts/fetch-test-data.ts UgtwrncR3GokKDIS7dpm4Z 402-34955 my-design\n\n# 方式二：使用环境变量\nTEST_FIGMA_FILE_KEY=xxx TEST_FIGMA_NODE_ID=123-456 pnpm tsx scripts/fetch-test-data.ts\n```\n\n**参数说明：**\n\n| 参数         | 说明           | 获取方式                                                |\n| ------------ | -------------- | ------------------------------------------------------- |\n| `fileKey`    | Figma 文件标识 | URL 中 `/design/` 后的部分，如 `UgtwrncR3GokKDIS7dpm4Z` |\n| `nodeId`     | 节点 ID        | URL 中 `node-id=` 参数，如 `402-34955`                  |\n| `outputName` | 输出文件名     | 自定义，如 `my-design`                                  |\n\n**示例 URL 解析：**\n\n```\nhttps://www.figma.com/design/UgtwrncR3GokKDIS7dpm4Z/MyProject?node-id=402-34955\n                            ↑ fileKey                              ↑ nodeId\n```\n\n#### 3. 运行测试验证输出\n\n```bash\n# 运行所有测试\npnpm test\n\n# 只运行集成测试（验证布局优化效果）\npnpm test tests/integration/\n\n# 查看输出的 JSON 文件\nls tests/fixtures/figma-data/\n```\n\n#### 4. 分析优化结果\n\n测试会自动验证：\n\n- **数据压缩率** - 通常 >50% 压缩\n- **布局检测** - Flex/Grid 布局识别率\n- **CSS 属性** - 冗余属性清理\n- **输出质量** - 结构一致性检查\n\n如果测试失败，说明输出可能不符合预期，可以根据错误信息调整或报告 issue。\n\n---\n\n## 许可证\n\n[MIT](./LICENSE) © 1yhy\n\n## 致谢\n\n- [Figma-Context-MCP](https://github.com/GLips/Figma-Context-MCP) - 原始项目\n- [Model Context Protocol](https://modelcontextprotocol.io/) - MCP 规范\n- [Best-README-Template](https://github.com/othneildrew/Best-README-Template) - README 模板参考\n\n---\n\n<p align=\"center\">\n  为 AI 编码社区用 ❤️ 制作\n</p>\n","readmeFilename":"README.zh-CN.md","author":{"name":"1yhy"}}