Vercel AI SDK MCP Server Project

Vercel AI SDK MCP 服务项目

此代码仓库包含一个模型上下文协议（MCP）服务，旨在向 Cursor 等 AI 开发环境提供 Vercel AI SDK Core 的功能。它支持使用 generateObject、generateText、streamText 和 UI 生成等功能，还可与其他 MCP 服务（例如通过 Smithery 提供的 mcp-figma 和 magic-mcp）配合使用。

核心功能

• Vercel AI SDK 集成： 提供封装 Vercel AI SDK 核心函数（generate_object、generate_ui_component 等）的 MCP 工具。
• 工具分类： 实现了一个 ToolManager，并提供 set_tool_category 元工具，以管理向 Cursor 暴露的活动工具数量，确保其保持在合理范围内。
• Figma/Magic MCP 占位项： 包含 mcp-figma 和 magic-mcp 的占位连接器和工具注册，计划通过 Cursor AI 进行编排（路径 2）。
• 支持通过 Smithery 部署： 配置了 Dockerfile 和 smithery.yaml，便于在 Smithery.ai 上部署。
• Cursor 集成： 设计为通过 .cursor/mcp.json 配置在 Cursor 中使用。

架构方案（路径 2 编排）

此服务主要设计为由 Cursor 中的 AI 编排的多 MCP 工作流中的一个组件（路径 2）。

预期工作流如下：

1. 使用提示词和 Cursor 规则（.cursor/rules/）引导 AI。
2. 依次调用不同的 MCP 服务：
   • 使用 mcp-figma（通过 Smithery）提取设计。
   • 使用 magic-mcp（通过 Smithery）获取灵感并构建组件。
   • 使用此 vercel-ai-sdk-mcp 服务处理 Vercel AI SDK 特定任务（例如结构化生成）。
3. AI 汇总各步骤中的上下文，以实现最终目标。

代码中存在一个展示服务间直接交互的组合工具（generate_enhanced_component_from_figma）（路径 1），位于 src/integrations/crossIntegration.ts；但要使用它，需要在连接器中实现功能完整的 MCP 客户端，因此这并非此设置的主要预期使用模式。

前置条件

• Node.js（推荐 v20 或更高版本）
• npm
• Git
• Cursor
• Smithery 账号（用于部署）
• API 密钥：
  • OpenAI API 密钥（必需）
  • Figma API 密钥（实现 Figma 集成时必需）
  • 21st Dev API 密钥（实现 Magic MCP 集成时必需）

本地设置

1. 克隆代码仓库：

   git clone https://github.com/chiziuwaga/vercel-ai-sdk-mcp-project.git
   cd vercel-ai-sdk-mcp-project
   

2. 安装依赖项：

   npm install
   

3. 创建 .env 文件： 将 .env.example 复制为 .env，并填写 API 密钥：

   OPENAI_API_KEY=sk-your-openai-key
   ANTHROPIC_API_KEY=sk-ant-your-anthropic-key # 可选
   FIGMA_API_KEY=your-figma-key              # 后续实现时使用
   TWENTY_FIRST_API_KEY=your-21st-key        # 后续实现时使用
   TRANSPORT_TYPE=stdio                      # 本地使用时保持为 stdio
   PORT=3000                                 # 仅在 TRANSPORT_TYPE=sse 时使用
   

4. 构建代码：

   npm run build
   

5. 在本地运行：

   npm run start
   

   服务将通过 stdio 运行，并等待连接。

Cursor 集成（本地）

要在 Cursor 中使用本地服务：

1. 确保可通过本地 npx 运行 mcp-figma 和 magic-mcp。

2. 修改工作区的 .cursor/mcp.json，使用 Node 直接运行此服务：

   {
     "mcpServers": {
       "magic-mcp": { ... }, // 保留现有 Smithery 配置
       "mcp-figma": { ... }, // 保留现有 Smithery 配置
       "vercel-ai-sdk-mcp": {
         "command": "node",
         "args": ["dist/index.js"], // 相对于工作区根目录的路径
         "env": { // 本地运行时直接传入密钥
           "OPENAI_API_KEY": "${OPENAI_API_KEY}",
           "ANTHROPIC_API_KEY": "${ANTHROPIC_API_KEY}",
           "FIGMA_API_KEY": "${FIGMA_API_KEY}",
           "TWENTY_FIRST_API_KEY": "${TWENTY_FIRST_API_KEY}",
           "TRANSPORT_TYPE": "stdio"
         }
       }
     }
   }
   

