AI 应用MCP 服务【免费下载链接】Figma-Context-MCPMCP server to provide Figma layout information to AI coding agents like Cursor项目地址https://gitcode.com/gh_mirrors/fi/Figma-Context-MCP点击查看免费下载本篇技术指南以 CONTRIBUTING.md 为骨架面向希望为 Figma-Context-MCPFramelink MCP for Figma贡献代码的开发者系统讲解该项目的设计哲学、本地开发环境搭建、开发命令、项目结构、代码风格、提交规范与 Pull Request 流程。读完本文你将能够在本地完整跑通该 MCP Server 的开发、测试与联调链路并按照与维护者一致的质量标准提交可被合并的 PR。一、项目定位与贡献哲学先理解我们为什么这样做在动手写代码之前CONTRIBUTING.md 用两个核心原则划定了项目的边界。理解它们是提交被接受的第一道门槛。坚持 Unix 工具哲学一个工具只做一件事本项目严格遵守 Unix 哲学工具只承担单一职责只暴露极少的参数。这样做的直接动机是——MCP 的调用方是 LLM如 Cursor 等 AI 编程代理参数越少、语义越单一模型在调用时就越不容易产生歧义或误用。由此衍生出一条重要的设计决策凡是项目级即多个请求之间不太可能变化的配置项优先做成命令行参数而不是暴露为工具tool参数。例如 Figma 访问令牌、端口、输出格式这类配置在 src/config.ts 中被设计为 CLI flag 与环境变量而get_figma_data这类工具的参数则只保留与单次请求强相关的输入。这条原则在 src/bin.ts 的 CLI 定义中得到了完整贯彻。MCP Server 的边界只负责设计摄取项目的核心职责只有一个摄取ingesting设计数据供 AI 消费。因此以下功能被明确列为范围之外应该交给其他专业工具处理图片转换、裁剪或其他图像处理将设计数据同步到 CMS 或数据库代码生成或框架专属输出与设计摄取无关的第三方集成这种聚焦带来的收益是明确的职责边界清晰、可维护性更好、测试与调试更简单、与 AI 工具的集成更可靠。从源码看这种边界被落实为极简的工具集——src/mcp/tools/index.ts 仅注册两个工具get_figma_data获取并简化 Figma 设计数据与download_figma_images下载 Figma 图片。二、本地开发环境搭建从零到跑通环境前提PrerequisitesCONTRIBUTING.md 列出的前提条件如下Node.js文档要求 18.0.0 或更高注意当前仓库 package.json 的engines字段已将要求提升至20.20.0且声明了包管理器pnpm10.10.0见 package.json。因此实际开发建议使用 Node.js ≥ 20.20.0 pnpm 10.x。pnpm推荐包管理器。Figma API 访问令牌Personal Access Token可在 Figma 账户设置中创建也可以使用 OAuth Bearer Token环境变量名见下文。七个步骤搭建开发环境克隆仓库从当前仓库克隆若用于开发本仓库镜像请使用对应的镜像地址git clone https://gitcode.com/gh_mirrors/fi/Figma-Context-MCP.git cd Figma-Context-MCP安装依赖pnpm install配置环境变量在仓库根目录创建.env文件FIGMA_API_KEYyour_figma_api_key_here如果你使用 OAuth 方式则可以改为设置FIGMA_OAUTH_TOKEN。从源码看src/config.ts 的resolveAuth会同时读取这两个变量并优先采用 OAuth 认证方式useOAuth为真时使用 Bearer Token。此外非 stdio 模式下HTTP 请求还可以通过X-Figma-Token请求头按请求提供凭据见 src/server.ts。构建项目pnpm buildbuild脚本使用tsup --dts打包产物输出到dist/见 package.json。运行测试pnpm test测试框架为 Vitest全局配置见 vitest.config.ts测试超时 30 秒~/路径别名与 tsconfig 保持一致。启动开发服务器pnpm devdev以 watch 模式运行tsup --watch代码变更后自动重新构建cross-env NODE_ENVdevelopment见 package.json。本地联调StreamableHTTPpnpm dev会启动一个可通过 Streamable HTTP 连接的本地服务器。要连接它可在你的 MCP JSON 配置文件中加入以下配置注意部分 MCP 客户端使用不同的配置格式请以对应客户端的文档为准mcpServers: { Framelink MCP for Figma - Local StreamableHTTP: { url: http://localhost:3333/mcp } }从源码看HTTP 模式默认监听127.0.0.1:3333且同时挂载/mcp与/sse两个端点——/sse是为兼容既有客户端配置保留的现代 MCP 客户端会先 POST 探测再回退 SSE见 src/server.ts。一个容易踩的坑stdio 模式与全局凭据如果你使用--stdio模式pnpm dev:cli或NODE_ENVcliMCP 客户端是直接以子进程方式启动服务器的没有按请求传 token的通道。因此 src/server.ts 会在启动时调用requireGlobalCredentials做快速失败——如果既没有FIGMA_API_KEY也没有FIGMA_OAUTH_TOKEN直接抛错退出而不是等到第一次工具调用才报出令人困惑的 send X-Figma-Token 信息实现见 src/config.ts。三、开发命令速查表CONTRIBUTING.md 列出的核心命令结合 CLAUDE.md 与 package.json 补充的完整命令如下命令作用pnpm dev开发模式watch 自动重启HTTPpnpm dev:cli开发模式stdiopnpm build用 tsup 构建输出到dist/pnpm type-check仅做 TypeScript 类型检查tsc --noEmitpnpm test运行 Vitest 测试pnpm lint运行 ESLintpnpm format用 Prettier 格式化代码pnpm inspect运行 MCP Inspector 调试pnpm start生产模式启动HTTP默认端口 3333pnpm start:cli生产模式启动stdiopnpm test -- path/to/test.ts运行单个测试文件pnpm test -- --testNamePatternpattern按名称模式筛选测试提示当前仓库还提供pnpm benchmark:simplify运行简化性能基准脚本见 package.json 与 scripts/benchmark-simplify.ts可用于评估提取器简化输出的性能表现。四、项目结构导航源码级CONTRIBUTING.md 给出了项目结构的概览。结合当前仓库的实际布局已与文档略有演进完整的目录地图如下src/ ├── bin.ts # CLI 入口调用 startServer()文档中的 cli.ts 已演进为 bin.ts ├── config.ts # 配置管理CLI flag / 环境变量 / 默认值 三级解析 ├── index.ts # 库导出extractors、types 等 ├── server.ts # MCP 服务器初始化stdio 与 HTTP 模式选择 ├── mcp-server.ts # 面向外部消费者的库级再导出createServer、startServer 等 ├── mcp/ # MCP 相关代码 │ ├── index.ts │ └── tools/ # MCP 工具定义get_figma_data、download_figma_images ├── extractors/ # 提取器系统解析 Figma API 响应并简化 ├── services/ # 核心业务逻辑Figma API 客户端等 ├── transformers/ # 数据转换逻辑layout/style/effects/text/component ├── telemetry/ # 使用遥测含错误脱敏 ├── utils/ # 工具函数序列化、日志、代理等 └── tests/ # 测试文件核心数据流MCP 工具层src/mcp/tools/定义工具 schema 与处理器——get_figma_data获取并简化设计数据download_figma_images下载图片。Figma 服务层src/services/figma.tsFigma REST API 客户端处理认证Personal Access Token 或 OAuth提供getRawFile()、getRawNode()、downloadImages()等方法。提取器系统src/extractors/把原始 Figma API 响应转换为精简结构——design-extractor.ts入口解析 API 响应并调用提取器node-walker.ts递归遍历并对每个节点应用提取器built-in.ts内置提取器layoutExtractor、textExtractor、visualsExtractor、componentExtractor且可组合allExtractors组合全部内置提取器。转换器层src/transformers/把具体 Figma 属性转为可消费数据——layout.ts布局/定位、style.ts填充、描边、effects.ts阴影、模糊、text.ts文本内容与样式、component.ts组件元数据。另外代码库使用~/作为src/的路径别名配置在 tsconfig.json 与 vitest.config.ts贡献代码时应沿用这一约定。五、代码风格与质量标准TypeScript 与格式化所有新代码必须使用 TypeScript遵循 tsconfig.json 中定义的严格模式设置strict: true、ES2022 目标、NodeNext 模块解析等。代码格式化使用 Prettierpnpm format代码检查使用 ESLintpnpm lint。遵循既有代码模式与约定。注释规范什么值得写、什么不该写CONTRIBUTING.md 未展开但仓库内的 CLAUDE.md 给出了团队对注释的明确要求贡献者应当遵循不该出现的注释复述代码行为的注释、被注释掉的代码、显而易见的注释如 increment counter、用注释替代良好命名。值得写的注释为什么存在——解决什么问题、为何有价值为什么这样实现——重要的设计决策及理由为什么不那样做——考虑过但否决的方案防止后人重蹈覆辙警告——不明显的坑、顺序依赖如必须先于 X 发生领域桥接——复杂领域逻辑协议规范、算法无法完全用代码表达时看似错误实则有意——代码看似冗余/错误但存在非显而易见的理由如测试实现的接口契约、承重副作用负空间——刻意不处理某情况且这种缺失是有意为之例如不重试——由调用方处理退避可防止后人好心加入破坏上游假设的重试逻辑。测试哲学Write tests. Not too many. Mostly integration.每个测试都有成本维护、误报、拖慢 CI测试必须挣得自己的位置。大多数功能需要 25 个测试有些则一个都不需要简单 CRUD、样式、配置变更、框架约定代码等可零测试。优先设计功能核心 命令外壳functional core, imperative shell把纯业务逻辑与 IO 分离以便测试。测行为不测实现只通过公开接口验证行为。不测类型系统已保证的东西TypeScript 编译期保证的运行时测试没有价值。不测框架不验证 Express 路由、React 渲染、ORM 查询是否工作——测你自己的逻辑。优先真实实现而非 mockmock 会把测试耦合到实现细节并掩盖真实 bug只在系统边界网络、文件系统、时间处 mock。错误处理只在系统边界校验信任内部代码与框架保证只在系统边界用户输入、外部 API、文件 IO做校验。不要为实际不会发生的场景添加 try/catch、回退或防御性检查让错误自然向上传播由知道如何处理它的调用方去捕获。六、提交规范与 Pull Request 流程提交前检查Before You Start先检查已有的 Issues 和 PR避免重复工作。对于重大变更先创建 Issue 讨论方案。保持变更聚焦、原子化。Pull Request 流程Fork 仓库并创建特性分支做出修改遵循代码风格规范为新功能添加测试运行完整测试套件确保无破坏pnpm test pnpm type-check pnpm lint按需更新文档提交 PR附上清晰描述包含变更的上下文与动机。Commit MessagesConventional Commits 与版本号规则项目使用 Conventional Commits 规范来自动化版本管理与变更日志生成。维护者在 squash 合并你的 PR 时会应用正确的前缀因此单个提交中不必纠结前缀。但了解前缀如何影响版本号有助于理解发布机制前缀触发版本示例fix: descriptionpatch 版本0.6.4 → 0.6.5fix: handle empty framesfeat: descriptionminor 版本0.6.4 → 0.7.0feat: add yaml output formatfeat!: description或BREAKING CHANGE:footermajor 版本0.6.4 → 1.0.0feat!: drop node 18 supportchore:/docs:/test:/refactor:不触发发布docs: fix typopre-commit 钩子提交前的自动关卡仓库通过 lefthook.yml 配置了 pre-commit 钩子parallel 并行执行任何提交都会自动经过四道检查format对暂存的 TS/JS/JSON/MD 文件执行 Prettier 并重新 addlint对暂存的 TS/JS 文件执行 ESLinttype-check运行pnpm type-checkscan-hidden-chars用 scripts/scan-hidden-chars.mjs 扫描 TS/JS/JSON/MD/YAML 文件中的隐藏字符防止不可见字符混入代码。这意味着本地提交失败往往能帮你在推 PR 之前发现大部分格式与类型问题。我们欢迎什么 / 不欢迎什么欢迎新功能——扩展服务器能力以支持更多 Figma 特性Bug 修复——提升可靠性性能改进——让服务器更快文档改进——帮助更多人理解项目测试覆盖——改进测试套件代码质量——重构与清理。不欢迎超出设计摄取范围的功能见上文 Philosophy 章节未经讨论的破坏性变更不符合项目风格规范的代码没有测试的功能。七、贡献者值得了解的配置解析机制虽然配置细节不属于贡献流程本身但理解 src/config.ts 的解析机制能帮你判断新配置应该做成 flag 还是环境变量。核心是三级优先级链CLI flag → 环境变量 → 默认值resolve函数实现见 src/config.ts。常用配置项及其来源配置CLI flag环境变量默认值Figma 访问令牌--figma-api-keyFIGMA_API_KEY无OAuth 令牌--figma-oauth-tokenFIGMA_OAUTH_TOKEN无HTTP 端口--portFRAMELINK_PORT/PORT3333监听地址--hostFRAMELINK_HOST127.0.0.1输出格式--formatOUTPUT_FORMATtree跳过图片下载--skip-image-downloadsSKIP_IMAGE_DOWNLOADSfalse图片保存目录--image-dirIMAGE_DIR进程工作目录代理--proxyFIGMA_PROXY无关闭遥测--no-telemetryFRAMELINK_TELEMETRYoff/DO_NOT_TRACK1遥测开启要点--format的合法值为tree默认、紧凑、yaml、json--json是--formatjson的向后兼容别名src/config.ts。非法配置值会在启动时大声失败而不是静默强转src/config.ts。关于 token 效率由于简化后的输出由 LLM 消费每个字段都消耗上下文预算因此输出应当精简——能推断的默认值一律省略只输出偏差值例如strokeAlign: INSIDE与 LLM 默认生成的 CSSborder一致故被省略只保留OUTSIDE/CENTER。八、发布与版本自动化release-please项目发布由 release-please 自动化完成相关配置见 release-please-config.json。流程为合并到main后release-please 读取 Conventional Commits 前缀fix:、feat:、feat!:并维护一个 release PR合并该 release PR 后通过 OIDC 可信发布自动发布到 npm。因此 PR 是 squash 合并的PR 标题会成为 release-please 解析的提交信息——请务必在 PR 标题中使用 Conventional Commits 前缀。九、获取帮助与社区协作文档查阅 Framelink 官方文档了解产品用法与各客户端接入细节。Issues先在仓库的 Issues 中搜索若无结果再创建新 Issue。社区可加入项目的 Discord 社区与维护者和其他贡献者交流。十、许可与贡献协议本项目以 MIT License 发布见 LICENSE。向本项目贡献即表示你同意你的贡献将在 MIT License 下授权。结语Figma-Context-MCP 是一个边界清晰、设计克制、质量要求明确的 MCP Server 项目。遵循本文梳理的哲学原则、开发流程与质量标准你不仅能顺利提交被合并的 PR也能在维护者视角理解为什么代码要这样写。动手之前先在本地跑通pnpm install → pnpm build → pnpm test → pnpm dev这条完整链路再开始你的第一个贡献吧。赞分享AI 应用MCP 服务【免费下载链接】Figma-Context-MCPMCP server to provide Figma layout information to AI coding agents like Cursor项目地址https://gitcode.com/gh_mirrors/fi/Figma-Context-MCP点击查看免费下载相关推荐Figma-Context-MCP社区贡献指南提交PR前的检查清单Figma Context MCP社区贡献指南提交PR前的检查清单 前言为什么需要贡献检查清单 作为Figma Context MCPMCP ServeAI 应用MCP 服务终极Figma设计到代码智能桥梁Figma-Context-MCP完整实战指南终极Figma设计到代码智能桥梁Figma Context MCP完整实战指南 Figma Context MCP是一款革命性的Model Context PAI 应用MCP 服务Figma-Context-MCP代码审查标准提升代码质量的关键要点Figma Context MCP代码审查标准提升代码质量的关键要点 1. 引言为什么代码审查至关重要 你是否曾面对过Figma布局数据处理延迟、类型定义混AI 应用MCP 服务创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考