{"_id":"@boltdoggy/figma","_rev":"2-eeb7e4fb5a73e440a0ea3c7fa7c9871e","name":"@boltdoggy/figma","dist-tags":{"latest":"1.0.1"},"versions":{"1.0.0":{"name":"@boltdoggy/figma","version":"1.0.0","keywords":["figma","cli","design","api"],"author":"","license":"ISC","_id":"@boltdoggy/figma@1.0.0","maintainers":[{"name":"lc60005457","email":"lc60005457@163.com"}],"bin":{"figma":"dist/index.js"},"dist":{"shasum":"a9fdf47c94e216acaa4e76af28eb22b1d94af756","tarball":"https://registry.npmjs.org/@boltdoggy/figma/-/figma-1.0.0.tgz","fileCount":18,"integrity":"sha512-MOhc689GlpNA8XDDiU0kKmNDaP2l3JEf7JiyqhhuMhfADXKiPSQQ3Y84d46fl+guL0136pOiRLkNMWgSgeeBCw==","signatures":[{"sig":"MEYCIQCdtPjdgk7WeGmxNBgAn76P2rQeWvfNJDSQtycUmFcoEgIhAMg17g5freJMFeNVU1fuL1wrG/dWnyHDQxyHn9Q6SXRJ","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":43481},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","exports":{".":"./dist/index.js"},"scripts":{"dev":"tsx src/index.ts","build":"tsgo","start":"node dist/index.js","typecheck":"tsgo --noEmit"},"_npmUser":{"name":"lc60005457","email":"lc60005457@163.com"},"_npmVersion":"11.9.0","description":"Figma REST API CLI - Figma MCP Server 的命令行封装","directories":{},"_nodeVersion":"24.14.0","dependencies":{"ora":"^8.1.0","conf":"^13.0.0","open":"^11.0.0","chalk":"^5.4.0","commander":"^13.0.0","cli-highlight":"^2.1.11","@modelcontextprotocol/sdk":"^1.29.0"},"_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.7.0","@types/node":"^22.0.0","@typescript/native-preview":"7.0.0-dev.20260604.1"},"_npmOperationalInternal":{"tmp":"tmp/figma_1.0.0_1780659301224_0.620190319624695","host":"s3://npm-registry-packages-npm-production"}},"1.0.1":{"name":"@boltdoggy/figma","version":"1.0.1","description":"Figma REST API CLI - Figma MCP Server 的命令行封装","type":"module","bin":{"figma":"dist/index.js"},"main":"./dist/index.js","exports":{".":"./dist/index.js"},"scripts":{"build":"tsgo","typecheck":"tsgo --noEmit","start":"node dist/index.js","dev":"tsx src/index.ts"},"keywords":["figma","cli","design","api"],"author":"","license":"ISC","devDependencies":{"@types/node":"^22.0.0","@typescript/native-preview":"7.0.0-dev.20260604.1","typescript":"^5.7.0"},"dependencies":{"@modelcontextprotocol/sdk":"^1.29.0","chalk":"^5.4.0","cli-highlight":"^2.1.11","commander":"^13.0.0","conf":"^13.0.0","open":"^11.0.0","ora":"^8.1.0"},"gitHead":"daaf91f061fd19e37e0efbc9c0fb7b830a743a2a","types":"./dist/index.d.ts","_id":"@boltdoggy/figma@1.0.1","_nodeVersion":"24.14.0","_npmVersion":"11.9.0","dist":{"integrity":"sha512-gngYeswYYhofm35aXlr4rsIR6JALowZPnLf2b4iriNaFsQjPsd19wGyb6SfH0tkjUrzEawhYLwH0qaEDRnCYyg==","shasum":"1657b475246d6a102957122a47a9e565d01840e0","tarball":"https://registry.npmjs.org/@boltdoggy/figma/-/figma-1.0.1.tgz","fileCount":18,"unpackedSize":43486,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIH26wCUTbSNYnsldKkbPgxiUrSbtaMMerY++23kgYG5rAiEA6L9Z3Hb5744TGpkBAheYSFV0pyhWeHMMjQOq5CI1zME="}]},"_npmUser":{"name":"lc60005457","email":"lc60005457@163.com"},"directories":{},"maintainers":[{"name":"lc60005457","email":"lc60005457@163.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/figma_1.0.1_1780661631850_0.5147799119752352"},"_hasShrinkwrap":false}},"time":{"created":"2026-06-05T11:35:01.025Z","modified":"2026-06-05T12:13:52.105Z","1.0.0":"2026-06-05T11:35:01.416Z","1.0.1":"2026-06-05T12:13:51.980Z"},"license":"ISC","keywords":["figma","cli","design","api"],"description":"Figma REST API CLI - Figma MCP Server 的命令行封装","maintainers":[{"name":"lc60005457","email":"lc60005457@163.com"}],"readme":"# Figma CLI\n\n> Figma MCP 命令行工具 — **给 AI Agent 用的 Figma 桥接器**\n>\n> 📖 关于 Figma MCP 认证，看这篇：[Kimi 用不了 Figma？看这里解决](https://juejin.cn/spost/7647784370972360755)\n\n将 Figma 的完整设计读写能力带到命令行，专为 **Claude Code / Cursor 等 AI Agent** 设计。\n\n## 设计思路\n\n本工具不封装 Figma REST API，而是作为 **Figma Remote MCP Server 的代理和前端**：\n\n- **`figma mcp`** — 启动 stdio MCP 代理，供 AI Agent 直接连接并使用所有 Figma MCP 工具\n- **`figma use-figma`** / **`figma call`** — 从终端直接调用 MCP 工具，无需 Agent 中间层\n- **`figma auth`** — 一站式认证管理（PAT + OAuth）\n\n---\n\n## 安装\n\n```bash\npnpm link                        # 本地 link（开发用）\n# 或\npnpm install -g @boltdoggy/figma # 全局安装（发布后）\n```\n\n> 也可以直接用 `npx -y @boltdoggy/figma` 无需安装即可运行（适合临时使用或 MCP 配置）。\n\n## 快速开始\n\n### 1. 认证\n\n```bash\n# 查看认证状态\nfigma auth status\n\n# 方式 A: OAuth 登录（推荐，支持 MCP 完整能力）\nfigma auth oauth-login    # 自动打开浏览器完成 PKCE 授权\n\n# 方式 B: 设置 Personal Access Token（只读操作需要）\nfigma auth set figd_xxxxxxxxxxxx\nfigma auth test            # 测试 PAT 有效性\n```\n\n### 2. 配置 MCP Server（供 AI Agent 使用）\n\n在 Claude Code、Cursor 或 Windsurf 中，将 `figma mcp` 注册为 stdio MCP Server。\n\n**方式 A — 全局安装后直接引用**（本地已 `pnpm link` 或 `npm i -g`）：\n\n| 平台 | 配置位置 |\n|------|----------|\n| **Claude Code** | `.claude/settings.local.json` 或 `~/.claude/settings.json` |\n| **Cursor** | `.cursor/mcp.json` |\n| **Windsurf** | `.windsurf/mcp.json` |\n\n```json\n{\n  \"mcpServers\": {\n    \"figma\": {\n      \"command\": \"figma\",\n      \"args\": [\"mcp\"]\n    }\n  }\n}\n```\n\n**方式 B — 无需安装，用 `npx -y` 自动拉取**（推荐）：\n\n```json\n{\n  \"mcpServers\": {\n    \"figma\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@boltdoggy/figma\", \"mcp\"]\n    }\n  }\n}\n```\n\n> `npx -y` 方式无需预先全局安装，每次自动从 npm 下载并运行最新版本。适合首次配置、跨机器使用或 CI 环境。\n\n配置后 Agent 自动获得 `use_figma`、`get_design_context`、`get_screenshot`、`search_design_system` 等全部 Figma MCP 工具，可直接读取或写入 Figma 设计文件。\n\n### 3. 直接从终端操作 Figma\n\n```bash\n# 解析 Figma URL\nfigma url \"https://figma.com/design/abc123/MyDesign?node-id=1-2\"\n\n# 在 Figma 文件中创建设计（内联代码）\nfigma use-figma abc123 --code '\n  const frame = figma.createFrame()\n  frame.resize(375, 812)\n  frame.fills = [{type: \"SOLID\", color: {r: 1, g: 1, b: 1}}]\n  frame.name = \"iPhone Frame\"\n  figma.currentPage.appendChild(frame)\n'\n\n# 从文件读取设计代码\nfigma use-figma abc123 -f ./my-design-code.js\n\n# 调用任意 MCP 工具\nfigma call get_screenshot --arg.fileKey=abc123 --arg.nodeId=1-2\nfigma call get_design_context --arg.fileKey=abc123 --arg.nodeId=1-2\nfigma call search_design_system --arg.fileKey=abc123 --arg.query=button\n```\n\n---\n\n## 命令参考\n\n### `figma auth` — 认证管理\n\n| 子命令 | 功能 |\n|--------|------|\n| `figma auth set <token>` | 设置 Personal Access Token |\n| `figma auth status` | 查看 PAT 和 OAuth 的详细状态 |\n| `figma auth clear` | 清除 PAT |\n| `figma auth test` | 测试 PAT 有效性（调用 `/v1/me`） |\n| `figma auth oauth-login` | **OAuth 登录** — 打开浏览器完成 PKCE 授权流程 |\n| `figma auth oauth-logout` | 清除 OAuth 令牌 |\n\n### `figma mcp` — MCP 代理\n\n启动 **stdio MCP 代理**，将所有 Figma Remote MCP Server 的工具透传给 AI Agent。\n\n```bash\nfigma mcp\n```\n\n这是核心能力：Agent 通过 stdio 连接后，可以获得 `use_figma`、`get_design_context`、`get_screenshot`、`search_design_system` 等全部 Figma MCP 工具。\n\n### `figma use-figma <fileKey>` — 执行设计操作\n\n在指定 Figma 文件中运行 JavaScript（Figma Plugin API），完成创建/编辑/同步等设计操作。\n\n| 选项 | 说明 |\n|------|------|\n| `-c, --code <code>` | 内联 JS 代码 |\n| `-f, --file <path>` | 从文件读取 JS 代码 |\n| `-d, --description <desc>` | 操作描述（默认 `figma-cli call`） |\n\n### `figma call <toolName>` — 调用任意 MCP 工具\n\n通用方式调用 Figma MCP 工具，参数用 `--arg.key=value` 传入。\n\n```bash\nfigma call get_screenshot --arg.fileKey=abc123 --arg.nodeId=1-2\nfigma call get_libraries --arg.fileKey=abc123\n```\n\n### `figma url <figmaUrl>` — URL 解析\n\n从 Figma URL 提取 `fileKey`、`nodeId` 和 `branchKey`。\n\n---\n\n## 认证\n\n### Personal Access Token（PAT）\n\n适用于 CI/CD 或传统 REST API 调用场景。\n\n```bash\nfigma auth set figd_xxxxxxxxxxxx\n```\n\n也可以通过环境变量设置（优先级更高）：\n\n```bash\nexport FIGMA_ACCESS_TOKEN=figd_xxxxxxxxxxxx\n```\n\n### OAuth 2.0 with PKCE（MCP 模式）\n\nMCP 完整读写能力需要 OAuth 认证：\n\n```bash\nfigma auth oauth-login\n```\n\n流程：\n1. 自动发现 Figma OAuth 端点\n2. 动态注册 OAuth 客户端\n3. 启动本地回调服务器 → 打开浏览器授权\n4. 使用 PKCE 交换 access + refresh token\n5. 令牌持久化存储，后续自动复用\n\n> **注意:** Figma Remote MCP Server 目前为 beta 阶段。Starter 免费版账户每月限制 6 次 MCP 工具调用。OAuth 客户端凭证需在 Figma OAuth 白名单中。\n\n---\n\n## 技术栈\n\n- **TypeScript** — 类型安全\n- **Commander.js** — CLI 框架\n- **@modelcontextprotocol/sdk** — MCP 协议（Stdio Server + Streamable HTTP Client）\n- **Chalk + Ora** — 颜色输出和加载动画\n- **Conf** — 配置文件持久化\n- **Figma Remote MCP Server** — 完整设计读写能力\n\n---\n\n## 博客\n\n关于 Figma MCP 认证问题的详细解读：[Kimi 用不了 Figma？看这里解决](https://juejin.cn/spost/7647784370972360755)\n\n---\n\n## 开发\n\n```bash\n# 安装依赖\npnpm install\n\n# 类型检查\npnpm typecheck\n\n# 编译\npnpm build\n\n# 开发模式（直接运行 ts）\npnpm dev -- <args>\n\n# 发布版\npnpm build && figma <command>\n```\n","readmeFilename":"README.md"}