Butterbase 工具链清单：SDK、CLI 与 Claude Code 插件的 AI 辅助开发完整指南

Butterbase 工具链清单：SDK、CLI 与 Claude Code 插件的 AI 辅助开发完整指南

【免费下载链接】butterbase-ossOpen-source backend-as-a-service. Postgres, auth, storage, functions, AI gateway, MCP.项目地址: https://gitcode.com/gh_mirrors/bu/butterbase-oss

Butterbase 工具链是开源 BaaS（后端即服务）项目 Butterbase 的三大核心开发利器：@butterbase/sdk（TypeScript SDK）、@butterbase/cli（命令行工具）和 Claude Code 插件（30+ 引导式 Skills），三者配合 MCP 协议，让你用自然语言即可完成 Postgres 数据库、认证、存储、无服务器函数与 AI 网关的全部后端搭建。本文面向新手，带你快速上手这套 AI 辅助开发工具链。

一图看懂：Butterbase 三大工具各司其职 🧩

简单记法：SDK 管"代码里用"，CLI 管"终端里管"，插件 + MCP 管"让 AI 替你干"。

@butterbase/sdk：前端后端通用的 TypeScript 客户端 📦

SDK 可在浏览器、Node.js 和 Deno 三种环境运行，是官方文档中所有示例代码的基础。

30 秒上手 SDK：安装、初始化与查询数据

安装后只需三步：初始化客户端 → 查询 → 写入。

import { createClient } from '@butterbase/sdk'; const bb = createClient({ appId: 'app_abc123', apiUrl: 'https://api.butterbase.ai' }); // 查询（链式查询构建器，类似 SQL 的 where/order/limit） const { data, error } = await bb.from('posts').select('*').eq('status', 'published'); // 写入 await bb.from('posts').insert({ title: 'Hello', content: '...' });

除了数据 CRUD，SDK 还内置了以下能力（详见 packages/sdk/README.md）：

• 认证：auth.signUp/signIn/ OAuth 登录，会话自动持久化到 localStorage，令牌自动刷新；
• 文件存储：storage.upload/getDownloadUrl/delete；
• 函数调用：functions.invoke直接触发云端无服务器函数；
• RAG 检索、实时订阅、AI 网关（chat / embeddings）；
• 类型安全：from<Post>('posts')可传入泛型，返回数据自动推断类型。

💡 错误处理同样对 AI 友好：所有方法返回{ data, error }，error是带code、remediation（修复建议）的强类型错误对象，方便 AI Agent 自我纠错。

@butterbase/cli：一行命令搞定脚手架与部署 🚀

CLI 把"建应用、改表结构、发函数、传文件、配 AI"这些重复操作全部变成一条命令。

CLI 一键安装与登录步骤

npm install -g @butterbase/cli # 1. 安装 butterbase login # 2. 用 API Key 登录 butterbase init # 3. 生成本地项目（内置 React + Vite 模板）

butterbase init会基于 packages/cli/templates/react-vite/ 模板自动替换 App ID、API 地址等变量，并生成.mcp.json供 Claude Code 直接接入（见 packages/cli/src/commands/init.ts）。

常用命令清单：schema、functions、storage 与 AI

配置保存在~/.butterbase/config.json（全局）和.butterbase/config.json（项目级），也支持BUTTERBASE_API_KEY、BUTTERBASE_ENDPOINT环境变量。完整命令参考 packages/cli/README.md，各子命令实现位于 packages/cli/src/commands/。

Claude Code 插件与 MCP：让 AI 直接操作后端 🤖

这是 Butterbase 最"AI 原生"的部分——内置的 MCP 服务器把平台能力暴露为 40+ 个工具：manage_schema（声明式建表 + dry-run 预览）、deploy_function、manage_rls、manage_auth_config、rag_query等。AI 不再需要拼胶水代码，而是"调用工具"完成操作。

3 种接入 MCP 的方式：托管、本地 stdio 与插件

1. 托管端点（最省事）：在任意 MCP 客户端配置中填入https://api.butterbase.ai/mcp+ Bearer 认证头即可；
2. 本地 stdio：npx @butterbase/mcp，零部署；
3. CLI 一键接入：butterbase mcp install通过 add-mcp 自动写入 Claude Code、Cursor、VS Code 等 14 种客户端的配置，并打印每种客户端的一次性浏览器登录指引（实现见 packages/cli/src/commands/mcp.ts）。

支持 OAuth 2.1 授权流程，已实测兼容Claude Code、Claude Desktop、Cursor、Windsurf、Codex CLI等主流 AI 客户端。

30+ 引导式 Skills：从想法到上线

Claude Code 插件位于 packages/plugin/（以 git submodule 形式挂载，git clone时记得加--recurse-submodules，否则该目录为空）。它提供/butterbase-skills:journey、/butterbase-skills:build-app等 30+ 引导式技能，覆盖完整链路：

想法 → 规划 → 建表（schema）→ 认证（auth）→ 函数（functions）→ 部署（deploy）→ 提交

配合butterbase clone命令，还可以一键克隆 templates/butterbaseCRM/、templates/butterSupport/ 等生产级模板应用，从第一天就拥有可用的产品（schema、RLS、函数、AI 配置全部随克隆带走）。

实战：SDK + CLI + MCP 的推荐组合拳 ⚡

一个典型的 AI 辅助开发流程长这样：

1. CLI 打地基：butterbase login→butterbase apps create my-app→butterbase schema apply schema.json；
2. MCP 让 AI 接手：butterbase mcp install接入 Claude Code，用自然语言说"给 posts 表加索引并配 RLS 策略"，AI 通过manage_schema、manage_rls工具直接执行并返回 dry-run 差异；
3. SDK 写业务：前端用@butterbase/sdk做登录、查询、上传；
4. 验证与部署：butterbase functions deploy ./functions/api.ts一键上线函数，butterbase functions logs查看运行日志。

目录结构与源码索引 📁

常见问题 FAQ ❓

Q：API Key 从哪来？自托管环境执行butterbase keys generate即可生成（以bb_sk_开头），也可在官方平台控制台创建，然后export BUTTERBASE_API_KEY=bb_sk_...。

Q：插件目录是空的怎么办？packages/plugin是 git submodule，普通git clone不会拉取内容，需执行git submodule update --init --recursive补齐。

Q：SDK 能在无服务器的 Deno 函数里用吗？可以。import { createClient } from 'npm:@butterbase/sdk'，配合Deno.env.get读取配置即可，SDK 对浏览器/Node/Deno 三端全兼容。

掌握SDK 写代码、CLI 管后端、Claude Code 插件 + MCP 让 AI 干重活这套组合，你就能以接近"聊天"的速度交付完整的全栈应用 🎯

【免费下载链接】butterbase-ossOpen-source backend-as-a-service. Postgres, auth, storage, functions, AI gateway, MCP.项目地址: https://gitcode.com/gh_mirrors/bu/butterbase-oss