Supero

supero-mcp

通过 MCP 使用 Supero，从 AI 助手构建并部署真正的 Web 应用。

描述你想要的应用。你的助手（Claude Code、Cursor、VS Code Copilot 或任何 MCP 客户端）会从 Supero 读取构建规范、编写应用、验证应用，并将其部署到一个可供你打开的 URL。平台会为应用提供登录、角色、数据库、管理面板和 API，因此助手只需编写属于你的部分，不必处理其他内容。

此仓库包含三项内容：

• 本指南：从头到尾介绍如何连接和构建。
• 项目简介：涵盖 16 个垂直领域的 31 款值得构建的应用，并以需求形式编写。选一个来构建吧。
• 社区应用：人们构建的应用及其源代码。运行一个、添加你自己的应用，或为他人的应用提交修复。

免费套餐提供 3 个项目，且无需绑定银行卡。该套餐的部署是 30 分钟预览版；要让 URL 持续可用，则需付费套餐。

从这里开始

如果你想要	前往
按步骤构建你的第一个应用	手把手构建你的第一个应用（30 分钟）
选择要构建的应用	挑选项目，然后查看项目列表
查看带源代码的完整示例	Page Turners，读书俱乐部应用
修复现有应用中的问题	社区应用
了解平台功能	在 docs.supero.dev 上了解更多

本页其余部分是面向有经验用户的简要版本。

目录

1. 获取密钥
2. 连接助手
3. 检查连接
4. 构建应用
5. 助手会做什么
6. 修改并发布
7. 免费套餐限制
8. 遇到问题时
9. 参与贡献

1. 获取密钥

1. 创建免费的 Supero 账户。无需绑定银行卡。
2. 在控制面板中打开 Build via MCP。每个项目页面和侧边栏中都有此入口。
3. 创建密钥。有两种类型：

密钥	助手可以用它做什么	适用场景
项目密钥	仅在一个项目中构建	你已在控制面板中创建项目，并希望在该项目中构建应用。这是更安全的默认选项。
域密钥	创建新项目并在其中构建	你希望助手也创建项目。需要域管理员权限。

密钥以 ak_ 开头，且仅显示一次。请立即复制。如果丢失，可在 API Keys 中轮换密钥以获取新密钥。

请像对待密码一样保护密钥。不要提交密钥，也不要将其粘贴到 issue 或应用文件夹中。

2. 连接助手

服务地址为 https://api.supero.dev/mcp/v1/messages（可流式传输的 HTTP）。请在 X-API-Key 请求头中直接发送密钥，不要在前面加上 Bearer。

Claude Code

claude mcp add --transport http supero \
  https://api.supero.dev/mcp/v1/messages \
  --header "X-API-Key: ak_..."

然后在 Claude Code 中运行 /mcp，并检查 supero 是否已连接。

Cursor：~/.cursor/mcp.json

{
  "mcpServers": {
    "supero": {
      "url": "https://api.supero.dev/mcp/v1/messages",
      "headers": { "X-API-Key": "ak_..." }
    }
  }
}

VS Code (GitHub Copilot)：.vscode/mcp.json

{
  "servers": {
    "supero": {
      "type": "http",
      "url": "https://api.supero.dev/mcp/v1/messages",
      "headers": { "X-API-Key": "ak_..." }
    }
  }
}

运行 MCP: List Servers，启动 supero，并在 Agent 模式下使用 Copilot。

其他客户端。 任何支持通过可流式传输的 HTTP 使用 MCP，且允许设置请求头的客户端都可以使用。更多详情以及目前已知的一项限制（Claude Desktop 的连接器界面要求使用 OAuth，而服务器暂不支持 OAuth），请参阅 docs/connect.md。

3. 检查连接

向你的助手提问：

Call build_whoami on Supero and tell me what it says.

你应该会收到自己的角色、域，以及使用项目密钥时与之绑定的项目。如果你更愿意在终端中检查：

curl -s https://api.supero.dev/mcp/v1/messages \
  -H "Content-Type: application/json" \
  -H "X-API-Key: ak_..." \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"build_whoami","arguments":{}}}'

4. 构建应用

粘贴以下内容，并在中间加入你自己的描述。

使用项目密钥（项目已存在）：

Connect to Supero over MCP and use your build_ tools. Everything runs through MCP: don't look for a local supero CLI or a SKILLS.md file on disk, there isn't one.

Build this app in my project: [describe your app: the main thing users do, the key screens, and an admin view].

Work in this order: build_whoami, then build_get_skills to load the spec, then build_plan. Echo the plan back to me and wait for my go-ahead. Then build_get_examples with the closest archetype as your reference, author the bundle, run build_validate and fix everything it reports, run build_doctor and fix its warnings, then build_publish and deploy (build_deploy for a ~30-minute preview, build_go_live for the permanent URL). Finally build_smoke_test the deployed URL and finish with a short summary: what you built, the URL, and how I log in.

使用域密钥，将第二段改为：

Create a new project with build_create_project (pick a short name and namespace), then build this app in it: [describe your app].

想不到点子？每份项目简介的末尾都有一条可直接粘贴的提示词。

如果助手开始在你的磁盘中搜索 CLI，请向它发送以下内容：

Stop reading the local filesystem. There is no CLI and no SKILLS.md. Call build_get_skills over MCP now, author the bundle, then build_validate.

