Uiux Pro Max MCP

UI UX Pro Max MCP

一个面向通用 AI coding 客户端的 Python stdio MCP server，用于：

• 搜索 UI/UX 知识库
• 搜索特定技术栈最佳实践
• 生成结构化设计系统建议
• 在工作区内安全写入 MASTER.md 与页面 override 文件
• 提供 runtime diagnostics、cache refresh、catalog metadata 与 MCP resources

当前 MCP 已对齐 SKILL/cli/assets 的 16-stack 指南资产，并额外打包上游 templates/** 模板资源，覆盖 Web / Native / Mobile 多栈场景。

1. 环境要求

• Python 3.11+
• 建议使用虚拟环境
• Windows / macOS / Linux

已针对以下问题做兼容处理：

• Windows stdio UTF-8
• pathlib 路径归一化
• workspace boundary 写入限制
• 默认 overwrite=false

2. 快速开始

2.1 本地开发安装

在 mcp/ 目录下执行：

python -m pip install -e .

安装后可使用以下任一入口：

uiux-pro-max-mcp
python -m uiux_pro_max_mcp
python -m uiux_pro_max_mcp.server

2.2 启动前设置工作区

write_design_system_files 只允许写入工作区内部，建议显式设置：

PowerShell

$env:UIUX_PRO_MAX_MCP_WORKSPACE_ROOT = "C:/path/to/workspace"
$env:UIUX_PRO_MAX_MCP_LOG_LEVEL = "INFO"
$env:UIUX_PRO_MAX_MCP_PRELOAD_CACHE = "true"
uiux-pro-max-mcp

bash / zsh

export UIUX_PRO_MAX_MCP_WORKSPACE_ROOT="/path/to/workspace"
export UIUX_PRO_MAX_MCP_LOG_LEVEL="INFO"
export UIUX_PRO_MAX_MCP_PRELOAD_CACHE="true"
uiux-pro-max-mcp

环境变量说明：

• UIUX_PRO_MAX_MCP_WORKSPACE_ROOT：写文件允许落盘的工作区根目录
• UIUX_PRO_MAX_MCP_LOG_LEVEL：日志级别，默认 INFO
• UIUX_PRO_MAX_MCP_PRELOAD_CACHE：是否在启动时预热 search/design-system runtime，默认 true

3. 资产来源与同步方式

当前 mcp/ 包内实际随仓库 / wheel / sdist 发布的资产位于：

• src/uiux_pro_max_mcp/data/
• src/uiux_pro_max_mcp/data/stacks/
• src/uiux_pro_max_mcp/templates/

本仓库当前采用以下 provenance 约定：

1. 主源（source of truth）：SKILL/cli/assets
2. 源码参考：SKILL/src/ui-ux-pro-max
3. 历史参考：.claude/skills/ui-ux-pro-max

其中：

• stack catalog 通过扫描 SKILL/cli/assets/data/stacks/*.csv 生成
• threejs.csv 在同步阶段会被规范化到统一 stack schema（自动补 No 列并重排 header）
• templates/base/*.md 与 templates/platforms/*.json 会同步到 MCP 包内
• domain CSV 采用“审计后同步”的策略：当前已切到 SKILL/cli/assets 主治理链路，同时保留少量经审计确认更适合作为运行时版本的 MCP 本地变体

这些资产最初来源于上游 UI UX Pro Max Skill / CLI assets：

• https://github.com/nextlevelbuilder/ui-ux-pro-max-skill
• License: MIT

如果你手头同时维护一份上游 skill 仓库副本，可以使用同步脚本把 SKILL/cli/assets 回灌到 MCP 包内，避免 GitHub 源码、MCP 包数据、template 资源与上游资产漂移：

python scripts/sync_cli_skill_assets.py --dry-run --source-root /path/to/ui-ux-pro-max/SKILL/cli/assets
python scripts/sync_cli_skill_assets.py --source-root /path/to/ui-ux-pro-max/SKILL/cli/assets

如果你的本地工作区就是当前 monorepo 结构，也可以省略 --source-root；脚本默认会尝试 SKILL/cli/assets。

脚本会：

• 扫描 --source-root/data/stacks/*.csv 自动发现可用 stacks
• 对 stack CSV 做统一 schema 校验与规范化
• 同步 audited domain CSV / stack CSV 到 src/uiux_pro_max_mcp/data/
• 同步 templates/** 到 src/uiux_pro_max_mcp/templates/
• 生成 src/uiux_pro_max_mcp/data/catalog-manifest.json

如果你要更新 stack 资产，推荐流程是：

1. 准备或更新本地 UI UX Pro Max Skill 源目录
2. 运行 python scripts/sync_cli_skill_assets.py --dry-run --source-root /path/to/ui-ux-pro-max/SKILL/cli/assets
3. 运行 python scripts/sync_cli_skill_assets.py --source-root /path/to/ui-ux-pro-max/SKILL/cli/assets
4. 执行测试
5. 再构建/发布 MCP

如果你只是使用或发布这个独立 MCP 仓库，而不是维护上游 skill，则无需额外准备 .claude/ 目录；.claude 现在仅作为历史参考，不再是同步主源。

4. 客户端配置示例

4.1 通用 mcpServers 配置

{
  "mcpServers": {
    "uiux-pro-max": {
      "command": "uiux-pro-max-mcp",
      "env": {
        "UIUX_PRO_MAX_MCP_WORKSPACE_ROOT": "C:/path/to/your/workspace",
        "UIUX_PRO_MAX_MCP_LOG_LEVEL": "INFO",
        "UIUX_PRO_MAX_MCP_PRELOAD_CACHE": "true"
      }
    }
  }
}

4.2 通过 uvx 直接使用 TestPyPI 版本

如果你希望不先手动安装包，也可以直接通过 uvx 启动：

uvx --index https://test.pypi.org/simple --index https://pypi.org/simple --index-strategy unsafe-best-match uiux-pro-max-mcp==0.1.2

手动编辑MCP配置JSON时，可写成：

{
  "mcpServers": {
    "uiux-pro-max": {
      "command": "uvx",
      "args": [
        "--index",
        "https://test.pypi.org/simple",
        "--index",
        "https://pypi.org/simple",
        "--index-strategy",
        "unsafe-best-match",
        "uiux-pro-max-mcp==0.1.2"
      ],
      "env": {
        "UIUX_PRO_MAX_MCP_WORKSPACE_ROOT": "C:/path/to/your/workspace",
        "UIUX_PRO_MAX_MCP_LOG_LEVEL": "INFO",
        "UIUX_PRO_MAX_MCP_PRELOAD_CACHE": "true"
      }
    }
  }
}

4.3 Claude Desktop / Cursor / Cline 示例文件

可直接参考：

• examples/client-configs/claude-desktop.config.json
• examples/client-configs/cursor.mcp.json
• examples/client-configs/cline_mcp_settings.json
• examples/client-configs/generic-mcp-servers.json

5. 支持的 Domains 与 16 个 Stacks

5.1 Knowledge domains

当前知识搜索 domains 包括：

• style
• color
• chart
• landing
• product
• ux
• typography
• icons
• react
• web
• google-fonts

5.2 Stack guidelines

当前支持的 16 个 stack：

• angular
• astro
• flutter
• html-tailwind
• jetpack-compose
• laravel
• nextjs
• nuxt-ui
• nuxtjs
• react-native
• react
• shadcn
• svelte
• swiftui
• threejs
• vue

建议：MCP tool 层保持显式参数设计，search_stack_guidelines 仍要求传入 stack。 若你只是做通用 web UI，可优先从 html-tailwind 开始参考；若是 3D / Angular / Laravel 项目，也可直接查对应 stack 指南。

6. Tools 与 Resources

6.1 Tools

search_uiux_knowledge

搜索 UI/UX 知识库。

输入：

• query: string
• domain?: string
• max_results?: integer

返回重点：

• 结构化搜索结果
• source
• diagnostics.cache_hit
• diagnostics.query_duration_ms

search_stack_guidelines

搜索 stack-specific UI/UX 指南。

输入：

• query: string
• stack: string
• max_results?: integer

典型示例：

• stack="html-tailwind"：查 Tailwind 过渡、布局、可访问性实现方式
• stack="react"：查 hooks、state、render/perf 相关建议
• stack="react-native"：查列表、手势、样式、导航最佳实践

generate_design_system

生成结构化设计系统建议。

输入：

• query: string
• project_name?: string
• output_format?: "structured" | "markdown" | "ascii"

write_design_system_files

Mutating tool

输入：

• query: string
• project_name: string
• page?: string
• output_dir?: string
• overwrite?: boolean

安全规则：

• 仅允许写入 workspace 内
• 默认 overwrite=false
• 文件冲突返回 file_conflict
• 越界返回 workspace_boundary_error

get_uiux_metadata

返回能力发现信息：

• domains / stacks / output formats
• tools / resources
• data files / reasoning file
• catalog manifest / source-of-truth
• package version / workspace root

get_uiux_diagnostics

返回运行时状态：

• startup preload 状态
• search cache stats
• design-system runtime state
• last refresh state
• Python / platform / env 信息

refresh_uiux_cache

Maintenance tool

用于在 CSV / reasoning 文件变更后刷新内存缓存。

输入：

• force_reload?: boolean
• include_stacks?: boolean

6.2 Resources

• uiux://quick-reference
• uiux://diagnostics
• uiux://skill-quick-reference
• uiux://skill-content
• uiux://platform-templates/{platform}

7. 示例调用

7.1 通用 UI/UX 知识搜索

{
  "tool": "search_uiux_knowledge",
  "arguments": {
    "query": "fintech dark dashboard",
    "domain": "style",
    "max_results": 3
  }
}

7.2 Stack 指南：HTML + Tailwind

{
  "tool": "search_stack_guidelines",
  "arguments": {
    "query": "animate pulse transition",
    "stack": "html-tailwind",
    "max_results": 3
  }
}

7.3 Stack 指南：React

{
  "tool": "search_stack_guidelines",
  "arguments": {
    "query": "useState local state",
    "stack": "react",
    "max_results": 3
  }
}

7.4 Stack 指南：React Native

{
  "tool": "search_stack_guidelines",
  "arguments": {
    "query": "StyleSheet inline styles",
    "stack": "react-native",
    "max_results": 3
  }
}

8. 本地验证

8.1 运行测试

python -m unittest discover -s tests -v -p "test_*.py"

8.2 语法检查

python -m compileall src tests

当前测试覆盖：

• Search service / tool contract
• 多 stack search contract（含 html-tailwind / react / angular / laravel / threejs / react-native / swiftui）
• Catalog manifest / stack 目录一致性 / 字段校验
• Design-system service / rendering contract
• Persistence 安全与覆盖策略
• Cache preload / refresh / diagnostics
• MCP resources quick reference / diagnostics flow
• stdio MCP server smoke / integration flow
• package data / release metadata

9. 版本号策略

版本号现在采用单一来源：

• src/uiux_pro_max_mcp/__init__.py 中的 __version__

pyproject.toml 通过 setuptools dynamic version 读取该值，因此发布时只需要修改一处。

示例：

__version__ = "0.1.0"

如果你修改了版本号并且当前环境使用 editable install，建议重新安装一次：

python -m pip install -e .

10. 发布前清理与构建

10.1 清理策略

以下目录视为构建产物，不应提交到仓库：

• dist/
• build/
• src/uiux_pro_max_mcp.egg-info/
• pip-wheel-metadata/

这些规则已写入：

• 仓库根目录 .gitignore
• mcp/.gitignore

10.2 手动清理命令

PowerShell

Remove-Item -Recurse -Force dist, build, src/uiux_pro_max_mcp.egg-info -ErrorAction SilentlyContinue

bash / zsh

rm -rf dist build src/uiux_pro_max_mcp.egg-info

10.3 构建发布包

建议先安装发布工具：

python -m pip install --upgrade build twine

然后构建：

python -m build

校验包元数据：

python -m twine check dist/*

安装本地 wheel 验证：

python -m pip install --force-reinstall dist/uiux_pro_max_mcp-0.1.0-py3-none-any.whl

10.4 打包资源说明

本项目通过以下方式保证 data / manifest / templates 资产被包含进发布包：

1. pyproject.toml 中声明 package-data
2. MANIFEST.in 中声明 source distribution 资源包含规则

核心数据目录：

• src/uiux_pro_max_mcp/data/*.csv
• src/uiux_pro_max_mcp/data/*.json
• src/uiux_pro_max_mcp/data/stacks/*.csv
• src/uiux_pro_max_mcp/templates/base/*.md
• src/uiux_pro_max_mcp/templates/platforms/*.json

10.5 发布护栏建议

发布前至少执行以下检查：

python scripts/sync_cli_skill_assets.py --dry-run --source-root /path/to/ui-ux-pro-max/SKILL/cli/assets
python scripts/sync_cli_skill_assets.py --source-root /path/to/ui-ux-pro-max/SKILL/cli/assets
python -m unittest discover -s tests -v -p "test_*.py"
python -m build
python -m twine check dist/*

这样可以确保：

• 外部 skill 源目录（如果你提供了 --source-root）与 MCP stack / template 资产未漂移
• catalog-manifest.json 与运行时 stack 目录一致
• wheel / editable install 均包含完整 data + templates 资产

11. 维护提示

• stack 资产变更时，不要手工复制单个 CSV 后就直接发布。
• 如果你有上游 skill 源目录，优先更新 SKILL/cli/assets，再通过同步脚本回灌到 MCP package data / templates。
• 如果你替换了磁盘上的 CSV / reasoning 文件，记得调用 refresh_uiux_cache。
• 如需查看当前能力边界，优先使用 get_uiux_metadata 与 uiux://quick-reference。
• 如需查看上游模板资产，优先读取 uiux://skill-quick-reference、uiux://skill-content 与 uiux://platform-templates/{platform}。