Ark UI MCP Server 完全指南：为 AI 助手接入组件、示例与文档的七个工具与配置实战

前端UI组件设计系统【免费下载链接】arkUnstyled, accessible UI components for your design System. Works in React, Vue, Solid, and Svelte.项目地址https://gitcode.com/gh_mirrors/ar/ark点击查看免费下载本文聚焦 Ark UI 官方推出的 MCPModel Context Protocol服务器包ark-ui/mcp它让 Claude、Cursor 等 AI 助手能够直接查询 Ark UI 的组件清单、可运行示例、组件 Props、样式指南与官方文档。读完本文你将掌握该 MCP 服务器的工具清单与参数语义、在 Claude Desktop / Cursor 中的接入配置、其 stdio 与 HTTP 两种传输架构以及每个工具背后的源码实现与数据来源。一、Ark UI MCP Server 是什么Ark UI 是一套无样式unstyled、可访问accessible的 UI 组件库同一套组件同时支持 React、Vue、Svelte 与 Solid.js 四个框架。而ark-ui/mcp是它的官方 MCP 服务器package.json职责是把 Ark UI 的知识库暴露给 AI 助手让助手在生成界面代码时不再凭空猜测而是基于真实、可运行的组件 API 与示例。从 README 看该服务器提供的核心能力有五类组件发现Component Discovery列出任一框架下所有可用的 Ark UI 组件示例检索Example Retrieval获取完整、可直接运行的代码示例文档搜索Documentation Search按关键词检索文档并可拉取整页内容样式指南Styling Guides读取 CSS 变量与 data 属性支撑自定义主题多框架支持Multi-Framework统一覆盖 React、Vue、Svelte 和 Solid.js。换句话说当 AI 需要为你的设计系统生成一个 Dialog、Select 或 DatePicker 时它会先调用 MCP 工具拿到该组件真实的 Props 定义和官方示例代码再据此生成贴合 Ark UI 惯例的实现而不是输出一段似是而非的通用组件代码。二、服务器实现与两种传输架构MCP 服务器的核心实例在 server.ts 中创建名为ark-ui通过modelcontextprotocol/sdk的McpServer声明了prompts、resources、tools三项能力其中tools是本次部署的全部重点。从 tsup.config.ts 可以看到该包构建产物包含两个入口src/stdio.ts与src/http.ts分别对应两种运行形态2.1 stdio 模式本地进程stdio.ts 是默认入口逻辑非常直接先initializeTools(server)注册全部工具再通过StdioServerTransport与宿主进程建立基于标准输入/输出的 JSON-RPC 通信。package.json中的bin字段将ark-ui-mcp指向打包产物dist/stdio.js因此通过npx启动客户端时实际拉起的就是这个进程。2.2 HTTP 模式远程服务http.ts 基于 Express 5 实现了两种 HTTP 传输Streamable HTTP现代方式POST /mcp用于初始化与请求处理通过请求头mcp-session-id复用已建立的会话新会话由randomUUID()生成 sessionId并在onsessioninitialized回调中登记到内存 MapGET /mcp与DELETE /mcp则分别用于会话的续传与关闭http.ts。Legacy SSE兼容旧客户端GET /sse建立事件流客户端随后通过POST /messages?sessionId...回发消息http.ts。服务器端口由环境变量PORT控制未设置时默认监听3000。值得注意的是HTTP 模式下每个会话都会读取请求头x-api-key并作为ToolConfig.apiKey传给工具层详见下文工具注册机制这为未来接入需要鉴权的数据源预留了扩展点。三、在 Claude Desktop / Cursor 中接入官方在 README 中给出了标准配置——在客户端的 MCP 配置文件中声明ark-ui服务器即可npx会自动拉取并启动ark-ui/mcp{ mcpServers: { ark-ui: { command: npx, args: [-y, ark-ui/mcp] } } }这段配置适用于 Claude Desktop 与 Cursor 等支持 MCP 的桌面客户端客户端通过 stdio 与本服务器进程通信随后就能在对话中调用下文介绍的七个工具。对于需要以 HTTP 方式远程部署的场景例如团队共享一台 MCP 网关可参考package.json中的脚本本地开发用bun run servetsx --watch src/http.ts热重载正式构建用bun run buildtsup 打包两个入口并赋予dist/stdio.js可执行权限。四、七个内置工具总览工具注册清单定义在 tools/index.ts共七个。下表汇总了每个工具的输入参数与返回内容参数类型均以 Zod schema 在注册时声明工具名必填参数参数说明返回内容list_componentsframework枚举值react/vue/svelte/solid见 types.ts该框架下全部组件名称列表list_examplesframework,component组件名由预加载清单校验该组件可用的示例 ID 列表get_exampleframework,component,exampleIdexampleId可通过list_examples得到完整示例代码含每个文件的npmDependenciesget_component_propsframework,component同上该组件在该框架下的 Props 详情styling_guidecomponent无需指定框架样式信息跨框架一致组件的dataAttr与cssVar映射外加针对性样式笔记search_docsquery非空关键词如composition、initial focus匹配页面列表slug、标题、描述、分类get_docsslug文档页 slug如components/dialog、guides/composition该页完整 Markdown 内容其中framework参数的合法值由 types.ts 中的常量FRAMEWORKS [react, vue, svelte, solid]统一定义并通过z.enum在工具注册时转成输入 Schema非法框架名会直接被模型拒绝从而保证参数在源头就合法。五、组件发现与示例获取list_components / list_examples / get_example5.1 list_components摸清某个框架的组件全貌list-components.ts 的输入只有framework一个参数底层调用fetchComponentList(framework)返回string[]组件名数组并序列化为 JSON 文本返回给模型。它是后续所有按组件查询的工具的入口索引。5.2 list_examples枚举组件的示例清单list-examples.ts 的输入是frameworkcomponent返回该组件在此框架下的示例 ID 列表。一个值得注意的实现细节是它在ctx()预加载阶段就以react为默认框架拉取了一次组件清单并把清单作为component参数的z.enum可选值——这意味着模型在调用时无法传入任意字符串只能从真实组件名中选择从源头杜绝了拼写错误导致的无效请求。5.3 get_example拉取完整可运行代码get-example.ts 是示例链路的关键一环输入framework、component、exampleId。根据 types.ts 中的响应类型定义返回结构为{ id: 示例 ID, framework: react, component: dialog, files: [ { name: dialog.demo.tsx, content: 完整源码..., npmDependencies: [ark-ui/react, react] } ] }files数组中的每个文件都自带npmDependencies字段AI 助手拿到示例后可以据此补全依赖声明生成真正能安装、能运行的项目代码而不是一段缺少依赖的半成品。5.4 数据来源抓取层如何工作以上三个工具最终都汇聚到 fetch.ts它是整个 MCP 服务器的数据访问层。核心是一个泛型fetchJsonT封装fetch.ts所有请求指向官方文档站点提供的公共 API 基址源码第 12 行的API_BASE请求失败非 2xx时抛出带状态码的错误信息。对应的 API 端点映射如下工具请求端点相对API_BASElist_components/types/{framework}get_component_props/types/{framework}/{component}list_examples/examples/{framework}/{component}get_example/examples/{framework}/{component}/{exampleId}styling_guide/style-guide/{component}search_docs/docs?q{关键词}get_docs/docs/{slug}这些端点与官网站点中 API 目录 下的types、examples、docs、search、style-guide路由一一对应也就是说 MCP 服务器并不内置任何组件知识而是作为转发层实时读取官网内容——这保证了模型拿到的一直是最新的组件 API 与示例而不是打包时固化的快照。六、组件属性查询get_component_propsget-component-props.ts 用于查询某个组件在某个框架下有哪些 Props。它同样以 React 组件清单预构建component参数的枚举校验底层调用getComponentProps({ framework, component })该函数在 fetch.ts 中会把返回的原始 Props 对象包装成带framework与component上下文的响应{ framework: react, component: select, props: { name: ..., type: ..., default: ... } }在 Ark UI 的设计中同一组件在不同框架下的 Props 命名存在差异例如 React 采用 camelCase 事件Vue 则可能表现为事件发射因此必须按框架分别查询。AI 助手可先用它确认某个 Props 是否存在、默认值是什么再生成使用该 Props 的代码避免编造不存在的属性。七、样式定制styling_guide 与内置样式笔记Ark UI 是无样式组件库样式完全交给使用者因此如何拿到组件的样式挂载点是关键。styling_guide工具的返回由两部分拼接而成见 styling-guide.ts从公共 API/style-guide/{component}拉取的dataAttr与cssVar映射类型定义见 types.ts——即每个组件部位part暴露的data-*属性与--*CSS 变量源码内置的customGuides补充笔记styling-guide.ts针对复杂组件给出手写的样式指引。这部分内置笔记极具实战价值举几个代表Collapsible / Accordion提示通过--height、--width变量做高度/宽度动画并直接附上可复用的slideDown/slideUpkeyframesstyling-guide.tsToast给出 Root 部位必须包含的完整样式——translate: var(--x) var(--y)、scale: var(--scale)、z-index: var(--z-index)等以及按data-stateopen/closed区分进入与退出的过渡时长styling-guide.tsTooltip / Tour / Select / Popover / Menu / Hover-card / Combobox共用popperStyleGuide说明--arrow-size、--arrow-background如何设置箭头--available-width/--available-height代表视口可用空间--transform-origin用于基于放置位置的原点感知动画styling-guide.tsSlider提示 Thumb 的定位样式position/left/top/transform由组件自动注入用户无需重复编写styling-guide.tsTree View通过--depth变量实现层级缩进附上calc(var(--depth) * var(--padding-inline))的推荐写法styling-guide.tsProgress区分 circular 与 linear 两种形态分别给出--size/--thickness变量与 indeterminate 状态下的关键帧动画建议styling-guide.ts。这些笔记让模型即使不看官网也能写出符合组件运行机制的样式代码例如漏掉 Toast 的translate: var(--x) var(--y)会导致通知不移动是该工具相比简单文档检索最大的增值点。八、文档检索search_docs 与 get_docs文档类工具构成一对先搜索、再读取的工作流search-docs.ts接收非空关键词query返回匹配页面的元信息数组每个条目包含slug、title、description、category与url类型见 types.ts。工具的description明确引导模型先用本工具拿 slug再用get_docs拉全文。get-docs.ts接收slug直接返回整页 Markdown 文本示例 slug 如components/dialog、guides/composition。get_docs的返回值直接以原始 Markdown 内容作为文本块返回不做二次加工保证了信息的完整性而search_docs的输出里category字段还能帮助模型判断这是组件文档、指南还是其他类型从而决定是否需要继续深挖。这套组合与 website 搜索端点 的实现对应适合处理如何组合多个组件这类需要查整篇文档的问题。九、工具注册机制ctx 预加载与去重缓存最后从 tools/index.ts 看整体注册流程理解工具是如何被装载到 MCP 服务器上的initializeTools(server, config?)遍历工具数组先用tool.disabled?.(config)过滤被禁用的工具当前所有工具均未声明disabled但config.apiKey的传入为此留好了钩子对每个工具执行可选的tool.ctx?.()预加载上下文——如前所述list_examples、get_example、get_component_props、styling_guide都会在此时以 React 组件清单构建component参数的枚举校验通过模块级registeredToolCacheMap做注册去重避免重复初始化最后调用tool.exec(server, ...)把工具及其 Zod 输入 Schema 注册进McpServer。这种先加载上下文、再注册工具的设计意味着工具的输入 Schema 是动态生成的——组件清单一旦更新新组件会立即出现在模型可选的枚举值中无需重启服务端代码。这也是该 MCP 服务器能长期保持与官网组件库同步的根本原因。十、本地构建与开发仓库使用 Bun 作为包管理器根目录存在 bun.lock。在packages/mcp目录下可用的脚本见 package.jsonbun run buildtsup 打包src/stdio.ts与src/http.ts为 ESM 产物并给dist/stdio.js添加可执行权限bun run devtsup watch 模式改动即时重编译bun run serve以tsx --watch热重载运行src/http.ts用于本地调试 HTTP 形态的服务器。运行时依赖方面该包仅依赖modelcontextprotocol/sdk提供 McpServer、stdio/SSE/Streamable HTTP 传输、expressHTTP 服务与zod参数 Schema核心逻辑零业务依赖充分说明它只是一个轻量的官方知识代理。十一、许可证与发布状态ark-ui/mcp以 MIT 许可证开源README 标注 MIT Chakra Systemspackage.json中publishConfig.access设为public可正常发布到 npm 供npx -y ark-ui/mcp直接拉取使用。当前仓库中的包版本为 1.3.0所有源码均可从 packages/mcp/src 目录继续深入研读。结语Ark UI MCP Server 的价值在于它把AI 生成 UI 代码从记忆驱动的猜测升级为数据驱动的查询——组件清单、示例源码、Props 定义、样式挂载点和整页文档全部以结构化工具的形式提供给模型。无论你是想让 Claude Desktop 写出的代码更贴合 Ark UI 惯例还是计划自建一套基于官网 API 的组件知识代理本文介绍的工具清单、参数语义、传输架构与源码实现都可以作为直接可用的参考。赞分享前端UI组件设计系统【免费下载链接】arkUnstyled, accessible UI components for your design System. Works in React, Vue, Solid, and Svelte.项目地址https://gitcode.com/gh_mirrors/ar/ark点击查看免费下载相关推荐Nuxt UI MCP Server 接入指南让 AI 编程助手直接调用组件库的 12 个工具与 3 个提示词Nuxt UI MCP Server 接入指南让 AI 编程助手直接调用组件库的 12 个工具与 3 个提示词 Nuxt UIThe Intuitive V前端UI组件Ghost Downloader 3 上手指南快速跑通下载器Ghost Downloader 3 上手指南快速跑通下载器 Ghost Downloader 3 是一个多协议下载工具直链、磁力、FTP、M3U8 到 B桌面应用网络AntDesign Blazor 文档 MCP为 AI 编码工具接入组件文档与示例源码查询服务AntDesign Blazor 文档 MCP为 AI 编码工具接入组件文档与示例源码查询服务 AntDesign.Docs.MCP 是 Ant DesignUI组件前端上一篇前端性能优化实战基于Lighthouse指标的优化指南下一篇CANN/GECopyKvCache KV缓存拷贝函数创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考