VaneUI

@vaneui/mcp

一个 Model Context Protocol 服务，用于向 AI 编码 Agent 提供 VaneUI 文档。任何支持 MCP 的客户端（Claude Code、Claude Desktop、Cursor、VS Code 等）都可以按需读取组件文档，并通过一次工具调用搜索文档，让 Agent 无需你手动把规则粘贴到提示词中，也能编写正确的 VaneUI 代码。

该服务提供完整的组件参考、入门和自定义指南，以及每个组件的结构化属性表，并包含两个工具：search_docs 和 get_component_props。

要求

• Node.js 24（下面的 npx 命令会为你下载并运行服务）。

快速开始

该服务通过 stdio 运行，并以 @vaneui/mcp 的名称发布到 npm。使用下面的代码片段将其添加到客户端；无需本地克隆或构建。

Claude Code

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

Claude Desktop

编辑你的 claude_desktop_config.json：

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

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

之后重启 Claude Desktop。

Cursor

添加到 ~/.cursor/mcp.json（全局）或 .cursor/mcp.json（单个项目）：

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

VS Code

code --add-mcp '{"name":"vaneui","command":"npx","args":["-y","@vaneui/mcp"]}'

或者添加到 .vscode/mcp.json（注意，VS Code 使用 servers 键）：

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

其他客户端

任何支持 stdio MCP 服务的客户端都可以使用。将 npx 设为命令，并将 -y @vaneui/mcp 设为参数，按照该客户端的配置格式填写即可。

使用方法

连接服务后，只需用自然语言要求它使用 VaneUI 构建。Agent 会自动通过工具获取合适的文档：

• “使用 VaneUI 构建一张定价卡片，包含标题、功能列表和实心主按钮。” → Agent 会读取 card、list 和 button 的属性，并正确组合它们。
• “Chip 的默认外观和变体是什么？” → get_component_props 会返回属性表（Chip 默认使用 secondary + outline，而不是 primary）。
• “如何为每个 Button 设置应用级默认值？” → search_docs 会找到 theme-defaults 指南，并展示 ThemeProvider themeDefaults 模式。
• “VaneUI 中哪个属性对应 flex-1？” → search_docs 会在属性到 Tailwind 的映射中找到答案。

验证是否正常工作

添加服务并重启客户端后：

• 客户端应列出名为 vaneui 的服务，其中包含 search_docs 和 get_component_props 工具（以及 vaneui://docs/* 资源）。
• 如需直接对服务进行冒烟测试，请在终端中运行 npx -y @vaneui/mcp。服务启动后会等待 stdio 输入（MCP stdio 服务没有输出属于正常情况；按 Ctrl+C 退出）。

工具

search_docs

在完整文档语料中进行子串或正则表达式搜索。

参数	类型	说明
query	string	必填。区分大小写。
regex	boolean	可选。如果为 true，则将 query 解析为 JavaScript 正则表达式。默认值为 false。

最多返回 50 条结果，每条包含 uri、slug、lineNumber 和简短的上下文 snippet。在猜测属性名、默认值或类映射之前，请先使用此工具——答案几乎总能在文档中找到。

get_component_props

返回单个组件的结构化属性／类别／默认值／描述表，直接从 @vaneui/ui 的 ComponentCategories、ComponentKeys、defaultTheme 和 PropDescriptions 派生。

参数	类型	说明
slug	string	必填。组件 slug，与资源基本名称一致，例如 button、card、icon-button、page-title。

返回一个 JSON 数组，其中包含 { prop, category, isDefault, description, isCommon } 行。需要获取组件的准确属性列表时可使用此工具（例如，在常见布局属性与组件专属属性之间进行选择，查找某个类别中的默认属性等）。

可用资源

每个文档文件都会作为名为 vaneui://docs/<slug> 的资源公开，其中 <slug> 是小写的源文件名（去掉 .md 扩展名）。所有资源的 mimeType 均为 text/markdown。

示例：

