v0-mcp-node/README_zh.md

Vercel v0 MCP Server using Node.js and TypeScript - Generate UI components through Claude Code

# v0-mcp

[English](README.md) | [中文](README_zh.md)

Vercel v0 MCP 服务器 for Claude Code - 通过模型上下文协议 (MCP) 使用 AI 生成精美的 UI 组件。

> ✨ **协作开发**: 此项目通过 Claude Code 和 Gemini CLI 使用 Vibe Coding 方法论的创新协作完成 - 展示了 AI 辅助开发流程的强大力量。

## 🎯 功能特点

- **生成 UI 组件**: 从自然语言描述创建 React 组件
- **图像转 UI**: 将设计图转换为可用的 React 代码
- **对话式迭代**: 通过对话逐步完善组件
- **多模型支持**: 支持 v0-1.5-md、v0-1.5-lg 和 v0-1.0-md
- **TypeScript 支持**: 使用 Zod 模式验证的完整类型安全
- **流式支持**: 实时生成进度显示

## 🚀 快速开始

```bash
# 1. 克隆项目并进入目录
git clone <repository-url> && cd v0-mcp

# 2. 安装依赖
npm install

# 3. 创建 .env 文件并添加你的 v0 API 密钥
npm run setup
# 编辑 .env 文件并填入你的 V0_API_KEY

# 4. 构建项目
npm run build

# 5. 添加到 Claude Code（确保你在项目根目录中）
claude mcp add v0-mcp --env V0_API_KEY=$(grep V0_API_KEY .env | cut -d '=' -f2) -- node $(pwd)/dist/main.js

# 6. 开始在 Claude Code 中使用！
# 试试：「嘿 v0-mcp，创建一个带有电子邮件和密码字段的登录表单」
```

## 🛠 安装

### 1. 克隆或下载
```bash
git clone <repository-url>
cd v0-mcp
```

### 2. 安装依赖
```bash
npm install
```

### 3. 设置环境
```bash
npm run setup
# 编辑 .env 文件，填入你的 v0 API 密钥
```

### 4. 构建项目
```bash
npm run build
```

## ⚙️ 配置

### 🔑 获取你的 v0 API 密钥

在配置 v0-mcp 之前，你需要一个 v0 API 密钥：