3. 确保 Cursor 能从你的环境中读取 ${API_KEY} 变量。

使用示例（路径 2）

1. 确保 MCP 服务正在运行（在本地运行，或通过 .cursor/mcp.json 中的 Smithery 配置）。

2. 创建 Cursor 规则： 在 .cursor/rules/ 中添加规则文件，以指导 AI（参见下文）。

3. 向 Cursor AI 提示： 提供类似前文所述用户故事的多步骤提示，指示 AI 依次调用 mcp-figma、magic-mcp 和 vercel-ai-sdk-mcp 中的工具。

   示例片段：

   "首先，使用 mcp-figma 的 extract_figma_design……然后，使用 magic-mcp 的灵感工具……最后，使用 vercel-ai-sdk-mcp 的 generate_ui_component，并结合上下文……"
   

Cursor 规则（.cursor/rules/）

要有效使用路径 2 的编排方式，需要为 Cursor AI 创建指导规则。你必须在项目根目录中创建 .cursor/rules/ 目录，并添加规则文件（例如，figma.cursorule、magic.cursorule、vercel.cursorule）。

• 这些文件应包含自然语言说明，内容包括：
  • 针对特定任务，使用各 MCP 服务中的哪些工具。
  • 如何组织这些工具的提示词。
  • 如何在连续的工具调用之间传递上下文（数据）。
  • 标准工作流（例如，Figma -> Magic -> Vercel）。

有关语法和示例，请参阅 Cursor 规则文档。

部署（Smithery）

1. 推送到 GitHub： 确保已将最新代码（包括 Dockerfile 和 smithery.yaml）推送到 GitHub 上的 main 分支。
2. 前往 Smithery.ai： 登录并查找/添加你的 chiziuwaga/vercel-ai-sdk-mcp-project 服务。
3. 部署： 前往“Deployments”选项卡，然后点击“Create Deployment”。
4. 配置： 按 Smithery 的提示提供必需的 API 密钥（openaiApiKey 等）。这些密钥会得到安全存储。
5. 启动： 开始部署流程。Smithery 会构建 Docker 镜像并运行容器。

Cursor 集成（已部署）

在 Smithery 上完成部署后：

1. 更新 .cursor/mcp.json，为你的服务使用 Smithery CLI 运行器（内容应与当前内容一致）：

   {
     "mcpServers": {
       "magic-mcp": { ... }, // 保留现有 Smithery 配置
       "mcp-figma": { ... }, // 保留现有 Smithery 配置
       "vercel-ai-sdk-mcp": {
         "command": "npx",
         "args": [
           "-y", "@smithery/cli@latest", "run",
           "chiziuwaga/vercel-ai-sdk-mcp-project",
           "--config",
           // 确保 Cursor 能访问这些环境变量
           "{"openaiApiKey":"${OPENAI_API_KEY}", "anthropicApiKey":"${ANTHROPIC_API_KEY}", "figmaApiKey":"${FIGMA_API_KEY}", "twentyFirstApiKey":"${TWENTY_FIRST_API_KEY}", "transportType":"stdio"}"
         ]
       }
     }
   }
   

2. 确保 Cursor 能从你的环境中访问 --config JSON 字符串中引用的 ${API_KEY} 变量。

配置

完整功能需要 API 密钥：

• OPENAI_API_KEY：Vercel AI SDK 工具必需。请在 Smithery 部署配置中提供，或在本地运行时填写到 .env 中。
• ANTHROPIC_API_KEY：可选，用于 Anthropic 模型。
• FIGMA_API_KEY：仅在实现 FigmaConnector 时必需。
• TWENTY_FIRST_API_KEY：仅在实现 MagicMcpConnector 时必需。

占位内容与后续工作

• 实现连接器： src/integrations/figma/connector.ts 和 src/integrations/magicMcp/connector.ts 中包含占位内容。需要添加实际的 API 调用（针对 Figma）和 MCP 客户端逻辑（可能针对 Magic MCP，具体取决于其接口），以启用集成工具。
• 添加更多工具： 按照规范实现剩余的 Vercel AI SDK 工具（文本生成、流式传输、聊天、代码生成等）。
• 错误处理： 改进错误处理，尤其是针对缺少 API 密钥的情况。
• 测试： 添加自动化测试。

许可证

ISC 许可证（根据 package.json）。