• vaneui://docs/claude — VaneUI 项目概览。
• vaneui://docs/component-usage、vaneui://docs/prop-to-tailwind-mapping、vaneui://docs/component-patterns、vaneui://docs/props-and-theme、vaneui://docs/css-conventions、vaneui://docs/testing、vaneui://docs/e2e-testing、vaneui://docs/playground-examples — 面向 Agent 的规则文件。
• vaneui://docs/installation、vaneui://docs/usage-basics、vaneui://docs/core-concepts — 入门指南。
• vaneui://docs/theming-overview、vaneui://docs/using-theme-provider、vaneui://docs/theme-defaults、vaneui://docs/theme-and-override、vaneui://docs/extra-classes、vaneui://docs/customizing-styles、vaneui://docs/variant-inheritance、vaneui://docs/css-variables — 自定义指南。
• vaneui://docs/common-props — 共享布局／排版属性参考。
• vaneui://docs/button、vaneui://docs/card、vaneui://docs/modal、…… — 每个组件各有一个资源。

---

开发

本节面向为服务器本身工作的贡献者和维护者。

源文件

文档语料库在构建时从两个同级仓库打包而来：

• vaneui/（vaneui/vaneui 的检出副本）—— API 参考和面向 Agent 的规则（CLAUDE.md + .claude/rules/*.md）。
• vaneui-web/（vaneui/web 的检出副本）——叙述性指南和各组件参考，采用纯 Markdown 编写，位于 app/docs/data/**/*.md 下（每个组件一个文件，带有 frontmatter）。

每个 .md 文件都会根据其基本名称放入 resources/（文件名全局唯一，因此语料库是扁平的）。vaneui/ 中的文件会原样复制。vaneui-web/ 页面中的 {% include "x.md" %} 标签会通过 vaneui-web 自己的 include 辅助程序（lib/docs/includes.mjs）展开，因此每个资源都与 vaneui.com 上的页面一致。名称以下划线 _ 开头的文件和目录是供页面引入的局部文件，因此不会各自生成资源。scripts/sync-component-props.mjs 还会读取每个组件的 componentKey frontmatter，并将其与 @vaneui/ui 导出的元数据合并，生成 resources/component-props.json。

构建

resources/ 已提交到 git，因此全新克隆的仓库已经包含服务器运行所需的全部文件。

npm install
npm run build       # tsc only — uses the committed resources/
npm start           # run the built server over stdio

将客户端指向本地构建时，可将 node /absolute/path/to/vaneui-mcp/dist/server.js 设为命令。

重新同步语料库（维护者）

同步脚本要求 vaneui/ 和 vaneui-web/ 是本仓库的同级目录（解析为 ../vaneui 和 ../vaneui-web）。如果它们位于其他位置，可通过 VANEUI_PATH / VANEUI_WEB_PATH 环境变量覆盖。请先在 vaneui-web/ 中运行 npm install，因为其中的 include 助手会从那里加载 @vaneui/md。如果存在缺失或循环引用的 include，同步将会停止。

npm run build:full  # re-sync resources/ from the sibling repos, then tsc

• npm run sync — 宽松同步：将两个源目录中的所有 .md 文件复制到 resources/，并写入 component-props.json。⚠️ 会先清空 resources/；如果缺少同级仓库，生成的资源包将不完整。建议使用 build:full。
• npm run sync:strict — 严格同步：如果缺少任何同级仓库或未找到 MD 文件，则以非零状态退出。由 prepublishOnly 使用。

添加或更新文档

1. 在 vaneui/ 或 vaneui-web/ 中编辑（或创建）源 Markdown 文件：
   • 组件参考：vaneui-web/app/docs/data/<category>/<slug>.md（包含 frontmatter）。
   • 叙述性指南：vaneui-web/app/docs/data/{getting-started,customization,reference}/。
   • Agent 规则：vaneui/.claude/rules/<slug>.md。
2. 运行 npm run build:full 以重新生成 resources/ 并重新编译。
3. 将重新生成的 resources/ 与源文件修改一同提交，然后重启 MCP 客户端。

src/resources.ts 会在启动时读取 resources 目录，因此添加文件时无需修改注册表。

许可证

MIT