UI Code MCP

参考 Ant Design Components MCP 的文件式方案，项目现已使用多组件仓库知识架构。当前接入 weapp-ui 和 weapp-ebdcontainercoms 两个组件库；后者直接导入 /workspace/component-knowledge 标准制品，不读取本地源码仓库。构建期生成或导入 componentData/libraries/<libraryId>，运行期通过 stdio MCP 按库查询，不使用 SQLite、FTS 或向量数据库。

工具

• list-libraries
• list-components
• search-components
• resolve-component-symbol
• get-component-info
• get-component-source
• list-component-examples
• get-component-example
• get-component-changelog
• search-icons
• get-icon
• get-icon-svg
• validate-ui（基于包内 TypeScript 声明闭包与 iconfont；上下文缺失时 fail-closed）

当前 weapp-ui 数据基线为 128 个组件族、1688 份源码、825 份 PC 原始 Demo、1685 份类型声明和 8255 个图标元数据；图标知识索引落地为 7440 个唯一规范名、5714 条 SVG 内容分片。本次知识包不收录 Mobile Demo。类型图审计覆盖 315 个 JSX Symbol：198 个顶层、117 个静态成员，包含 305 个 strict 和 10 个 open Props 契约。审计结果随知识包发布在 symbol-audit-report.json。

当前 [email protected] 数据来自标准 Schema 2 知识制品，包含 DocListStandalone、WorkflowListStandalone 两个 PC 组件和 27 份源码。该包缺少 CHANGELOG，保留 1 条非阻断 warning；由于未提供 Schema 3 validation bundle，该库暂不支持 validate-ui。

正式组件发现契约：list-components({platform:'pc'|'mobile'|'all'}) 一次返回所有已加载库的完整轻目录（缺省 platform 为 pc）， 不接受 libraryId、limit 或 cursor，也不返回 truncated/nextCursor。目录项的 libraryId + componentName 可直接用于详情、源码、Demo 和 changelog 工具；目录 Symbol 可直接用于 resolver。当前实测 pc=120、 all=130，响应约 59.4 KiB/63.4 KiB，用途来自 componentData 的确定性文档字段或明确标记的关键词/Symbol 推导。

构建与验证

npm install
npm run legacy:build:weapp-ui
npm run legacy:build-icons:weapp-ui
npm run validate
npm run legacy:audit:weapp-ui
npm run validate:package -- --input componentData/libraries/weapp-ui
npm test
npm run bundle
npm run package:agent
npm run smoke
npm run smoke:all
npm run smoke:all:ebdcontainer

上述 legacy:* 仅用于维护当前 weapp-ui 存量资料，不是其他仓库的接入方式。其他仓库自行生成标准包后使用 validate:package 和 import:data。

知识数据位于 componentData/，发布时与 release/server.mjs 一起交付。

npm run package:agent 会生成与当前版本对应的运行目录，这是分发给 Agent 客户端的完整运行包。客户端不需要 src、scripts 或 test。

多仓库采用分布式生成：各组件仓库自行生成标准 Library Knowledge Package，本项目使用 validate:package 和 import:data 通用校验、导入，不负责理解每个仓库的特殊目录。所有对外规范、Schema、对接导入和校验说明统一位于 spec/component-data。

完整架构、Agent/MCP 职责边界、调用时序与代码分布见 docs/architecture.md。

当前正式工具、运行边界、validator 和兼容性契约见 docs/CONTRACTS.md。

项目当前基线、后续阶段、优先级和验收标准见 docs/roadmap.md。

接入其他组件仓库所需的多库架构改造、仓库资料契约和验收清单见 docs/multi-repository-design.md。

componentData 的输入、配置、生成算法、新增组件和校验流程见 docs/component-data-generation.md。

独立客户端安装、配置、验证和使用说明见 docs/client-usage.md。

可直接复制到 WorkBuddy 的最新集成验证脚手架和通过标准见 docs/test-cases/workbuddy-integration-verify.md。

生产环境的构建发布、制品分发、WorkBuddy 安装、灰度回滚和后续 HTTP 演进方案见 docs/production-deployment.md。

集中式 Streamable HTTP MCP 已列为后续计划，前置条件、开发改造、实施阶段和验收标准见 docs/http-mcp-roadmap.md。

WorkBuddy

本地源码联调配置如下；生产安装建议固定 npm 精确版本并使用安装目录中 Node 与 release/server.mjs 的绝对路径。

{
  "mcpServers": {
    "ui-code": {
      "command": "/absolute/path/to/node-22-or-newer",
      "args": ["/absolute/path/to/release/server.mjs"],
      "env": {
        "COMPONENT_KNOWLEDGE_ROOT": "/absolute/path/to/componentData",
        "COMPONENT_MCP_DEFAULT_LIBRARY": "weapp-ui"
      },
      "disabled": false
    }
  }
}

升级或改配置后需要完全重启 WorkBuddy。npm 包版本、initialize.serverInfo.version 与 list-libraries.data.server.version 必须一致；当前发布候选为 0.2.7。

npm 私服发版

仓库新增 release 分支，定位为预上线与正式发版分支。develop 继续用于日常开发和集成； 待发布代码必须先进入 release。以后正式 npm 包和 Docker HTTP 制品都只能从 release 生成，不得直接从 develop、功能分支或本地未提交状态发布。

发版前必须确认当前分支为 release、工作区干净，并且 HEAD 与 origin/release 一致；同一版本的 npm 包、Docker 制品和校验结果必须来自同一个 commit。

目标 registry：

http://10.10.27.63:4873

先确认当前版本号和私服登录状态：

npm whoami --registry http://10.10.27.63:4873
npm version patch --no-git-tag-version

Agent 协助发版时只执行到发布前准备：

npm run release:prepare

release:prepare 会完成完整门禁并生成 release/ui-code-mcp-<version>.tgz。到这一步必须暂停，由用户在本机手动执行私服发布：

npm run publish:private

发布完成后，用户告知 Agent 继续，再执行 Docker 制品和部署等后续步骤。

publish:private 会通过 npm 的 prepack 生命周期自动执行 release:check，依次校验 componentData 包、全库数据、自动测试、Server bundle 和 stdio smoke。任一步失败都不会进入上传阶段。

其中 smoke:all 会遍历知识包内所有组件，并对每个组件实际调用 info、source、examples 和 changelog；不是只抽查 Button 等代表组件。

也可以在不发布的情况下检查：

npm run release:check
npm pack --dry-run --ignore-scripts

服务器 Docker HTTP 发版使用：

npm run release:docker

该命令在完整发布门禁通过后，生成 release/ui-code-mcp-http-<version>-server-docker.tar.gz 及对应 SHA-256 校验文件。服务器解压后执行 docker compose build 和 docker compose up -d。

将 release/ 中最高版本制品部署到默认内网服务器：

npm run deploy:docker

部署命令会先校验 SHA-256，再上传、重建容器并检查 /readyz。服务器地址等覆盖参数见 生产部署说明。

发布包只包含：

• release/server.mjs；
• componentData/；
• spec/component-data/；
• docs/；
• README.md；
• npm 自动生成的 package.json。

安装或通过 npx 启动：

npx --registry http://10.10.27.63:4873 ui-code-mcp