aicanvas

@aicanvas/mcp

适用于 AI Canvas 的模型上下文协议服务。让你的 AI 编辑器（Claude Code、Cursor、Claude Desktop、Codex）无需离开聊天界面，即可发现并安装 AI Canvas 组件。

You:   "find me an animated card stack"
AI:    [calls search_components → ranks matches → picks polaroid-stack]
       [calls get_install_command → returns: npx shadcn add @aicanvas/polaroid-stack]
       [runs the command — file lands in your project]
You:   "make the rotation more dramatic"
AI:    [edits the file directly]

提供的功能

共 13 个工具，数据来自 aicanvas.me 的实时注册表。网站添加组件后，MCP 会在几分钟内自动更新。注册表中包含 80 多个独立组件，以及拥有自身组件和模板的 Andromeda 设计系统。

工具	用途
list_categories	显示所有分类及组件数量。方便在深入浏览前了解概况。
list_components	浏览独立组件，可按分类筛选。支持分页。
search_components	在独立组件和设计系统组件中进行模糊关键词搜索（包括 slug、名称、描述、分类和标签）。结果按相关性排序。
get_component	获取一个组件的完整元数据和 .tsx 源代码。支持解析独立组件 slug 和设计系统组件 slug（例如 andromeda-heat-grid）。
get_install_command	获取任意独立组件或设计系统组件对应的 npx shadcn add @aicanvas/<slug> 命令。
list_systems	列出可用的设计系统（例如 Andromeda），并显示组件和模板数量。
get_system	获取整个设计系统的所有文件、共享令牌、组件安装命令和依赖关系链。
list_templates	列出即用型模板（完整示例页面），可按设计系统筛选。
get_template	获取单个模板（即用型组合）的所有文件，以及它引入的注册表依赖项。
get_component_props	获取一个组件的已记录属性：名称、类型、是否必填、默认值和描述。免费使用，无需账户，内容远少于源代码。
validate_usage	根据组件已记录的属性检查文件中的 JSX：检查未知属性、缺少的必填属性、超出属性可选值范围的值，并标注各项所在行号。
compose_page	将一行简要需求转化为构建计划：最匹配的模板、每个部分对应的一个组件及备选方案、安装顺序（令牌优先），以及没有组件覆盖的部分。只生成计划，不生成代码。
get_audit_checklist	检查已完成页面或组件的清单：安装完整性、属性、两种主题、320px 布局、动效清理、键盘操作与对比度、组合方式。

所有工具均为只读，不会修改 AI Canvas 端的任何内容。

最后四个工具适用于以下工作流：先用 compose_page 制定计划，再用 get_component_props 在编写 JSX 前查看各组件的 API，用 validate_usage 检查完成的文件，最后用 get_audit_checklist 检查是否已完成。

独立组件和设计系统组件分别存放。list_components 和 list_categories 仅涵盖 80 多个独立组件，保持目录清晰。设计系统组件可通过 list_systems / get_system 查找，也可以通过 get_component、get_install_command 和 search_components 按 slug 解析。

设置

Claude Desktop

编辑 claude_desktop_config.json：

• macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows： %APPDATA%\Claude\claude_desktop_config.json
• Linux： ~/.config/Claude/claude_desktop_config.json

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

重启 Claude Desktop。工具列表中应会显示 aicanvas 工具。

Cursor

项目级（仓库中的 .cursor/mcp.json）或全局（~/.cursor/mcp.json）：

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

Claude Code

项目级 .mcp.json（与代码一起提交）：

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

也可以通过 CLI 配置：

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

Codex

~/.codex/config.toml：

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

验证是否正常运行

在上述任意 AI 编辑器中询问：

“AI Canvas 有哪些组件类别？”

你应该会看到全部 11 个类别及其数量。如果没有，请检查宿主的 MCP 日志。通常，“Failed to spawn process” 或网络错误意味着 npx 无法获取软件包，或者编辑配置后没有重启宿主。

要在编辑器外检查服务：

npx -y @modelcontextprotocol/inspector npx -y @aicanvas/mcp

这会打开一个浏览器界面，你可以在其中手动调用每个工具。

配置

环境变量	默认值	用途
AICANVAS_REGISTRY_BASE	https://aicanvas.me/r	注册表根 URL。仅在针对可自托管镜像进行本地开发时覆盖。
AICANVAS_TOKEN	(none)	可选的账户专属令牌。网站会将其写入提供给你的 MCP 配置。它用于识别你的 AI Canvas 账户，以授权拉取源代码并解锁你拥有的任何高级内容。每次注册表请求都会以 Bearer 令牌的形式发送。没有该令牌时，你的身份为匿名：仍可浏览元数据，但拉取组件源代码时会收到一条简短的“创建免费账户”提示，而不是代码。

账户和高级内容

浏览元数据（list_categories、list_components、search_components、list_systems、list_templates、get_install_command）免费且无需账户。拉取实际源代码（get_component、get_system、get_template）需要使用免费的 AI Canvas 账户：从你的账户获取 AICANVAS_TOKEN，网站会为你提供现成的配置。没有令牌时，拉取免费组件源代码会收到一条简短的“创建免费账户”提示，而不是代码；高级内容（完整设计系统和模板）则会返回 HTTP 402，并附带 aicanvas.me/pricing 上的升级链接。可随时通过 npx @aicanvas/mcp@latest 更新。

注册表如何保持最新

MCP 会在首次使用时获取 https://aicanvas.me/r/aicanvas-mcp.json，并将其缓存 5 分钟。AI Canvas 上的新组件会自动显示在 MCP 中，无需更新软件包。

每个组件的完整源代码会按需从 /r/<slug>.json 获取（与 CLI 安装的 shadcn 注册表项目相同）。

属性表来自 https://aicanvas.me/r/aicanvas-props.json，并在构建时从每个组件自身的 JSDoc 解析，因此不会与源代码出现偏差。同样缓存 5 分钟。

本地开发

git clone https://github.com/aicanvas-me/aicanvas.git
cd aicanvas/mcp
npm install
npm run build

# Smoke-test against the deployed registry:
npm run inspect

# Or point at a locally running aicanvas dev server:
AICANVAS_REGISTRY_BASE=http://localhost:3000/r node dist/index.js

编辑 src/index.ts，运行 npm run build，然后重启 AI 编辑器。

许可证

MIT，与 AI Canvas 项目相同。