Penpot MCP types-generator 全解析如何从插件 API 文档自动生成 api_types.yml【免费下载链接】penpotPenpot: The open-source design platform for Product teams that need scalable collaboration.项目地址: https://gitcode.com/GitHub_Trending/pe/penpot导读mcp/types-generator是 Penpot MCP 服务器开发链路中的一组辅助脚本它负责抓取 Penpot 插件PluginAPI 的类型文档站点TypeDoc 生成的静态页面并将其清洗、汇总为一个结构化的api_types.yml文件。该 YAML 随后会被 MCP 服务器中的ApiDocs组件按需加载作为按需提供给 LLM 的 API 文档数据源。阅读本文后你将掌握整个类型的生成流程、两种数据来源远程生产文档 vs 仓库内本地文档、核心清理规则以及 pixi/Caddy 等工具链的完整用法。一、子项目定位服务于 MCP 服务器的文档工厂从 mcp/types-generator/README.md 的定义看本目录是 Penpot MCP 服务器开发中的辅助脚本集专门负责生成一份包含 Penpot 插件 API 类型及其文档说明的 YAML 文件。它自身不提供任何 MCP 能力而是为 MCP 服务器供给数据资产。从目录结构看该子项目仅由 4 个文件组成见 mcp/types-generator文件作用prepare_api_docs.py核心抓取与清洗脚本Pythonpixi.toml/pixi.lockpixi 环境声明与锁文件声明 Python 依赖build一键构建脚本先pixi install再执行脚本README.md使用说明而产出的数据会落入 mcp/packages/server/data/api_types.yml仓库当前已提交约 23000 行被 MCP 服务器消费。在 ApiDocs.ts 中该文件在运行时被解析加载并通过PenpotApiInfoTool见 PenpotApiInfoTool.ts暴露给 LLM 按需查询。也就是说本文讨论的是这份 LLM 可查询的 API 类型字典 是如何被生产出来的。二、环境搭建基于 pixi 的依赖管理项目使用 pixi 管理 Python 运行环境该工具已包含在 Penpot 的 devenv 中因此无需手工创建 virtualenv。执行环境安装pixi install按 README 说明此步骤是可选的——后面的build脚本会代为执行pixi install。依赖清单定义在 pixi.toml 中从源码可以确认实际用到的核心库与版本约束[dependencies] python 3.11.* beautifulsoup4 4.13.5,5 markdownify 1.1.0,2 requests 2.32.5,3 ruamel.yaml 0.18.15,0.19 [pypi-dependencies] sensai-utils 1.5.0, 2这些依赖与 prepare_api_docs.py 的 import 一一对应requests抓取远程 HTML 页面_fetch方法中调用requests.getbeautifulsoup4解析 TypeDoc 生成的 HTML DOM定位.col-content、.tsd-signature、.tsd-member等节点markdownify把清洗后的 HTML 片段转成 Markdown子类化MarkdownConverter定制转换行为ruamel.yaml以 YAML 块状字面量block literal风格写出结果保留|-语义以保持长文档可读sensai-utils提供logging.run_main包装入口与日志器。另外值得注意pixi.toml中声明了platforms [win-64,linux-64]即该工具链在 Windows 与 Linux 下均可安装使用。三、直接抓取线上文档prepare_api_docs.py url3.1 脚本行为prepare_api_docs.py从给定的 Web URL 读取 Penpot 插件 API 文档将其汇总进单个 YAML 文件。成功执行后会在父级目录的packages/server/data下生成api_types.yml。脚本主入口见 prepare_api_docs.py 中main()函数把目标目录固定解析为target_dir Path(__file__).parent.parent / packages / server / data即无论从哪个目录调用输出总是落到 mcp/packages/server/data/api_types.yml。脚本还预置了两个常量对应 README 中的两条路径LOCAL_API_DOCS_URL http://localhost:9090 PROD_API_DOCS_URL https://doc.plugins.penpot.app DEFAULT_API_DOCS_URL LOCAL_API_DOCS_URL # 不传 URL 时默认抓本地3.2 运行方式手动运行需已执行过pixi installpixi run python prepare_api_docs.py url也可以直接调用封装脚本 build它会额外自动完成 pixi 环境安装pixi installpixi run python prepare_api_docs.py $URL默认 URL 同样是http://localhost:9090./build url例如基于当前生产环境的 Penpot 插件 API 文档生成即 README 示例./build https://doc.plugins.penpot.app3.3 输出文件形态生成的api_types.yml以类型名 →TypeInfo的组织方式存放。TypeInfo数据类见源码第 106–123 行包含两个字段overview类型主文档包含全部声明/签名但不含成员详情members按成员分组如 Properties、Methods映射到成员名 → Markdown 描述。此外每个类型会在overview末尾追加一段 Referenced by: ...列出所有引用它的其他类型——这是脚本在抓取每个页面时通过解析.tsd-signature内a.tsd-signature-type链接收集到的反向引用关系见process_page与add_referencing_types。仓库中已生成的样例节选如下Penpot: overview: |- Interface Penpot These are methods and properties available on the penpot global object. interface Penpot { ui: { open: ( name: string, url: string, options?: { width: number; height: number; hidden?: boolean }, ) void; ... ## 四、基于仓库内最新文档生成pnpm run build:types ### 4.1 前提需要 Caddy 这种模式下数据源是**仓库内当前源码**实时构建出的文档页面因此必须先起一个静态文件服务器。README 明确要求 Caddy 已安装并在系统 PATH 中Caddy 同时被下文 build:types 脚本内部调用。 ### 4.2 一键流程 在 [mcp](https://link.gitcode.com/i/61b88d5bac6dc6c6136964e2ec89c22e) 目录types-generator 的父级执行 bash pnpm run build:types该命令对应 mcp/package.json 中的脚本定义build:types: bash ./scripts/build-types实际执行 build-types# 1. 默认 URL 指向本地 9090因此先构建本地文档 if [[ $URL http://localhost:9090 ]]; then pushd ../../plugins pnpm install pnpm run build:doc popd fi # 2. 用 Caddy 起 9090 静态服务并同时执行抓取脚本 pnpx concurrently --kill-others-on-fail -s last -k \ caddy file-server --root ../../plugins/dist/doc/ --listen :9090 \ bash ../types-generator/build $URL结合 plugins/package.json 中build:doc: typedoc ... --out dist/doc可知完整链路为在 plugins 目录执行pnpm run build:doc用 TypeDoc 把插件运行时类型定义生成静态站点到plugins/dist/doc/caddy file-server将该目录以127.0.0.1:9090暴露build:types的监听地址为:9090README 中单独起服务示例为127.0.0.1:9090../types-generator/build即前一节的封装脚本随后调用prepare_api_docs.py http://localhost:9090完成抓取与转换。由于concurrently配合--kill-others-on-fail -s last -k只要抓取脚本失败Caddy 进程也会被一并终止避免遗留后台服务。4.3 仅启动文档服务器若只想在本地查看文档而暂不执行抓取可跳过脚本、只启动静态服务器在mcp目录下caddy file-server --root ../plugins/dist/doc/ --listen 127.0.0.1:9090对应仓库路径即 plugins/dist/doc需先构建产生。同时build-types脚本也支持通过环境变量PENPOT_PLUGINS_API_DOC_URL覆盖目标 URL例如把它指向上游文档地址即可跳过本地构建、直接抓取远程文档。五、深入脚本内部如何把 HTML 清洗成LLM 友好的 Markdownprepare_api_docs.py最见功力的部分在于对 TypeDoc 页面做了大量定制清洗这正是保证最终 YAML 体积可控、语义干净的关键。理解这些规则有助于你判断何时需要重新生成、以及生成结果的形态。5.1 页面定位与成员拆分PenpotAPIDocsProcessor.run()先抓取modules.html在.col-content中收集所有指向interfaces/与types/的链接作为待处理类型列表再逐页处理。处理单个类型页时process_page遍历.col-content下带tsd-member-group的分组标签按h2文本如 Properties / Methods归类把组内每个tsd-member拆成成员名 → Markdown 描述成员名的提取优先取a.tsd-anchor的id否则取h3 span的文本无法确定时会触发断言从h3标题中提取的tsd-tag如Readonly会被重新插回签名区标题本身随后被移除因为它是冗余信息成员分组从 DOM 中删除后剩余内容作为该类型的overview。5.2 定制 Markdown 转换规则PenpotAPIContentMarkdownConverter继承自 markdownify通过重写process_tag实现了一套针对 Penpot API 文档的规则主要可归纳为丢弃导航噪音面包屑tsd-breadcrumb、索引区tsd-index-content、按钮如 Copy、Defined in 列表项、Inherited from 段落一律置空代码块化签名tsd-signature中的br转成换行仅保留readonly标记optional因已通过?表达而删除整体包裹进代码块pre块也会去掉内部按钮后转成代码块去冗余列表仅含单个li的tsd-signatures列表会被拆包为普通div递归处理避免出现只有一条且带缩进的项目符号链接取纯文本a链接只保留文字减少无关超链接对 LLM 上下文的干扰。5.3 YAML 写出全程块状字面量YamlConverter使用ruamel.yaml并开启preserve_quotes、把宽度放宽到 4096 以阻止自动折行再将所有字符串统一递归转换为LiteralScalarString使生成的 YAML 采用|-块状风格。这样长 Markdown 描述不会被折叠成冗长单行便于人读与增量 diff。5.4 调试辅助函数源码中还带有一个debug_type_conversion函数仅用于调试默认被注释可单独处理某个类型页并把转换结果打印到控制台例如将注释行替换为debug_type_conversion(interfaces/Path.html, LOCAL_API_DOCS_URL)在扩展转换规则、排查某个类型为何转换异常时非常有用。六、产出如何被消费从 api_types.yml 到 MCP 工具为了让生成 YAML这件事的上下文更完整这里补充其在运行时一侧的消费链路均位于 mcp/packages/server/srcApiDocs.tsApiDocs类在初始化时从data/api_types.yml加载全部类型数据运行时默认路径为当前工作目录下的data/api_types.ymlPenpotApiInfoTool.ts作为 MCP 工具暴露 API 文档查询能力其构造器接收ApiDocs实例PenpotMcpServer.ts服务器启动时实例化ApiDocs并注入各工具。也就是说当你修改了插件 API 类型或文档注释后应当重新执行本 README 描述的类型生成流程推荐走pnpm run build:types的本地模式使api_types.yml与最新源码保持同步MCP 服务器提供的 API 文档能力才会随之更新。七、两种生成模式的取舍小结模式命令数据源前置依赖适用场景生产文档./build https://doc.plugins.penpot.app线上发布版 API 文档pixi对齐线上公开 API、无需本地构建本地文档pnpm run build:types仓库内当前源码经 TypeDoc 构建的 plugins/dist/docCaddy、pnpm修改 API 类型/注释后同步生成最新 YAML需要说明的边界TypeDoc 本地构建依赖 plugins 子工作区中 plugins/package.json 声明的typedoc等开发依赖及其配置而脚本抓取的是 TypeDoc 输出中的特定 CSS 类结构tsd-*系列因此若上游 TypeDoc 的页面结构发生大版本变化可能需要同步修订prepare_api_docs.py中的选择器规则——这正是上文保留debug_type_conversion这类调试入口的原因。【免费下载链接】penpotPenpot: The open-source design platform for Product teams that need scalable collaboration.项目地址: https://gitcode.com/GitHub_Trending/pe/penpot创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考