更多提示词，适用于修改应用、修复部署失败以及上线，请参阅 docs/prompts.md。

5. 助手会做什么

步骤	工具	执行内容
1. 了解情况	build_whoami	查明它可以将应用构建到哪个项目中，以及密钥允许执行哪些操作。
2. 学习	build_get_skills、build_get_examples、build_get_service_contract	读取构建规范、可正常运行的参考应用，以及计划使用的每项平台服务的契约。规范由服务端实时提供，因此永远不会过时。
3. 规划	build_plan	将你的描述转化为记录、角色和界面。你先检查，然后确认开始。
4. 编写	（你的助手）	编写一组小型文件：数据模型、配置、设置内容和前端。
5. 检查	build_validate、build_doctor	平台会检查这组文件，并报告部署前需要修复的问题。
6. 发布	build_publish、build_deploy 或 build_go_live、build_deploy_status、build_smoke_test	发布一个版本并部署，等待应用启动，然后测试线上 URL。

部署通常需要几分钟，可能会在 launching 状态停留 5 分钟或更久。这是正常的：在判断出现问题之前，助手应持续轮询 build_deploy_status，最多等待 10 分钟。

完整的操作流程见 docs/build-flow.md，所有工具列于 docs/tools.md（共 64 个工具；无需密钥即可列出）。

**你不必构建的内容。**登录、角色和权限、逐条记录和逐字段的访问规则、数据库、REST API、管理面板，以及多租户应用中各组织之间相互隔离的数据。此外，还有现成的服务可供启用，无需自行编写：预订、预约、租赁、购物车、订单、支付、审批、任务、工单、评价、会员资格、定期方案、库存、文档签名、附件、通知、电子邮件等。让助手调用 build_list_capabilities，即可查看所有服务。

6. 修改并发布

• **修改应用。**告诉助手要修改什么。它会通过 build_get_bundle 获取当前版本，编辑后再次验证、发布和部署。每次都会递增版本号。
• 预览或上线。build_deploy 会提供一个有效期约 30 分钟的预览 URL，足以供你浏览和分享。build_go_live 会提供 supero.live 上的永久地址，需使用付费方案。
• **密钥。**电子邮件、短信或支付服务的密钥应放在应用管理面板的 Services 下。切勿将密钥放入这组文件中。
• **开发模式和线上模式。**项目默认以开发模式启动。真实用户访问前，请将其切换为线上模式。

免费方案限制

	免费
价格	$0，无需银行卡
项目	3 个
预览部署	每个项目 10 次，每次约 30 分钟
架构	20 个
API 请求	每月 10,000 次
永久线上 URL	Basic 方案起提供

以上数据来自 2026 年 10 月 5 日的定价页面。如有差异，以该页面为准。规划和验证均不收费，因此请先通过 build_validate 验证，再使用预览部署。更多信息见 docs/limits.md。

遇到问题时

你看到的内容	意味着	请执行以下操作
Authentication required	没有密钥传到服务端	检查请求头是否为 X-API-Key，以及添加密钥后是否重启了客户端。
401 或 Invalid API key	密钥有误、不完整、已撤销，或前面带有 Bearer	粘贴原始的 ak_... 值。如果密钥丢失，请在 API Keys 下轮换密钥。
助手无法创建项目	你提供的是项目密钥	在控制面板中创建项目，或使用域密钥。
助手在查找 CLI 或 SKILLS.md 文件	它在根据旧习惯猜测	发送第 4 步中的恢复提示词。
build_validate 失败	资源包违反了某条规则	让助手修复列出的问题，然后重新运行。这一步免费。
build_doctor 警告说 workflows“通常需要更高权限”	该警告已过时	忽略它。工作流使用项目密钥即可注册和运行（已于 2026 年 10 月 6 日核实）。
应用已部署，但屏幕内容不完整	部分初始数据可能未创建。这是一个平台故障，已于 2026 年 10 月 5 日修复	如果仍然遇到此问题，请让助手调用 build_logs 并查找 SEED FAILURES，然后重新部署，并请提交 issue。
部署一直停留在 launching	应用仍在启动	请等待。轮询最多十分钟。
普通用户无法保存状态字段	名为 status 或 state 的字段受到保护	将生命周期字段命名为 <something>_state，例如 booking_state。
预览次数用尽	免费套餐提供十次预览	部署前多做验证，或升级套餐。

仍然无法解决？请在 Discussions 中提问。发现了让服务端出现异常的方法？请查看 SECURITY.md 并私下报告。

参与贡献

有四种参与方式，且都无需事先获得许可。待处理的 issue 中列出了一些适合新手的任务，我们会在一天内回复。

• 发布应用。 构建一个需求说明，或实现自己的创意，并将应用及其源代码添加到社区应用中。
• 改进他人的应用。 将其部署到自己的项目中，修复一个已知问题，然后提交修改。
• 为你希望存在的应用编写需求说明。 复制 projects/TEMPLATE.md。
• 改进本指南：补充我们尚未介绍的客户端、更有效的提示词，或我们尚未说明的错误。

详情请参阅 CONTRIBUTING.md。

相关内容

• supero-apps：19 个完整的参考应用，包含源代码和在线演示。
• docs.supero.dev 上的 MCP 文档，以及一份介绍构建时最实用的功能页面的指南。

许可证

本仓库中的所有内容均采用 MIT 许可。你构建的应用归你所有。Supero 平台本身是托管服务，并非开源。