uispec (Gnana997)

UISpec

让AI代理深入了解您的组件库。

  ](go.mod) 

UISpec是一个Go二进制文件，作为 MCP服务器 AI编码代理。它为代理提供了对UI组件目录的结构化访问——存在哪些组件，它们接受哪些道具，哪些值是有效的——并使用树形图解析根据该目录验证代理生成的代码。

作为开发人员的CLI工具和AI代理的MCP服务器。一个二进制文件，没有运行时依赖关系。

______________________________________________________________________

为什么选择UISpec？

AI编码代理不知道你的设计系统。当他们需要使用组件时，他们会读取源文件，grep通过 node_modules，并通过反复试验来纠正props和导入——在可能是一次查找的信息上燃烧令牌和代理循环。

UISpec取代了整个循环。而不是代理读取文件来弄清楚 Button 接受 variant="destructive" 并从以下来源进口 @/components/ui/button，它叫 get_component_details 并在一个响应中获取完整的prop模式、导入路径和组合规则。然后 validate_page 在编写代码之前捕获任何剩余的错误，不需要额外的生成往返。

无UISpec --代理读取文件、猜测、出错、读取更多文件，然后重试。 使用UISpec --代理查询目录，编写正确的代码，验证，完成。

______________________________________________________________________

运作原理

UISpec在两种模式下运行：

作为MCP服务器 --代理在规划和代码生成过程中通过专门构建的工具查询目录，然后调用 validate_page 在写入磁盘之前检查其输出。错误在毫秒内被捕获，而不会燃烧额外的生成令牌。

作为CLI工具 --开发人员运行 uispec validate 在CI或开发过程中，捕获组件误用、错误的prop值和不正确的导入。

______________________________________________________________________

MCP工具

涵盖整个代理工作流程的九个工具：

validate_page 支持 auto_fix: true --纠正确定性错误（错误的导入路径、无效的枚举值），并直接返回固定代码。

______________________________________________________________________

快速入门

安装：

# Homebrew (macOS / Linux)
brew install gnana997/tap/uispec

# Or download a pre-built binary from GitHub Releases
# https://github.com/gnana997/uispec/releases

# Or build from source
go install github.com/gnana997/uispec/cmd/uispec@latest

初始化项目 （写 .uispec/config.yaml，提取捆绑的shadcn目录，并自动配置检测到的AI代理）：

uispec init

根据目录验证文件：

uispec validate src/pages/dashboard.tsx
uispec validate src/pages/dashboard.tsx --fix   # auto-fix deterministic errors

查找组件：

uispec inspect Button
uispec inspect Dialog
uispec inspect DialogContent   # sub-component lookup

启动MCP服务器：

uispec serve

______________________________________________________________________

添加到您的AI代理

配置AI代理的最快方法是内置的setup命令。它会自动检测已安装的代理并交互式配置它们：

uispec setup          # interactive — prompts for each detected agent
uispec setup --auto   # non-interactive — configures all with project scope

这也会在结束时自动运行 uispec init （跳过 --skip-setup).

支持的代理： 克劳德代码, OpenAI 代码专家, 光标, VS代码（GitHub副本）, 克劳德桌面版.

Manual configuration

如果您更喜欢手动配置代理：

克劳德代码

claude mcp add uispec -- uispec serve

OpenAI 代码专家

codex mcp add uispec -- uispec serve

光标

添加 ~/.cursor/mcp.json （全球）或 .cursor/mcp.json （项目）：

{
  "mcpServers": {
    "uispec": {
      "command": "uispec",
      "args": ["serve"]
    }
  }
}

VS代码（GitHub副本）

添加 .vscode/mcp.json:

{
  "servers": {
    "uispec": {
      "type": "stdio",
      "command": "uispec",
      "args": ["serve"]
    }
  }
}

克劳德桌面版

