MCP SaaS-Builder

SAAS-MCP-Orchestrator：从原型到生产

1. 引言

本文件概述了将SAAS-MCP-Orchestrator从基于浏览器的用户界面原型发展成一个功能齐全、由人工智能驱动的应用程序所需的要求、架构和可执行任务。目标是将用户界面连接到一个真实的后端编排引擎，该引擎利用Gemini API并与指定的模型上下文协议（MCP）服务器进行交互。

2. 当前环境分析

现有的应用程序是一个高保真原型，完全在沙盒浏览器环境中运行。在进行转换之前，了解其局限性至关重要。

• 平台基于浏览器的React应用程序。
• 建筑学单页应用程序（SPA），无后端。所有逻辑都在客户端处理。
• 编排逻辑“编曲”是一种模拟。它使用 setTimeout 模拟异步任务并遵循硬编码的步骤序列。状态在React内部本地管理 App 组件。
• MCP交互有 没有实际交流 与任何MCP服务器（如Vercel、Supabase等）兼容。用户界面仅用于演示目的，显示这些服务器的图标和状态。
• 人工智能集成有 没有连接 根据上面的信息，执行如下指令：。

3. 本地开发需求

要在本地构建和运行完整的应用程序，您需要以下内容：

3.1。 软件

• Node.js版本18.x或更高版本。
• npm（Node Package Manager，节点包管理器） 或者 纱线；毛线用于包管理。
• Git（注：Git是一个分布式版本控制系统，常用于代码管理）用于版本控制。
• 代码编辑器推荐使用 Visual Studio Code。
• MCP服务器能够运行命令行进程，因为大多数MCP服务器都是通过命令行启动的 npx。

3.2。 账户与凭据

• 谷歌AI工作室API密钥一个有效的Gemini API密钥。
• GitHub账户一个带有（权限的）个人访问令牌 repo 并且 workflow 范围。
• Vercel 账户用于程序化控制项目的API令牌。
• Supabase 账户用于管理数据库和项目的API密钥。
• （可选）如果您选择集成其他服务（如Context7），请提供相应的密钥。

3.3。 环境变量

复制 .env.local.example 到；向；朝 .env.local 并在进入实时模式运行之前填写以下值：

• GEMINI_API_KEY — 双子座编排策略所需。
• ORCHESTRATION_STRATEGY — 设置为 simulated 或者 gemini。
• MCP_EXECUTION_MODE — dry-run 为了进行安全的模拟， live 执行真实的MCP命令。
• MCP_GITHUB_TOKEN — GitHub MCP服务器使用的GitHub个人访问令牌（PAT）。
• MCP_GITHUB_REPO_OWNER — 应创建仓库的用户名或组织名。
• 可选覆盖： MCP_GITHUB_EXECUTABLE， MCP_GITHUB_SERVER， MCP_GITHUB_TOOLSETS。
• Redis 持久化（生产环境推荐）： UPSTASH_REDIS_REST_URL， UPSTASH_REDIS_REST_TOKEN。

注： 当前的GitHub MCP集成支持 create_repository 并且 push_files 工具。确保提示中包含明确的仓库名称，以便编排器能够满足MCP（可能是指某种配置或管理规范）模式的要求。

4. 提出的架构与设计实现

功能应用将从仅客户端模式转变为客户端-服务器架构。前端仍然是用户进入编排过程的窗口，而新的后端服务则负责处理所有繁重的工作。

4.1。 前端（React 应用）

现有的React组件可以大量复用。其主要作用将是：

1. 捕捉用户的SaaS描述。
2. 通过将描述发送到后端来启动编排过程。
3. 通过WebSockets接收来自后端的实时状态更新和日志。
4. 动态渲染编排进度，就像在原型中所做的那样。

4.2。 后端（编排引擎）

这是要构建的核心组件。A. Node.js 服务器 （使用像Next.js API Routes或Express这样的框架）是理想的选择。

职责：

• API 端点暴露一个端点（例如。， /api/orchestrate) 从前端接收SaaS提示。
• WebSocket 服务器托管一个WebSocket服务器以推送实时更新OrchestrationStep 状态变化、日志、错误等信息传递给连接的前端客户端。
• 状态管理保持每个用户会话的生成过程状态。
• AI Core（人工智能核心）与Gemini API集成以驱动决策过程。
• MCP 客户端执行命令以与各个MCP服务器进行交互。

