ballmac

@ballmac/mcp

一个面向 Ballmac UI 的 MCP 服务。它让 Claude、Cursor、VS Code、Windsurf、Codex 和任何其他 MCP 客户端都能搜索组件、区块和模板目录，读取条目的属性、键盘行为和源代码，获取准确的安装命令，并使用区块规划完整页面。

它是只读的：只回答问题并返回命令，绝不会写入文件或在你的计算机上运行任何内容。免费目录无需账户或 API 密钥。

安装

该服务通过 npx 运行，因此无需全局安装。需要 Node.js 20 或更高版本。

Claude Code

claude mcp add ballmac -- npx -y @ballmac/mcp

Claude Desktop

将以下内容添加到 claude_desktop_config.json（Settings、Developer、Edit config）：

{
  "mcpServers": {
    "ballmac": {
      "command": "npx",
      "args": ["-y", "@ballmac/mcp"]
    }
  }
}

Cursor

将以下内容添加到项目中的 .cursor/mcp.json，或添加到 ~/.cursor/mcp.json 以供所有项目使用：

{
  "mcpServers": {
    "ballmac": {
      "command": "npx",
      "args": ["-y", "@ballmac/mcp"]
    }
  }
}

VS Code

将以下内容添加到 .vscode/mcp.json：

{
  "servers": {
    "ballmac": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@ballmac/mcp"]
    }
  }
}

Windsurf

将与 Cursor 相同的 mcpServers 区块添加到 ~/.codeium/windsurf/mcp_config.json。

Codex

将以下内容添加到 ~/.codex/config.toml：

[mcp_servers.ballmac]
command = "npx"
args = ["-y", "@ballmac/mcp"]

功能

工具	返回内容
search_items	最符合需求的结果，例如“带附件的聊天输入框”或“在线商店”。可识别常见同义词（modal、navbar、ecommerce）。
list_items	按类型、类别或层级筛选的组件、区块或模板。
list_categories	类别总数及所有类别的数量，让 Agent 了解有哪些内容。
get_item	描述、适用和不适用场景、导入语句、属性、键盘行为、依赖项、模板页面以及完整源代码。
get_examples	条目页面中展示的可运行示例。
get_changes	条目逐个版本的变更内容（使用 since 仅查看较新的变更），以及是否存在破坏性变更。
get_quality_rules	Ballmac 应用需遵循的规则（状态、无障碍、设计令牌、动效、布局），包括规则原因以及正反示例。编写组件前请先阅读。
audit_project	对项目源代码进行只读审计。按严重程度从高到低返回发现项，并为每项提供修复方法。宣布任务完成前请运行此工具。
make_preset	根据描述创建完整的设计系统（颜色、圆角、字体、平台风格、动效），并获取其 16 位代码和安装命令。
get_tests	条目附带的 vitest + Testing Library 测试，用于检查编辑后是否仍能正常运行。
get_install_command	适用于 pnpm、npm、yarn 或 bun 的 shadcn CLI 命令。
compose_page	根据区块生成页面规划，包含正确的顺序、安装命令、page.tsx 脚手架，以及任何现成且适用的完整模板。每个部分都会列出其区块可显示的状态，脚手架则会将数据区块连接到 useResource，并将表单区块连接到由你控制的状态。当请求中提到 macOS、Windows、iOS、Tauri 或 Electron（或你传入 feel）时，还会返回要安装的平台风格及连接说明。
get_setup	项目准备方法（shadcn init、可选主题，以及较旧 CLI 所需的注册表条目）。

资源：ballmac://catalog（包含每个条目及其单行描述）和 ballmac://items/{name}（以 Markdown 格式提供的单个条目）。

提示词：build_page（根据意图规划并构建页面）和 choose_component（查找并连接合适的组件）。

返回列表的工具也会返回结构化内容，以便支持该功能的客户端获取类型化结果。

可以询问的内容

• “使用 Ballmac UI 构建一个包含定价和常见问题解答的 SaaS 落地页。”
• “制作动态收入数字时，我应该使用哪个 Ballmac 组件？”
• “将 Ballmac UI 的登录界面添加到此应用。”
• “Ballmac 是否有在线商店模板？安装它。”

选项

变量	默认值	用途
BALLMAC_UI_URL	https://ui.ballmac.com	要读取的目录，例如网站的本地副本。
BALLMAC_LICENSE_KEY	none	Ballmac UI Pro 许可证密钥。使用该密钥后，get_item 和 get_examples 也会返回 Pro 项目的源代码。

Pro 项目

Pro 项目在搜索结果中显示为 tier: "pro"。它们的安装命令使用 @ballmac-pro 命名空间，而 get_install_command 会返回一行 proSetup，其中包含 shadcn CLI 所需的 components.json 条目。若要让 Agent 读取 Pro 源代码，请将密钥传递给服务：

claude mcp add ballmac --env BALLMAC_LICENSE_KEY=your-licence-key -- npx -y @ballmac/mcp

在 JSON 配置中，在 args 旁添加 "env": { "BALLMAC_LICENSE_KEY": "your-licence-key" }。密钥只会发送到 Ballmac UI 网站。设置指南：ui.ballmac.com/docs/pro。

在终端中可以运行 npx @ballmac/mcp --help 和 --version。

不使用 MCP

Ballmac UI 也是一个标准的 shadcn 注册表，因此官方 shadcn MCP 服务可以浏览它。shadcn CLI 可通过官方注册表目录识别 @ballmac，但该 MCP 服务只会读取 components.json 中列出的注册表，因此请将其添加到该文件中：

npx shadcn@latest registry add @ballmac=https://ui.ballmac.com/r/{name}.json

许可证

MIT