shadcn/ui CLI 的 MCP Server 实战解析让 AI 助手直接搜索、查看与安装 Registry 组件【免费下载链接】uiA set of beautifully-designed, accessible components and a code distribution platform. Works with your favorite frameworks. Open Source. Open Code.项目地址: https://gitcode.com/GitHub_Trending/ui/uishadcn/ui 的 CLI 内置了一个基于 Model Context ProtocolMCP的服务器它把 Registry 的搜索、浏览、查看与安装能力封装成 7 个标准化工具供 Claude Code、Cursor、VS Code 等 AI 客户端直接调用。本文以仓库中 skills/shadcn/mcp.md 的官方说明为主体结合 MCP 服务器源码实现 与 CLI 的 mcp 命令完整讲清它的接入方式、每个工具的输入输出契约、components.json中的 Registry 配置规则以及工具调用在源码层面的真实执行路径帮助你把组件选型和安装流程无缝交给 AI 完成。一、MCP Server 是什么与 CLI 的关系在 shadcn/ui 的工作流中组件以源码形式通过 CLI 添加到用户项目npx shadcnlatest add button而组件来源是各种 Registry。当用户用 AI 助手开发时助手需要回答三类问题有哪些组件可用这个组件长什么样、怎么用怎么安装MCP Server 正是为这三类问题提供的程序化接口——它本身不做项目初始化或主题配置只覆盖 Registry 操作。从源码结构看服务器实现在 packages/shadcn/src/mcp/index.ts使用modelcontextprotocol/sdk的Server构建声明了logging、resources、tools三种能力// packages/shadcn/src/mcp/index.ts export const server new Server( { name: shadcn, version: 1.0.0, }, { capabilities: { logging: {}, resources: {}, tools: {}, }, } )所有工具描述通过zod定义入参 schema 并转换为 JSON Schema 暴露给客户端zodToJsonSchema工具调用由统一的handleCallTool分发处理。值得注意的是源码中专门处理了 GitHub 认证通知由于 stdio 通道被协议占用认证信息通过 MCP 的 logging 能力发送给客户端而不是打印到控制台// stdout 承载协议console 不可用认证通知走 logging 通道 async function onGitHubAuthNotice(message: string) { try { await server.sendLoggingMessage({ level: info, data: message }) } catch { console.error(message) } }另外仓库中保留了旧的shadcn registry:mcp命令见 packages/shadcn/src/commands/registry/mcp.ts——它已被标记为DEPRECATED执行时只会提示改用shadcn mcp因此新接入一律使用mcp命令。二、接入配置shadcn mcp与shadcn mcp init文档给出的启动方式只有两条命令shadcn mcp # start the MCP server (stdio) shadcn mcp init # write config for your editorshadcn mcp以 stdio 传输启动服务器支持-c, --cwd cwd指定工作目录默认为当前目录。在 命令实现中可以看到它启动前的一个关键动作// packages/shadcn/src/commands/mcp.ts .action(async (options) { await loadEnvFiles(options.cwd) // 先加载 .env 文件 const transport new StdioServerTransport() await server.connect(transport) })这里调用的 loadEnvFiles 会按.env.local、.env.development.local、.env.development、.env的顺序读取项目环境文件。这就是后文 Registry 配置中${VAR}环境变量占位符能被解析的机制来源——即使 token 只存在于.env文件而没有导出为系统环境变量MCP Server 启动时也能取到。shadcn mcp init负责把服务器注册到各编辑器。官方支持的客户端与配置文件对应关系如下与源码中CLIENTS数组一一对应Editor配置文件说明Claude Code.mcp.json写入mcpServers.shadcnCursor.cursor/mcp.json写入mcpServers.shadcnVS Code.vscode/mcp.json写入servers.shadcn注意键名不同OpenCodeopencode.json写入mcp.shadcn含$schema与enabled: trueCodex~/.codex/config.toml手动只能打印指引不能直接写入生成后的配置内容以 Claude Code 为例{ mcpServers: { shadcn: { command: npx, args: [shadcnlatest, mcp] } } }Codex 的配置则是 TOML 格式shadcn mcp init --client codex会安装依赖并提示手动追加到~/.codex/config.toml[mcp_servers.shadcn] command npx args [shadcnlatest, mcp]写入逻辑见 runMcpInit它先读取已有配置文件用deepmerge与目标客户端的配置合并数组采用覆盖策略再写回并自动创建缺失的父目录因此重复执行mcp init不会破坏编辑器里已有的其他 MCP 服务器配置。--client取值限定为claude, cursor, vscode, codex, opencode不指定时会交互式询问。三、七个工具的完整输入契约MCP Server 暴露 7 个工具工具名在客户端中会带上shadcn:前缀。官方文档同时强调了一条重要边界Tip:MCP tools handle registry operations (search, view, install). For project configuration (aliases, framework, Tailwind version), usenpx shadcnlatest info— there is no MCP equivalent.即项目级配置查询别名、框架、Tailwind 版本没有 MCP 对应物AI 助手必须回到 CLI 的info命令。以下按工具逐一说明输入契约以 源码中的 zod schema 为准。3.1shadcn:get_project_registries返回components.json中配置的 Registry 名称列表。输入无。若项目根目录不存在components.json工具不会抛错中断而是返回指导性文本提示先用init命令创建components.json或手动在其中写入registries段。成功时除了列出 Registry 名称还会附带npx shadcnlatest view shadcn等后续操作建议命令帮助 AI 决定下一步动作。3.2shadcn:list_items_in_registries列出 Registry 中的全部条目。Registry 可以是components.json中配置的命名空间如acme、形如owner/repo的公开 GitHub 源或直接给出 Registry 目录 URL。输入参数参数类型必填说明registriesstring[]否要列出的 Registry 名称数组省略时列出components.json中配置的全部 Registrytypesstring[]否按条目类型过滤如[ui, block]limitnumber否返回上限默认 100源码 schema 中明确use 0 for no limit即传 0 表示不限制offsetnumber否分页跳过的条目数输出由 formatSearchResultsWithPagination 格式化带Found N items matching ...头部、Showing items x-y of N区间、每个条目的类型/描述/所属 Registry并在hasMore为真时追加More items available. Use offset: N to see the next page.的分页提示——这套文本是专门为 LLM 阅读设计的让助手能自主翻页。3.3shadcn:search_items_in_registries跨 Registry 的模糊搜索是最高频的工具例如让 AI “帮我找一个 hero”。搜索范围同样由registries参数决定省略即搜索全部已配置 Registry。输入参数参数类型必填说明registriesstring[]否要搜索的 Registry省略为全部已配置querystring是模糊匹配条目名称与描述的查询串typesstring[]否类型过滤如[ui, block]limitnumber否默认 1000 为不限offsetnumber否分页偏移两个源码层面的行为细节值得注意类型校验与 CLI 完全一致。合法的types取值来自 SEARCHABLE_TYPES即registryItemTypeSchema的全部选项去掉registry:example、registry:internal等内部类型后的短名形式如ui、block。传入未知类型时工具返回isError: true并列出合法类型对应实现见 findUnknownTypesMessage。全量搜索时容错继续。省略registries时源码设置continueOnError: true某个 Registry 加载失败不会使整个搜索失败而是在结果末尾追加Skipped N registries that failed to load:及逐个失败原因。该行为有专门的单元测试覆盖见 utils.test.ts 中formatSkippedRegistries用例。3.4shadcn:view_items_in_registries查看条目详情包含完整文件内容。输入items(string[]) —— 必须带 Registry 前缀如[shadcn/button, shadcn/card, owner/repo/item]。内部调用getRegistryItems拉取条目输出经 formatRegistryItems 组织为 Markdown 结构标题、描述、**Type:**、文件数量、**Dependencies:**与**Dev Dependencies:**。若一个条目都找不到会返回带纠正提示的文本提醒补全shadcn/button这类前缀。3.5shadcn:get_item_examples_from_registries查找用法示例与 demo返回完整源码。省略registries时搜索全部已配置 Registry。输入参数类型必填说明registriesstring[]否省略为全部已配置querystring是示例查询如accordion-demo、button example该工具的实现是“搜索 拉取”两步先searchRegistries找到匹配的示例条目再对其addCommandArgument调用getRegistryItems取回全量文件最后由 formatItemExamples 把每个示例渲染成## Example: name段落并把有content的文件以### Code (path):加 tsx 代码块的形式完整展开。源码 schema 中还给出了推荐查询模式{item-name}-demo、{item-name} example、example {item-name}。搜不到时返回的提示文本会引导 AI 转用search_items_in_registries或view_items_in_registries形成工具间的自引导闭环。3.6shadcn:get_add_command_for_items返回 CLI 安装命令。输入items(string[]) —— 如[shadcn/button]。实现很直接把 items 拼进npx shadcnlatest add ...并返回具体 runner 由 npxShadcn 按项目实际的 package manager 生成。注意这是“返回命令”而非代为执行——真正落地安装仍由 AI 助手在用户终端中跑 CLI 完成这与 shadcn 一贯的“安装交给 CLI、保证 import 重写与依赖安装”的边界一致。3.7shadcn:get_audit_checklist输入无。返回一份组件验证检查清单源码中的原文包括确认导入正确named vs default imports若使用next/image确认next.config.js的images.remotePatterns配置正确确认所有依赖已安装检查 lint 错误与警告检查 TypeScript 错误如果可用使用 Playwright MCP 做验证。工具描述明确建议“在创建或生成代码文件之后、所有步骤完成时调用”把它当作 AI 工作流的收尾自检环节。四、Registry 配置components.json的registries段上面所有工具里registries参数的解析最终都落到components.json。官方文档给出的配置示例如下可直接照抄{ registries: { acme: https://acme.com/r/{name}.json, private: { url: https://private.com/r/{name}.json, headers: { Authorization: Bearer ${MY_TOKEN} } } } }两条形式并存值是 URL 字符串公开 Registry或{ url, headers }对象需要鉴权的私有 Registry。规则有四点命名必须以开头如acme、privateURL 必须包含{name}占位符CLI 用具体条目名替换后请求${VAR}引用从环境变量解析——对应上文shadcn mcp启动时loadEnvFiles读取.env文件的行为token 可以只写在项目.env中shadcnRegistry 是内置的无需配置即可使用。此外还有一类零配置来源公开的 GitHub Registry。只要仓库根目录存在registry.jsonowner/repo可直接作为 Registry 源使用不必写入components.json。这一点在工具描述中也反复出现如view_items_in_registries的示例输入owner/repo/item。社区 Registry 索引则由本仓库自身的 Registry 端点提供apps/v4站点下的r/registries.json路由目录即对外发布该索引可用于发现公开可用的社区 Registry。五、一次典型调用的源码路径以“AI 助手搜索 button 并生成安装命令”为例shadcn:search_items_in_registries在 handleCallTool 中的执行链是用 zod 校验入参registries、query、types、limit、offsetfindUnknownTypesMessage(args.types)校验类型过滤值getMcpConfig(process.cwd())读取当前目录components.json的registries段useCache: false保证读到最新配置resolveSearchRegistries(args.registries ?? [], config)解析出目标 Registry 列表空列表时直接返回“请先配置 Registry”的引导文本searchRegistries(...)执行搜索limit缺省补 100continueOnError取决于是否为全量搜索空结果返回换词建议有结果则格式化为带分页提示的文本并追加被跳过 Registry 的失败说明。整个CallToolRequestSchema处理被withRegistryContext包裹以注入 GitHub 认证上下文异常统一转为 MCP 错误文本返回而非崩溃zod 校验失败返回逐条字段错误RegistryError会附带 suggestion与上下文 JSON其他错误返回Error: message。所有分支均以isError: true标记方便客户端区分。测试侧utils.test.ts 覆盖了分页头部、区间钳制如Showing items 21-25 of 25、hasMore分页提示、未知类型报错文案、跳过 Registry 的提示等。其中还有一处值得注意的诚实记录测试用it.fails标注了一个已知缺陷——formatSearchResultsWithPagination中npxShadcn是异步函数但插值时未await导致条目行里的 “Add command” 一度渲染为[object Promise]。这提示使用者MCP 返回文本中的命令字符串建议复制前先人工核对 runner 前缀或直接用get_add_command_for_items获取权威安装命令。六、组合成完整工作流与适用边界把 7 个工具串起来AI 助手处理“加一个登录卡片”的完整流程是get_project_registries—— 确认项目配置了哪些 Registry也用于探测components.json是否存在search_items_in_registriesquery: login可加types: [block]—— 在全部已配置 Registry 中模糊搜索view_items_in_registriesitems: [shadcn/...]—— 查看条目构成与依赖get_item_examples_from_registriesquery: login example—— 获取完整示例源码作为生成参考get_add_command_for_items—— 生成npx shadcnlatest add ...命令由助手在终端执行完成安装get_audit_checklist—— 安装后按清单核对导入、依赖、lint 与 TypeScript。适用边界需要说清楚前提是项目根目录存在components.json通常由npx shadcnlatest init生成。没有它时各工具会返回引导文本而非报错但搜索与列出功能无法工作传输协议为 stdio适合本地 AI 客户端不适合作为远程 HTTP 服务暴露MCP 只覆盖 Registry 操作。别名、框架、baseradix/base、Tailwind 版本等项目配置查询仍须走 CLI 的info命令文档与 skills/shadcn/SKILL.md 中都明确把二者分工SKILL 文件负责“项目上下文 编码规则”MCP 负责“组件检索与安装”。这套设计的实际效果是AI 助手不再需要猜测组件名或手写安装命令而是通过结构化工具拿到 Registry 的权威数据条目、文件内容、示例、依赖清单再交由 CLI 完成源码落盘——Registry 生态的可发现性与 AI 工作流由此打通。【免费下载链接】uiA set of beautifully-designed, accessible components and a code distribution platform. Works with your favorite frameworks. Open Source. Open Code.项目地址: https://gitcode.com/GitHub_Trending/ui/ui创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考