4.3。 AI核心逻辑（带函数调用的Gemini API）

后端不会遵循硬编码的序列。相反，它将使用Gemini的功能调用能力来确定下一步操作。

工作流程：

1. 初始提示后端接收用户的SaaS描述，并将其格式化为Gemini的系统提示。该提示将定义目标，并列出所有可用的MCP工具作为函数声明。

- 系统提示示例： "You are an expert SaaS development orchestrator. Your goal is to build a complete application based on the user's request. You have access to a set of tools to accomplish this. Plan your steps, use the tools provided, and do not hallucinate functions."

1. AI规划循环：

a. 后端将当前状态和提示发送给Gemini。 b. 双子座以期望的行为形式作出回应 functionCall （例如。， {"name": "github:createRepo", "args": {"repoName": "bookmark-manager"}}）。 c. 后端解析此响应，并确定目标MCP服务器和工具。 d. 它执行相应的MCP工具（例如，运行 npx @modelcontextprotocol/server-github createRepo ... 命令）。 e. 后端从MCP工具中捕获结果（成功、失败、数据）。 f. 它将结果发送回Gemini，以供其做出下一步决策，并重复此循环。

1. 实时记录在每一步（b-f）中，后端通过WebSocket向前端推送状态更新。

5. 实施任务：分步实施计划

第一阶段：项目搭建与后端基础建设

• \[ \] 任务1.1：初始化一个Next.js项目使用 npx create-next-app@latest --typescript 用于现代的React和后端框架。
• \[ \] 任务1.2：迁移前端组件移动现有的 components， types.ts， constants.ts，以及 App.tsx 文件导入到新的 Next.js 项目中 app 或者 pages 目录结构。根据需要调整导入内容。
• \[ \] 任务1.3：创建API端点和WebSocket服务器:

- 创建一个API路由（/app/api/orchestrate/route.ts）。 - 集成一个像……这样的WebSocket库 ws 或者 socket.io 处理实时通信。

• \[ \] 任务1.4：确保环境变量的安全性创建一个 .env.local 用于安全存储所有API密钥和令牌的文件。

第二阶段：AI协调器与MCP集成

• \[ \] 任务2.1：集成Gemini SDK添加 @google/genai 将包发送到后端。使用环境变量中的API密钥初始化客户端。
• \[ \] 任务2.2：定义工具模式对于每个MCP服务器工具（例如。， Vercel:createProject， Supabase:createTable)，定义一个 FunctionDeclaration 根据Gemini SDK文档中的模式。此模式告诉AI有哪些工具可用以及它们接受哪些参数。
• \[ \] 任务2.3：构建人工智能循环实现第4.3节中描述的核心编排逻辑。此函数将是应用程序的核心。
• \[ \] 任务2.4：创建MCP封装器在后端编写辅助函数来管理与MCP服务器的交互。这些封装函数将使用Node.js的 child_process 模块以生成（或启动） npx 发出命令，传递参数，并监听 stdout 和 stderr 以取得成果。

第三阶段：将前端与后端连接

• \[ \] 任务3.1：更新表单提交功能修改 SaaSInputForm.tsx 将SaaS描述发送给您 /api/orchestrate 使用端点 fetch。
• \[ \] 任务3.2：实现WebSocket客户端在 App.tsx，建立与后端的WebSocket连接。创建一个 useEffect 钩子用于监听传入消息并更新 steps 相应地说明。
• \[ \] 任务3.3：移除模拟逻辑删除全部 setTimeout 模拟代码和前端硬编码的状态转换。现在，前端应该是后端状态的纯粹反映。

阶段4：测试与优化

• \[ \] 任务4.1：端到端测试为一个简单的SaaS想法（比如书签管理器）进行全面的系统集成。
• \[ \] 任务4.2：实现健壮的错误处理确保如果MCP命令失败或AI返回无效响应，能够捕获该错误，将其记录到前端，并且可以重新尝试该过程或优雅地终止。
• \[ \] 任务4.3：提示工程优化提供给Gemini的系统提示和工具描述，以提高其计划和工具使用的可靠性和准确性。

______________________________________________________________________

遵循这一路线图，您可以将令人印象深刻的UI原型系统地转化为一个功能强大且实用的AI驱动SaaS生成工具。