1. **访问 [v0 Model API 文档](https://vercel.com/docs/v0/model-api)**
2. **登录你的 Vercel 账户**
3. **导航到 API Keys 部分**
4. **生成新的 API 密钥**
5. **复制并安全保存你的密钥**

### 🌐 第三方 API 访问（推荐）

为了增强可靠性和性能，我们推荐使用第三方 API 端点：

**推荐的基础 URL**：`https://api-key.info/v1`

要使用此端点，请在你的 `.env` 文件中设置 `V0_BASE_URL` 环境变量：

```bash
V0_BASE_URL=https://api-key.info/v1
```

**使用第三方端点的优势：**
- ✅ **提高可靠性**和正常运行时间
- ✅ **更好的性能**和响应时间
- ✅ **增强兼容性**，支持各种 API 客户端
- ✅ **一致的 API 行为**，跨不同地区

第三方端点与官方 v0 API 完全兼容，无需更改你现有的 API 密钥或使用模式。

### Claude Code 集成

📖 **快速设置指南 - 选择最适合你的方法**

#### 方法 1: CLI 配置（推荐）

1. **使用 Claude Code CLI 添加 v0-mcp：**
   ```bash
   # 首先导航到你的 v0-mcp 目录
   cd /path/to/your/v0-mcp
   
   # 使用当前目录添加 MCP 服务器
   claude mcp add v0-mcp -- node $(pwd)/dist/main.js
   ```

2. **设置你的 v0 API 密钥：**

   **选项 A: 在 CLI 设置时添加密钥**
   ```bash
   # 添加服务器时包含 API 密钥（在 v0-mcp 目录中运行）
   claude mcp add v0-mcp --env V0_API_KEY=your_api_key_here -- node $(pwd)/dist/main.js
   ```

   **选项 B: 设置后编辑 `.claude.json` 文件**
   
   运行 `claude mcp add` 命令后，编辑生成的 `.claude.json` 文件：
   ```json
   {
     "mcpServers": {
       "v0-mcp": {
         "type": "stdio",
         "command": "node",
         "args": ["/absolute/path/to/your/v0-mcp/dist/main.js"],
         "env": {
           "V0_API_KEY": "your_api_key_here",
           "V0_BASE_URL": "https://api-key.info/v1"
         }
       }
     }
   }
   ```
   
   **选项 C: 系统环境变量（最安全）**
   ```bash
   # 添加到你的 shell 配置文件（.bashrc、.zshrc 等）
   echo 'export V0_API_KEY="your_api_key_here"' >> ~/.zshrc
   
   # 重新加载 shell 配置
   source ~/.zshrc
   ```

3. **验证设置：**
   ```bash
   claude mcp list
   node scripts/verify-claude-code-setup.js
   ```
   
   ✅ **预期输出：**
   ```
   正在验证 v0 API 连接...
   ✓ 在 Claude 配置中找到 v0-mcp 服务器
   ✓ API 密钥已配置
   ✓ 成功连接到 v0 API
   设置完成！你现在可以在 Claude Code 中使用 v0-mcp。
   ```

#### 方法 2: 手动配置（进阶）

1. **创建或编辑 Claude Code 配置文件：**
   - **macOS/Linux**: `~/.claude.json`
   - **Windows**: `%USERPROFILE%\.claude.json`

2. **添加 v0-mcp 服务器配置：**

```json
{
  "mcpServers": {
    "v0-mcp": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/v0-mcp/dist/main.js"],
      "env": {
        "V0_API_KEY": "your_api_key_here",
        "V0_BASE_URL": "https://api-key.info/v1"
      }
    }
  }
}
```

3. **重启 Claude Code** 使更改生效。

#### 验证

配置后，你应该在 Claude Code 中看到可用的 v0-mcp 工具：

- ✅ `v0_generate_ui` - 从文本生成 UI 组件
- ✅ `v0_generate_from_image` - 从图像参考生成 UI  
- ✅ `v0_chat_complete` - 迭代式 UI 开发聊天
- ✅ `v0_setup_check` - 验证 API 连接

### 🔗 为什么使用 MCP（模型上下文协议）？

**MCP 优势：**
- **无缝集成**: 工具在 Claude 中原生显示，无需 API 调用复杂性
- **增强上下文**: Claude 理解你的 v0 工作流程并提供更好的协助
- **即时可用**: 工具在你的编码会话中始终可访问
- **类型安全**: 内建完整的参数验证和错误处理
- **持久状态**: 在工具调用过程中维护对话上下文

**工作原理：**
当你在 Claude 中提及 v0-mcp 或 UI 生成时，工具会自动变为可用。Claude 可以根据你的请求智能选择正确的工具，使开发过程感觉自然且集成。

### Claude Desktop 集成

添加到你的 `claude_desktop_config.json`：

```json
{
  "mcpServers": {
    "v0-mcp": {
      "command": "node",
      "args": ["/path/to/v0-mcp/dist/main.js"],
      "env": {
        "V0_API_KEY": "your_api_key_here",
        "V0_BASE_URL": "https://api-key.info/v1"
      }
    }
  }
}
```

### Cursor 集成

添加到你的 Cursor MCP 配置：

```json
{
  "mcpServers": {
    "v0-mcp": {
      "command": "node",
      "args": ["/path/to/v0-mcp/dist/main.js"],
      "env": {
        "V0_API_KEY": "your_api_key_here",
        "V0_BASE_URL": "https://api-key.info/v1"
      }
    }
  }
}
```

## 🔧 可用工具

### `v0_generate_ui`
从文本描述生成 UI 组件。

**参数：**
- `prompt`（必需）：UI 组件的描述
- `model`：要使用的 v0 模型（默认：v0-1.5-md）
- `stream`：启用流式响应（默认：false）
- `context`：可选的现有代码上下文

### `v0_generate_from_image`
从图像参考生成 UI 组件。

**参数：**
- `imageUrl`（必需）：参考图像的 URL
- `prompt`：额外的指令
- `model`：要使用的 v0 模型（默认：v0-1.5-md）

### `v0_chat_complete`
基于对话上下文的聊天式 UI 开发。

**参数：**
- `messages`（必需）：对话消息数组
- `model`：要使用的 v0 模型（默认：v0-1.5-md）
- `stream`：启用流式响应（默认：false）

### `v0_setup_check`
验证 v0 API 配置和连接。

## 🔑 环境变量

| 变量 | 必需 | 默认值 | 描述 |
|----------|----------|---------|-------------|
| `V0_API_KEY` | ✅ | - | 你的 v0 API 密钥 |
| `V0_BASE_URL` | ❌ | `https://api.v0.dev/v1` | v0 API 基础 URL。**推荐第三方 URL**：`https://api-key.info/v1` |
| `V0_DEFAULT_MODEL` | ❌ | `v0-1.5-md` | 默认使用的模型 |
| `V0_TIMEOUT` | ❌ | `60000` | API 超时时间（毫秒） |
| `MCP_SERVER_NAME` | ❌ | `v0-mcp` | MCP 服务器名称 |
| `LOG_LEVEL` | ❌ | `info` | 日志级别 |

## 🚀 使用示例

### 在 Claude Code 中

配置完成后，你可以通过多种方式使用 v0-mcp：

#### 直接使用 v0-mcp
只需在请求中提及 v0-mcp，Claude 会自动选择合适的工具：
```
嘿 v0-mcp，创建一个现代的登录表单，包含电子邮件和密码字段
```

```
v0-mcp：生成一个带有图表和 KPI 卡片的仪表板组件
```

```
@v0-mcp 将这个线框图转换为 React 组件：[图片 URL]
```

#### 使用特定工具

##### 生成登录表单
```
使用 v0_generate_ui 创建一个现代的登录表单，包含电子邮件、密码字段和带圆角的蓝色提交按钮。
```

##### 将设计转换为代码
```
使用 v0_generate_from_image 处理这个 Figma 设计 URL：https://example.com/design.png
```

##### 迭代开发
```
使用 v0_chat_complete 改进之前的登录表单，添加"记住我"复选框和"忘记密码"链接。
```

##### 检查 API 设置
```
使用 v0_setup_check 验证你的 v0 API 连接和配置。
```

### 进阶使用示例

#### 创建仪表板组件
```
使用 v0_generate_ui 并使用以下提示：
"创建一个现代的仪表板组件，包含侧边栏导航、带用户配置文件下拉菜单的标题，以及用于卡片网格布局的主内容区域。包含显示 KPI 图表的指标卡片。使用 shadcn/ui 组件和 Tailwind CSS。"
```

#### 从线框图构建
```
使用 v0_generate_from_image 处理你的线框图 URL 并添加：
"将此线框图转换为功能完整的 React 组件。添加适当的间距、现代样式，并使其对移动设备响应。"
```

#### 迭代改进
```
使用 v0_chat_complete 并提供对话历史：
[
  {"role": "user", "content": "创建一个定价表组件"},
  {"role": "assistant", "content": "[之前的定价表代码]"},
  {"role": "user", "content": "添加热门计划高亮和年度/月度切换"}
]
```

## 🧪 开发

```bash
# 带热重载的开发模式
npm run dev

# 类型检查
npm run lint

# 运行测试
npm test

# 带覆盖率的测试
npm run test:coverage

# CI 模式测试
npm run test:ci

# 清理构建产物
npm run clean

# 测试配置
npm run test:config

# 测试基本功能
npm run test:basic

# 验证 Claude Code 设置
npm run verify:claude-code
```

## 🛡️ 增强功能

### 结构化日志
- **基于 Winston 的日志记录**，使用 JSON 格式
- API 调用和工具使用的**上下文信息**
- 带堆栈跟踪和元数据的**错误跟踪**
- 通过 `LOG_LEVEL` 环境变量**可配置的日志级别**

### 高级错误处理
- **分类错误类型**（API、网络、超时、速率限制等）
- 针对暂时性错误的**指数退避重试逻辑**
- 带有可操作指导的**用户友好错误消息**
- 用于调试的**全面错误元数据**

### 测试基础设施
- **Jest 测试框架**，支持 TypeScript
- 所有核心组件的**全面单元测试**
- 带可配置阈值的**测试覆盖率报告**
- 外部依赖的**模拟实现**

### 提高可靠性
- 使用 Zod 模式的**输入验证**
- 所有故障模式的**优雅错误处理**
- 带请求计时的**性能监控**
- API 连接的**健康检查**

## 💖 支持此项目

如果你觉得这个项目有帮助，请考虑支持它：

[![Buy Me A Coffee](https://img.shields.io/badge/Buy%20Me%20A%20Coffee-Support-yellow?style=for-the-badge&logo=buy-me-a-coffee)](https://coff.ee/hellolucky)

你的支持有助于维护和改进 v0-mcp！

## 📄 许可证

MIT