1. 项目概述为UI Lab CLI构建一个MCP服务器如果你和我一样每天都在和前端项目打交道从零开始搭建一个功能齐全的UI组件库或应用那么你肯定对重复的脚手架工作感到厌倦。创建项目结构、初始化配置、添加新功能模块……这些工作虽然基础但极其耗时且容易出错。更不用说当你尝试让AI助手比如Claude或Cursor来帮你完成这些任务时它们往往因为缺乏对项目上下文和架构规则的精确理解而“胡言乱语”。这正是rethink-paradigms/ui-labs-mcp这个项目要解决的问题。它是一个基于TypeScript实现的Model Context Protocol服务器专门为ui-lab这个命令行工具服务。简单来说它就像给你的AI助手装上了一套标准化的“机械臂”和“传感器”让Claude或Cursor能够直接、安全、可预测地操作你的UI Lab项目。它不是一个独立的工具而是一座桥梁将LLM的智能与开发者工具的具体执行能力连接起来。无论你是想快速原型验证还是管理一个大型的、架构规范的前端项目这个MCP服务器都能让你的AI工作流从“提建议”升级到“直接动手干”。2. 核心设计思路为什么选择MCP与确定性执行在深入代码之前理解背后的设计哲学至关重要。这个项目不是简单地把CLI命令包装一下而是基于几个核心原则构建的。2.1 拥抱Model Context Protocol标准化而非定制化MCP是一个新兴但迅速被接受的协议它的目标是标准化LLM与外部工具、数据源之间的交互。在它出现之前每个AI工具如Claude Desktop、Cursor、Windsurf都需要为每个外部服务编写特定的集成代码这导致了大量的重复工作和兼容性问题。选择基于MCP构建意味着这个服务器天生就具备了与任何支持MCP的客户端兼容的能力。今天它服务于Claude和Cursor明天如果VSCode Copilot或新的AI IDE也支持MCP那么你的ui-lab工具就能立即被它们调用。这避免了为每个平台重复开发适配器的痛苦是一种面向未来的设计。注意MCP的核心通信机制是通过标准输入输出进行的这使得服务器可以是一个独立的进程与客户端解耦极大地提升了稳定性和安全性。2.2 确定性与可靠性让AI成为可靠的合作者项目文档中特别强调了“All operations are deterministic”。这是本项目设计的基石也是与许多其他AI代码生成工具的本质区别。确定性在这里意味着给定相同的输入参数如项目路径、功能名称ui_lab_init或ui_lab_add_feature工具总是会产生完全相同的输出和项目结构变化。这消除了LLM输出中固有的随机性对构建过程的影响。为什么这如此重要可重复性无论是你手动执行还是AI助手执行或是CI/CD流水线执行结果都是一致的。这为自动化测试和部署铺平了道路。可调试性如果出了问题你可以精确地复现步骤因为过程没有随机性。信任建立开发者可以放心地将项目脚手架这类关键任务交给AI因为你知道它不会即兴发挥而是严格遵循预设的、经过验证的规则。这种确定性是通过将ui-labCLI 的逻辑封装在MCP工具中实现的。AI助手只是“触发”了这些工具真正的“施工蓝图”和“操作规程”都写在CLI里。2.3 类型安全全覆盖从接口到执行整个项目使用TypeScript构建并深度集成Zod模式验证库。这带来了从开发时到运行时的一致性安全网工具输入验证每个MCP工具接收的参数都通过Zod Schema进行严格校验。如果AI助手错误地传递了一个非法的路径格式或缺少必填参数请求会在执行前就被拒绝并返回清晰的错误信息而不是导致CLI在项目中执行一半崩溃。结构化输出每个工具都返回结构化的JSON数据如{ success: boolean; message: string; }。这使得AI助手能够以编程化的方式解析结果并根据成功或失败决定后续动作而不是去费力地解析一段模糊的自然语言文本。资源类型安全项目配置、功能注册表等“资源”的读取也具备完整的类型定义确保AI助手获取到的项目元数据格式是已知且可靠的。这种端到端的类型安全将许多潜在的运行时错误转移到了编译时或请求验证时极大地提升了整个系统的健壮性。3. 架构与核心模块深度解析让我们拆开这个MCP服务器的内部结构看看各个模块是如何协同工作的。理解这部分有助于你进行二次开发或深度定制。3.1 整体数据流与职责分离项目的架构图清晰地展示了一个分层模型这是一个经典的责任链模式[LLM Agent (Claude/Cursor)] ↓ (发起JSON-RPC请求 via stdio) [MCP Server (本项目)] ↓ (封装参数调用CLI) [ui-lab CLI (底层工具)] ↓ (执行文件操作) [你的项目文件系统]交互层LLM代理客户端通过标准输入输出与MCP服务器通信使用的是MCP协议定义的JSON-RPC格式。协议转换层MCP服务器是核心。它使用官方modelcontextprotocol/sdk注册工具和资源。当收到一个工具调用请求如ui_lab_add_feature时它执行以下操作参数解析与验证利用Zod校验传入的projectPath,featureName等参数。环境准备解析路径确保项目目录存在等。调用执行器将验证后的参数传递给cli-executor模块。结果处理捕获CLI执行的标准输出、错误流和退出码将其格式化为MCP协议规定的结构化响应。执行层cli-executor模块使用Node.js的child_process.spawn或execa库来以子进程方式运行ui-lab这个二进制文件。这是关键的一步它将不可信的、可能包含复杂逻辑的CLI执行与MCP服务器进程隔离。效果层ui-labCLI 根据其内部逻辑实际在指定的项目路径上创建目录、文件、更新配置文件等。这种分离确保了MCP服务器本身的轻量和稳定它不包含具体的业务逻辑只负责协议适配、安全校验和进程调度。3.2 核心模块工具、资源与工具函数工具模块在src/tools/index.ts中你会看到所有8个CLI命令被注册为MCP工具。每个工具的定义包括名称如ui_lab_init。描述给AI助手看的自然语言说明描述这个工具的作用。输入模式一个JSON Schema对象由Zod Schema转换而来定义了参数的类型、是否必需、描述等。这是AI助手理解如何调用该工具的“说明书”。处理函数一个异步函数接收验证后的参数调用cli-executor并返回结构化结果。资源模块资源是MCP中用于“读取”数据的机制。在src/resources/index.ts中注册了三个资源ui-lab://project-config读取项目的lab.config.json。ui-lab://feature-registry读取llm/feature-registry.json这是一个由ui-lab维护的、列出所有功能的索引文件。ui-lab://feature-capabilities读取某个特定功能下的capabilities.json该文件描述了该功能提供的组件、API等“能力”。资源URI可以包含查询参数如projectPath。当AI助手需要了解项目上下文时例如用户问“我的项目里有什么功能”它可以“读取”这些资源就像浏览器访问一个URL一样从而获得结构化的项目信息而不是盲目猜测。工具函数模块cli-executor.ts这是与系统交互的核心。它需要处理很多边缘情况超时控制防止CLI命令挂起。正确处理缓冲区避免大量输出导致内存问题。将CLI的非零退出码转换为有意义的错误信息。在Windows和Unix系统上处理路径和命令的差异。path-helpers.ts包含路径解析、规范化、存在性检查等实用函数。确保无论用户传入的是绝对路径、相对路径还是带有~的路径都能被正确解析为绝对路径这是后续所有文件操作的基础。4. 从零开始的完整实操指南假设你是一个前端开发者手头有一个基于ui-lab架构规范的新项目想法现在想利用AI助手来加速开发。以下是完整的设置和使用流程。4.1 环境准备与项目初始化首先你需要确保基础环境就绪。安装Node.js和pnpm确保你的系统安装了Node.js 18或更高版本。我推荐使用nvm来管理Node版本。包管理器选择pnpm因为它更快且节省磁盘空间。# 检查Node版本 node --version # 安装pnpm (如果未安装) npm install -g pnpm获取MCP服务器代码你需要将ui-labs-mcp服务器部署到你的本地或开发环境中。# 克隆仓库 git clone repository-url /path/to/your/workspace/ui-labs-mcp cd /path/to/your/workspace/ui-labs-mcp # 安装依赖 pnpm install # 编译TypeScript代码 pnpm run build编译成功后会在项目根目录生成dist文件夹其中包含可执行的mcp-server.js。请记下这个文件的绝对路径例如/Users/yourname/workspace/ui-labs-mcp/dist/mcp-server.js。准备你的AI客户端这里以Claude Desktop和Cursor为例。为Claude Desktop配置 找到你的Claude Desktop配置文件所在位置文档中已给出各系统路径。编辑或创建claude_desktop_config.json文件。{ mcpServers: { ui-lab: { command: node, args: [ /Users/yourname/workspace/ui-labs-mcp/dist/mcp-server.js ] } } }关键提示args中的路径必须是绝对路径。相对路径会导致Claude无法找到服务器。保存后完全退出并重启Claude Desktop配置才会生效。为Cursor配置 在你的项目根目录你希望AI助手在其中操作UI Lab项目的那个目录下创建或编辑.cursor/mcp.json文件。{ mcpServers: { ui-lab: { command: node, args: [ /Users/yourname/workspace/ui-labs-mcp/dist/mcp-server.js ] } } }这样配置后只有当你打开这个特定项目时Cursor才会加载ui-labMCP服务器。重启Cursor或重新加载窗口即可。4.2 实战与AI助手协同构建项目配置完成后你就可以开始与AI对话让它替你执行繁琐的命令了。场景一创建全新项目你可以在Claude Desktop的聊天窗口中直接输入“在/Users/yourname/projects/my-saas-app目录下为我初始化一个新的UI Lab项目。”Claude会识别出这个请求匹配ui_lab_init工具并自动调用它。你会在聊天记录中看到类似这样的结构化回复工具调用ui_lab_init 参数{“projectPath”: “/Users/yourname/projects/my-saas-app”} 结果{ “success”: true, “message”: “UI Lab project initialized successfully at /Users/yourname/projects/my-saas-app. Created lab.config.json and base directories.” }同时你的文件系统中/Users/yourname/projects/my-saas-app目录下会自动生成lab.config.json和标准化的子目录结构。场景二为项目添加新功能模块假设你要为这个SaaS应用添加一个“用户认证”模块。你可以对AI说“在项目/Users/yourname/projects/my-saas-app中添加一个名为 ‘auth’ 的功能路由设置为 ‘/login’。”AI助手会调用ui_lab_add_feature工具。这个工具背后的CLI命令会执行一系列操作在features/目录下创建auth/文件夹。在auth/下创建标准化的子目录components/,hooks/,lib/,types/,pages/等。在llm/目录下更新feature-registry.json注册这个新功能。在auth/目录下生成一个capabilities.json文件描述这个功能模块的初始能力。根据lab.config.json中的框架设置如Next.js, Remix可能还会更新路由配置文件。整个过程你无需手动敲击任何命令行也无需记忆复杂的目录结构规则。场景三检查项目健康状态在添加了几个功能后你可以让AI帮你做一次“体检”“检查一下项目/Users/yourname/projects/my-saas-app的结构是否符合架构规则。”AI会调用ui_lab_check工具。这个工具会运行CLI的验证逻辑检查诸如每个功能目录是否包含所有必需的子目录。feature-registry.json是否与磁盘上的功能目录同步。共享模型目录 (shared/models/core/) 中的类型定义是否被正确引用。 返回的结果会明确告诉你hasErrors是true还是false并在message中列出具体问题。4.3 高级用法利用资源进行上下文感知MCP的资源机制让AI助手能“看见”你的项目。你可以进行如下对话你“我这个项目里现在有哪些功能”AI助手内部操作读取ui-lab://feature-registry?projectPath...资源AI回复“根据项目注册表你目前拥有以下功能1.auth(认证)2.dashboard(仪表板)3.billing(计费)。每个功能都包含对应的组件和页面。”你“我想了解一下auth功能具体能做什么。”AI助手内部操作读取ui-lab://feature-capabilities?projectPath...featureNameauth资源AI回复“auth功能目前提供了以下能力LoginForm组件、useAuth钩子、User类型定义以及/login和/register页面。你可以让我基于这些能力为你生成或修改代码。”通过这种方式AI助手不再是“盲人摸象”而是具备了项目级的上下文感知能力从而能给出更精准、更相关的建议和操作。5. 开发、调试与故障排除实录如果你想基于这个MCP服务器进行二次开发或者在使用中遇到了问题以下是我的实战经验。5.1 开发模式与热重载项目使用tsx来在开发时直接运行TypeScript源码这非常方便。pnpm run dev运行此命令后MCP服务器会启动并监听标准输入。但是在开发时你需要一个方法来测试它。你不能总是通过重启Claude来测试。我推荐使用MCP官方提供的mcp-cli工具或一个简单的测试脚本。创建一个test-client.js文件import { StdioClient } from modelcontextprotocol/sdk/client/stdio.js; import { spawn } from child_process; const serverProcess spawn(node, [dist/mcp-server.js]); const client new StdioClient( { name: test-client, version: 1.0.0 }, { command: node, args: [dist/mcp-server.js] } ); await client.connect(); // 列出所有工具 const { tools } await client.listTools(); console.log(Available tools:, tools.map(t t.name)); // 调用一个工具 const result await client.callTool({ name: ui_lab_init, arguments: { projectPath: /tmp/test-project } }); console.log(Tool result:, result); await client.close(); serverProcess.kill();这个脚本可以模拟客户端连接和调用是迭代开发时的利器。5.2 常见问题与排查清单即使按照步骤操作你也可能会遇到一些坑。下面是我遇到过的典型问题及其解决方法。问题现象可能原因排查步骤与解决方案Claude/Cursor中看不到ui-lab工具1. 配置文件路径错误。2. MCP服务器未成功编译。3. 路径权限问题。1.绝对路径检查再三确认claude_desktop_config.json或.cursor/mcp.json中的路径指向编译后的dist/mcp-server.js并且路径正确无误。在终端中使用ls -la /完整/路径/dist/mcp-server.js验证文件存在。2.编译验证运行pnpm run build后检查dist/目录下是否有.js文件并且没有TypeScript编译错误。3.重启客户端修改配置后必须完全退出并重启Claude Desktop或Cursor仅刷新页面通常无效。4.查看客户端日志Claude Desktop有时会在其标准输出启动它的终端中打印MCP连接错误日志。Cursor可以在输出面板查看日志。调用工具时报“Project not initialized”在调用ui_lab_add_feature等工具前没有在目标路径初始化项目。这是一个逻辑错误。确保你的操作顺序是先ui_lab_init再执行其他操作。MCP服务器只是传递命令项目初始化的状态由底层的ui-labCLI 检查。工具执行成功但项目文件无变化1.projectPath参数指向了错误目录。2. CLI命令在子进程中执行失败但被静默处理。1. 仔细检查传入的projectPath。在调用工具前可以尝试让AI助手先读取project-config资源来确认路径正确。2. 在开发时可以在cli-executor.ts中增加更详细的日志打印出实际执行的命令和子进程的stderr输出即使命令退出码为0。Windows系统下路径错误Windows使用反斜杠\和盘符而Node.js和JSON有时处理不当。1. 在配置文件的args中尝试使用正斜杠/或双反斜杠\\。2. 确保在path-helpers.ts中使用了Node.js的path模块如path.resolve()来处理路径它能跨平台工作。3. 在服务器代码中对所有用户输入的路径都执行path.resolve()进行标准化。“权限被拒绝”错误dist/mcp-server.js文件没有执行权限或者Node进程没有在目标项目路径的写入权限。1. 在Unix系统上运行chmod x dist/mcp-server.js赋予执行权限。2. 确保运行Claude/Cursor的用户对目标项目目录有读写权限。5.3 性能与稳定性优化心得在实际生产环境中使用这类MCP服务器时有几点经验值得分享进程生命周期管理MCP服务器是常驻进程。确保你的cli-executor正确处理了子进程的退出和资源清理避免僵尸进程累积。使用execa库通常比原生child_process更安全因为它提供了更好的Promise接口和清理机制。超时控制某些CLI操作如安装依赖可能耗时很长。为工具调用设置合理的超时时间例如30秒并在超时后向客户端返回明确的错误而不是让请求一直挂起。错误处理与用户反馈不要仅仅把子进程的stderr原样返回。尝试解析错误信息将其转化为对用户或AI更友好的提示。例如将“ENOENT: no such file or directory”转化为“目标项目目录不存在请检查路径是否正确”。资源读取的缓存feature-registry.json和capabilities.json这类资源可能在短时间内被AI助手频繁读取以理解上下文。可以考虑在服务器内存中添加一个短时间的缓存例如5秒减少不必要的磁盘I/O。但要注意缓存失效问题当ui_lab_add_feature等工具执行后应使相关缓存失效。这个项目展示了一个非常清晰的范式如何将一个领域特定的CLI工具通过MCP协议安全、可控地暴露给AI智能体。它解决了AI编码中“最后一公里”的问题——从生成代码建议到直接操作项目环境。通过确定性的工具、类型安全的接口和项目感知的资源它极大地提升了开发者与AI协同工作的效率和可靠性。如果你正在构建或使用一套内部开发工具并希望引入AI助手参考这个项目的设计模式将是一个极佳的起点。
基于MCP协议为UI Lab CLI构建AI代理服务器：实现确定性前端项目自动化
1. 项目概述为UI Lab CLI构建一个MCP服务器如果你和我一样每天都在和前端项目打交道从零开始搭建一个功能齐全的UI组件库或应用那么你肯定对重复的脚手架工作感到厌倦。创建项目结构、初始化配置、添加新功能模块……这些工作虽然基础但极其耗时且容易出错。更不用说当你尝试让AI助手比如Claude或Cursor来帮你完成这些任务时它们往往因为缺乏对项目上下文和架构规则的精确理解而“胡言乱语”。这正是rethink-paradigms/ui-labs-mcp这个项目要解决的问题。它是一个基于TypeScript实现的Model Context Protocol服务器专门为ui-lab这个命令行工具服务。简单来说它就像给你的AI助手装上了一套标准化的“机械臂”和“传感器”让Claude或Cursor能够直接、安全、可预测地操作你的UI Lab项目。它不是一个独立的工具而是一座桥梁将LLM的智能与开发者工具的具体执行能力连接起来。无论你是想快速原型验证还是管理一个大型的、架构规范的前端项目这个MCP服务器都能让你的AI工作流从“提建议”升级到“直接动手干”。2. 核心设计思路为什么选择MCP与确定性执行在深入代码之前理解背后的设计哲学至关重要。这个项目不是简单地把CLI命令包装一下而是基于几个核心原则构建的。2.1 拥抱Model Context Protocol标准化而非定制化MCP是一个新兴但迅速被接受的协议它的目标是标准化LLM与外部工具、数据源之间的交互。在它出现之前每个AI工具如Claude Desktop、Cursor、Windsurf都需要为每个外部服务编写特定的集成代码这导致了大量的重复工作和兼容性问题。选择基于MCP构建意味着这个服务器天生就具备了与任何支持MCP的客户端兼容的能力。今天它服务于Claude和Cursor明天如果VSCode Copilot或新的AI IDE也支持MCP那么你的ui-lab工具就能立即被它们调用。这避免了为每个平台重复开发适配器的痛苦是一种面向未来的设计。注意MCP的核心通信机制是通过标准输入输出进行的这使得服务器可以是一个独立的进程与客户端解耦极大地提升了稳定性和安全性。2.2 确定性与可靠性让AI成为可靠的合作者项目文档中特别强调了“All operations are deterministic”。这是本项目设计的基石也是与许多其他AI代码生成工具的本质区别。确定性在这里意味着给定相同的输入参数如项目路径、功能名称ui_lab_init或ui_lab_add_feature工具总是会产生完全相同的输出和项目结构变化。这消除了LLM输出中固有的随机性对构建过程的影响。为什么这如此重要可重复性无论是你手动执行还是AI助手执行或是CI/CD流水线执行结果都是一致的。这为自动化测试和部署铺平了道路。可调试性如果出了问题你可以精确地复现步骤因为过程没有随机性。信任建立开发者可以放心地将项目脚手架这类关键任务交给AI因为你知道它不会即兴发挥而是严格遵循预设的、经过验证的规则。这种确定性是通过将ui-labCLI 的逻辑封装在MCP工具中实现的。AI助手只是“触发”了这些工具真正的“施工蓝图”和“操作规程”都写在CLI里。2.3 类型安全全覆盖从接口到执行整个项目使用TypeScript构建并深度集成Zod模式验证库。这带来了从开发时到运行时的一致性安全网工具输入验证每个MCP工具接收的参数都通过Zod Schema进行严格校验。如果AI助手错误地传递了一个非法的路径格式或缺少必填参数请求会在执行前就被拒绝并返回清晰的错误信息而不是导致CLI在项目中执行一半崩溃。结构化输出每个工具都返回结构化的JSON数据如{ success: boolean; message: string; }。这使得AI助手能够以编程化的方式解析结果并根据成功或失败决定后续动作而不是去费力地解析一段模糊的自然语言文本。资源类型安全项目配置、功能注册表等“资源”的读取也具备完整的类型定义确保AI助手获取到的项目元数据格式是已知且可靠的。这种端到端的类型安全将许多潜在的运行时错误转移到了编译时或请求验证时极大地提升了整个系统的健壮性。3. 架构与核心模块深度解析让我们拆开这个MCP服务器的内部结构看看各个模块是如何协同工作的。理解这部分有助于你进行二次开发或深度定制。3.1 整体数据流与职责分离项目的架构图清晰地展示了一个分层模型这是一个经典的责任链模式[LLM Agent (Claude/Cursor)] ↓ (发起JSON-RPC请求 via stdio) [MCP Server (本项目)] ↓ (封装参数调用CLI) [ui-lab CLI (底层工具)] ↓ (执行文件操作) [你的项目文件系统]交互层LLM代理客户端通过标准输入输出与MCP服务器通信使用的是MCP协议定义的JSON-RPC格式。协议转换层MCP服务器是核心。它使用官方modelcontextprotocol/sdk注册工具和资源。当收到一个工具调用请求如ui_lab_add_feature时它执行以下操作参数解析与验证利用Zod校验传入的projectPath,featureName等参数。环境准备解析路径确保项目目录存在等。调用执行器将验证后的参数传递给cli-executor模块。结果处理捕获CLI执行的标准输出、错误流和退出码将其格式化为MCP协议规定的结构化响应。执行层cli-executor模块使用Node.js的child_process.spawn或execa库来以子进程方式运行ui-lab这个二进制文件。这是关键的一步它将不可信的、可能包含复杂逻辑的CLI执行与MCP服务器进程隔离。效果层ui-labCLI 根据其内部逻辑实际在指定的项目路径上创建目录、文件、更新配置文件等。这种分离确保了MCP服务器本身的轻量和稳定它不包含具体的业务逻辑只负责协议适配、安全校验和进程调度。3.2 核心模块工具、资源与工具函数工具模块在src/tools/index.ts中你会看到所有8个CLI命令被注册为MCP工具。每个工具的定义包括名称如ui_lab_init。描述给AI助手看的自然语言说明描述这个工具的作用。输入模式一个JSON Schema对象由Zod Schema转换而来定义了参数的类型、是否必需、描述等。这是AI助手理解如何调用该工具的“说明书”。处理函数一个异步函数接收验证后的参数调用cli-executor并返回结构化结果。资源模块资源是MCP中用于“读取”数据的机制。在src/resources/index.ts中注册了三个资源ui-lab://project-config读取项目的lab.config.json。ui-lab://feature-registry读取llm/feature-registry.json这是一个由ui-lab维护的、列出所有功能的索引文件。ui-lab://feature-capabilities读取某个特定功能下的capabilities.json该文件描述了该功能提供的组件、API等“能力”。资源URI可以包含查询参数如projectPath。当AI助手需要了解项目上下文时例如用户问“我的项目里有什么功能”它可以“读取”这些资源就像浏览器访问一个URL一样从而获得结构化的项目信息而不是盲目猜测。工具函数模块cli-executor.ts这是与系统交互的核心。它需要处理很多边缘情况超时控制防止CLI命令挂起。正确处理缓冲区避免大量输出导致内存问题。将CLI的非零退出码转换为有意义的错误信息。在Windows和Unix系统上处理路径和命令的差异。path-helpers.ts包含路径解析、规范化、存在性检查等实用函数。确保无论用户传入的是绝对路径、相对路径还是带有~的路径都能被正确解析为绝对路径这是后续所有文件操作的基础。4. 从零开始的完整实操指南假设你是一个前端开发者手头有一个基于ui-lab架构规范的新项目想法现在想利用AI助手来加速开发。以下是完整的设置和使用流程。4.1 环境准备与项目初始化首先你需要确保基础环境就绪。安装Node.js和pnpm确保你的系统安装了Node.js 18或更高版本。我推荐使用nvm来管理Node版本。包管理器选择pnpm因为它更快且节省磁盘空间。# 检查Node版本 node --version # 安装pnpm (如果未安装) npm install -g pnpm获取MCP服务器代码你需要将ui-labs-mcp服务器部署到你的本地或开发环境中。# 克隆仓库 git clone repository-url /path/to/your/workspace/ui-labs-mcp cd /path/to/your/workspace/ui-labs-mcp # 安装依赖 pnpm install # 编译TypeScript代码 pnpm run build编译成功后会在项目根目录生成dist文件夹其中包含可执行的mcp-server.js。请记下这个文件的绝对路径例如/Users/yourname/workspace/ui-labs-mcp/dist/mcp-server.js。准备你的AI客户端这里以Claude Desktop和Cursor为例。为Claude Desktop配置 找到你的Claude Desktop配置文件所在位置文档中已给出各系统路径。编辑或创建claude_desktop_config.json文件。{ mcpServers: { ui-lab: { command: node, args: [ /Users/yourname/workspace/ui-labs-mcp/dist/mcp-server.js ] } } }关键提示args中的路径必须是绝对路径。相对路径会导致Claude无法找到服务器。保存后完全退出并重启Claude Desktop配置才会生效。为Cursor配置 在你的项目根目录你希望AI助手在其中操作UI Lab项目的那个目录下创建或编辑.cursor/mcp.json文件。{ mcpServers: { ui-lab: { command: node, args: [ /Users/yourname/workspace/ui-labs-mcp/dist/mcp-server.js ] } } }这样配置后只有当你打开这个特定项目时Cursor才会加载ui-labMCP服务器。重启Cursor或重新加载窗口即可。4.2 实战与AI助手协同构建项目配置完成后你就可以开始与AI对话让它替你执行繁琐的命令了。场景一创建全新项目你可以在Claude Desktop的聊天窗口中直接输入“在/Users/yourname/projects/my-saas-app目录下为我初始化一个新的UI Lab项目。”Claude会识别出这个请求匹配ui_lab_init工具并自动调用它。你会在聊天记录中看到类似这样的结构化回复工具调用ui_lab_init 参数{“projectPath”: “/Users/yourname/projects/my-saas-app”} 结果{ “success”: true, “message”: “UI Lab project initialized successfully at /Users/yourname/projects/my-saas-app. Created lab.config.json and base directories.” }同时你的文件系统中/Users/yourname/projects/my-saas-app目录下会自动生成lab.config.json和标准化的子目录结构。场景二为项目添加新功能模块假设你要为这个SaaS应用添加一个“用户认证”模块。你可以对AI说“在项目/Users/yourname/projects/my-saas-app中添加一个名为 ‘auth’ 的功能路由设置为 ‘/login’。”AI助手会调用ui_lab_add_feature工具。这个工具背后的CLI命令会执行一系列操作在features/目录下创建auth/文件夹。在auth/下创建标准化的子目录components/,hooks/,lib/,types/,pages/等。在llm/目录下更新feature-registry.json注册这个新功能。在auth/目录下生成一个capabilities.json文件描述这个功能模块的初始能力。根据lab.config.json中的框架设置如Next.js, Remix可能还会更新路由配置文件。整个过程你无需手动敲击任何命令行也无需记忆复杂的目录结构规则。场景三检查项目健康状态在添加了几个功能后你可以让AI帮你做一次“体检”“检查一下项目/Users/yourname/projects/my-saas-app的结构是否符合架构规则。”AI会调用ui_lab_check工具。这个工具会运行CLI的验证逻辑检查诸如每个功能目录是否包含所有必需的子目录。feature-registry.json是否与磁盘上的功能目录同步。共享模型目录 (shared/models/core/) 中的类型定义是否被正确引用。 返回的结果会明确告诉你hasErrors是true还是false并在message中列出具体问题。4.3 高级用法利用资源进行上下文感知MCP的资源机制让AI助手能“看见”你的项目。你可以进行如下对话你“我这个项目里现在有哪些功能”AI助手内部操作读取ui-lab://feature-registry?projectPath...资源AI回复“根据项目注册表你目前拥有以下功能1.auth(认证)2.dashboard(仪表板)3.billing(计费)。每个功能都包含对应的组件和页面。”你“我想了解一下auth功能具体能做什么。”AI助手内部操作读取ui-lab://feature-capabilities?projectPath...featureNameauth资源AI回复“auth功能目前提供了以下能力LoginForm组件、useAuth钩子、User类型定义以及/login和/register页面。你可以让我基于这些能力为你生成或修改代码。”通过这种方式AI助手不再是“盲人摸象”而是具备了项目级的上下文感知能力从而能给出更精准、更相关的建议和操作。5. 开发、调试与故障排除实录如果你想基于这个MCP服务器进行二次开发或者在使用中遇到了问题以下是我的实战经验。5.1 开发模式与热重载项目使用tsx来在开发时直接运行TypeScript源码这非常方便。pnpm run dev运行此命令后MCP服务器会启动并监听标准输入。但是在开发时你需要一个方法来测试它。你不能总是通过重启Claude来测试。我推荐使用MCP官方提供的mcp-cli工具或一个简单的测试脚本。创建一个test-client.js文件import { StdioClient } from modelcontextprotocol/sdk/client/stdio.js; import { spawn } from child_process; const serverProcess spawn(node, [dist/mcp-server.js]); const client new StdioClient( { name: test-client, version: 1.0.0 }, { command: node, args: [dist/mcp-server.js] } ); await client.connect(); // 列出所有工具 const { tools } await client.listTools(); console.log(Available tools:, tools.map(t t.name)); // 调用一个工具 const result await client.callTool({ name: ui_lab_init, arguments: { projectPath: /tmp/test-project } }); console.log(Tool result:, result); await client.close(); serverProcess.kill();这个脚本可以模拟客户端连接和调用是迭代开发时的利器。5.2 常见问题与排查清单即使按照步骤操作你也可能会遇到一些坑。下面是我遇到过的典型问题及其解决方法。问题现象可能原因排查步骤与解决方案Claude/Cursor中看不到ui-lab工具1. 配置文件路径错误。2. MCP服务器未成功编译。3. 路径权限问题。1.绝对路径检查再三确认claude_desktop_config.json或.cursor/mcp.json中的路径指向编译后的dist/mcp-server.js并且路径正确无误。在终端中使用ls -la /完整/路径/dist/mcp-server.js验证文件存在。2.编译验证运行pnpm run build后检查dist/目录下是否有.js文件并且没有TypeScript编译错误。3.重启客户端修改配置后必须完全退出并重启Claude Desktop或Cursor仅刷新页面通常无效。4.查看客户端日志Claude Desktop有时会在其标准输出启动它的终端中打印MCP连接错误日志。Cursor可以在输出面板查看日志。调用工具时报“Project not initialized”在调用ui_lab_add_feature等工具前没有在目标路径初始化项目。这是一个逻辑错误。确保你的操作顺序是先ui_lab_init再执行其他操作。MCP服务器只是传递命令项目初始化的状态由底层的ui-labCLI 检查。工具执行成功但项目文件无变化1.projectPath参数指向了错误目录。2. CLI命令在子进程中执行失败但被静默处理。1. 仔细检查传入的projectPath。在调用工具前可以尝试让AI助手先读取project-config资源来确认路径正确。2. 在开发时可以在cli-executor.ts中增加更详细的日志打印出实际执行的命令和子进程的stderr输出即使命令退出码为0。Windows系统下路径错误Windows使用反斜杠\和盘符而Node.js和JSON有时处理不当。1. 在配置文件的args中尝试使用正斜杠/或双反斜杠\\。2. 确保在path-helpers.ts中使用了Node.js的path模块如path.resolve()来处理路径它能跨平台工作。3. 在服务器代码中对所有用户输入的路径都执行path.resolve()进行标准化。“权限被拒绝”错误dist/mcp-server.js文件没有执行权限或者Node进程没有在目标项目路径的写入权限。1. 在Unix系统上运行chmod x dist/mcp-server.js赋予执行权限。2. 确保运行Claude/Cursor的用户对目标项目目录有读写权限。5.3 性能与稳定性优化心得在实际生产环境中使用这类MCP服务器时有几点经验值得分享进程生命周期管理MCP服务器是常驻进程。确保你的cli-executor正确处理了子进程的退出和资源清理避免僵尸进程累积。使用execa库通常比原生child_process更安全因为它提供了更好的Promise接口和清理机制。超时控制某些CLI操作如安装依赖可能耗时很长。为工具调用设置合理的超时时间例如30秒并在超时后向客户端返回明确的错误而不是让请求一直挂起。错误处理与用户反馈不要仅仅把子进程的stderr原样返回。尝试解析错误信息将其转化为对用户或AI更友好的提示。例如将“ENOENT: no such file or directory”转化为“目标项目目录不存在请检查路径是否正确”。资源读取的缓存feature-registry.json和capabilities.json这类资源可能在短时间内被AI助手频繁读取以理解上下文。可以考虑在服务器内存中添加一个短时间的缓存例如5秒减少不必要的磁盘I/O。但要注意缓存失效问题当ui_lab_add_feature等工具执行后应使相关缓存失效。这个项目展示了一个非常清晰的范式如何将一个领域特定的CLI工具通过MCP协议安全、可控地暴露给AI智能体。它解决了AI编码中“最后一公里”的问题——从生成代码建议到直接操作项目环境。通过确定性的工具、类型安全的接口和项目感知的资源它极大地提升了开发者与AI协同工作的效率和可靠性。如果你正在构建或使用一套内部开发工具并希望引入AI助手参考这个项目的设计模式将是一个极佳的起点。