添加到您的Claude桌面配置(~/Library/Application Support/Claude/claude_desktop_config.json 在macOS上）：

{
  "mcpServers": {
    "uispec": {
      "command": "uispec",
      "args": ["serve"]
    }
  }
}

UISpec寻找 .uispec/config.yaml 在当前目录中。跑 uispec init 一旦进入项目根目录，服务器就会自动获取您的目录。

______________________________________________________________________

CLI参考

uispec init

在当前项目中设置UISpec。写 .uispec/config.yaml，将捆绑的shadcn/ui目录提取到 .uispec/catalogs/shadcn.json，并以交互方式运行代理设置。

uispec init                          # shadcn preset (default)
uispec init --catalog my-catalog.json  # custom catalog path
uispec init --force                  # overwrite existing config
uispec init --skip-setup             # skip AI agent configuration

uispec setup

检测已安装的AI代理，并将其配置为使用UISpec MCP服务器。结束时自动运行 uispec init.

uispec setup          # interactive — prompts for each detected agent
uispec setup --auto   # configure all detected agents with project scope defaults

uispec validate

解析TSX文件，并根据目录验证每个组件的使用情况。出口 0 为了清洁， 2 对于违规行为。

uispec validate src/pages/landing.tsx
uispec validate src/pages/landing.tsx --fix    # apply deterministic fixes in-place
uispec validate src/pages/landing.tsx --json   # machine-readable output
uispec validate src/pages/landing.tsx --catalog path/to/catalog.json

检测到的违规类型：

• 未知组件（不在目录中）
• 缺少导入/导入路径错误
• 无效的道具值（不在允许的枚举中）
• 未知道具（未为组件定义）
• 缺少必需的属性
• 违反成分（例如。 CardContent 外面 Card)
• 弃用的组件或道具

uispec inspect

查找组件的道具、允许值、子组件和指导方针。

uispec inspect Button
uispec inspect Dialog --examples
uispec inspect CardContent --json
uispec inspect Button --catalog path/to/catalog.json

uispec serve

在stdio上启动MCP服务器（由Claude Desktop、Cursor、VS Code和任何兼容MCP的客户端使用）。

uispec serve                                # uses bundled shadcn catalog (zero-config)
uispec serve --log                          # log MCP calls to .uispec/logs/mcp.jsonl
uispec serve --log-file /tmp/uispec.log     # log to a custom path
uispec serve --catalog path/to/custom.json  # use a custom catalog

登录中： 当 --log 或 --log-file 启用后，每个MCP工具调用都会记录为JSONL条目，其中包含工具名称、经过净化的参数、持续时间、响应大小和估计的令牌。可用于调试和提交错误报告。大参数如 code 为了隐私，用字节长度替换。

{"ts":"2026-02-26T12:00:00Z","tool":"validate_page","params":{"auto_fix":false,"code_len":1200},"duration_ms":12,"response_bytes":843,"tokens_est":211,"error":null}

______________________________________________________________________

目录

UISpec附带捆绑包 shadcn/ui 二进制文件中嵌入的目录。跑步 uispec init 将其提取到您的项目中。

当前捆绑目录：

• 7个类别的30个组件（动作、反馈、表单、布局、导航、叠加、数据显示）
• 具有类型、必需标志、默认值和允许值的完整道具模式
• 子组件组成规则（例如。 DialogContent 必须包含 DialogTitle)
• 导入路径、设计令牌、可访问性指南

您还可以将UISpec指向任何手工策划的 catalog.json 使用 --catalog。请参阅 目录格式参考 获取完整的模式、字段描述和自动化提示。

______________________________________________________________________

路线图

______________________________________________________________________

目录格式

UISpec使用开放的JSON模式。您可以将任何组件库的目录交给作者，并指向UISpec。

Minimal catalog.json example

{
  "components": [
    {
      "name": "Button",
      "description": "A clickable button element.",
      "category": "actions",
      "import_path": "@/components/ui/button",
      "imported_names": ["Button"],
      "props": [
        {
          "name": "variant",
          "type": "string",
          "required": false,
          "default": "default",
          "allowed_values": ["default", "destructive", "outline", "ghost"]
        }
      ]
    }
  ],
  "categories": [
    { "name": "actions", "components": ["Button"] }
  ],
  "tokens": [],
  "guidelines": []
}

______________________________________________________________________

贡献

欢迎发布问题和PR。

# Run unit tests
go test ./...

# Run integration tests (builds the binary, tests all 9 MCP tools over stdio)
INTEGRATION=1 go test ./cmd/uispec/... -v

# Lint
go vet ./...

项目结构：

______________________________________________________________________

许可证

麻省理工学院——见 许可证.