{ "markdown": "

\n \"Butterbase\"\n

\n\n

AI-native, open-source backend-as-a-service.
Postgres · Auth · Storage · Functions · AI Gateway · MCP server

\n\n

\n \"License:\n \"GitHub\n \"GitHub\n
\n \"Join\n \"Follow\n \"TypeScript\"\n \"Postgres\"\n \"Docker\"\n

\n\n

\n Website ·\n Discord ·\n LinkedIn ·\n Self-host ·\n Docs ·\n Roadmap ·\n Examples ·\n Contributing\n

\n\n---\n\n\n\nButterbase gives you the building blocks for AI-driven applications without lock-in: a Postgres-backed backend with row-level security, serverless functions, an LLM gateway, realtime subscriptions, key-value store, file storage, RAG, durable per-key actors, and a built-in **Model Context Protocol (MCP) server** so agents can operate your backend with tools instead of glue code.\n\n## Features\n\n**Data**\n- **Postgres data plane** — per-app databases with declarative schema (`/schema`), automatic REST endpoints (`/auto-api`), and migrations.\n- **Row-Level Security** — first-class RLS policy management with user-isolation helpers (`/rls`).\n- **Key-Value store** — regional, quota-protected KV with TTL, audit trail, and dashboard expose rules (`/v1/:app/kv/*`). *New in v0.2.0.*\n- **File storage** — S3/R2-backed object storage with presigned URLs, ACLs, and async indexing (`/storage`).\n\n**Compute**\n- **Serverless functions** — TypeScript functions executed on the Deno runtime (`/functions`).\n- **Durable Objects** — stateful per-key actors for chat rooms, multiplayer, rate limiters, long-running agents (`/durable-objects`).\n- **Realtime** — WebSocket subscriptions to table changes for live UIs and presence (`/realtime`).\n- **Edge SSR** — deploy Next.js / Remix / Astro edge handlers from source (`/edge-ssr`, `/edge-ssr-from-source`).\n- **Frontend hosting** — zip or build-from-source static / SPA deploys with custom domains (`/frontend`, `/custom-domains`).\n\n**AI**\n- **AI gateway** — single endpoint for chat, embeddings, model listing; pluggable router adapters (`/gateway`, `/ai-config`).\n- **RAG** — managed collections, document ingestion, semantic search and synthesized answers (`/rag`).\n- **Integrations** — third-party tool access via Composio (`/integrations`).\n\n**Identity & ops**\n- **Auth** — email + OAuth (Google, GitHub, Apple, X, …), JWT tuning, post-login hooks, service keys (`/auth`, `/oauth-config`, `/api-keys`).\n- **Audit logs** — structured request audit trail across KV and other surfaces (`/audit-logs`).\n- **Webhooks** — outbound webhooks for app events (`/webhooks`).\n- **Multi-region app moves** — relocate an app across regions with retained source replicas (`scripts/move-app/`).\n\n**Agent surface**\n- **MCP server** — every capability above is exposed as MCP tools at `/mcp` (HTTP) or via stdio (`@butterbase/mcp` — `npx @butterbase/mcp`).\n- **Claude Code plugin** — `packages/plugin` (submodule of [butterbase-skills](https://github.com/butterbase-ai/butterbase-skills)) ships 30+ guided skills (idea → plan → schema → auth → functions → deploy → submit) for agentic app building.\n\n## Open-source vs. managed\n\nThis repo ships the **runtime data plane** — everything required to self-host a fully featured Butterbase instance. The **managed offering** at [butterbase.ai](https://butterbase.ai) adds multi-region orchestration, billing, upstream AI router adapters, lease-based quota enforcement, and ops dashboards (those live in a private repo that consumes this one as a submodule).\n\nWhen you self-host, the AI gateway runs without upstream router adapters, billing uses a no-op provider, and quotas are unlimited. Wire your own implementations via the `BillingProvider`, `QuotaEnforcer`, and `RouterAdapter` interfaces in `packages/shared`.\n\n## Quickstart (self-host)\n\n**Requirements:** Docker, Node 22+, npm.\n\n### 1. Clone (with submodules)\n\nThe Claude Code plugin containing skills (`packages/plugin`) is a git submodule ([butterbase-skills](https://github.com/butterbase-ai/butterbase-skills)). A plain clone leaves `packages/plugin/` empty and `npm install` silently skips that workspace.\n\n```bash\ngit clone --recurse-submodules https://github.com/butterbase-ai/butterbase.git\ncd butterbase\n```\n\nIf you already cloned without submodules:\n\n```bash\ngit submodule update --init --recursive\n```\n\nOptional — keep submodules updated on every pull:\n\n```bash\ngit config --global submodule.recurse true\n```\n\n### 2. Install dependencies and configure env\n\n```bash\nnpm ci\ncp .env.example .env\n```\n\n`docker-compose.local.yml` sets `KV_REDIS_URL_US_EAST_1` for you. Edit `.env` only if you override defaults (e.g. run control-api on the host — use `redis://localhost:6379`).\n\n### 3. Start the stack\n\nFirst run builds images and can take several minutes.\n\n```bash\ndocker compose -f docker-compose.local.yml up -d\n```\n\nWait until control-api is healthy:\n\n```bash\ncurl -sf http://localhost:4000/health/ready\n```\n\n### 4. Run database migrations\n\nSchema is **not** applied automatically on container start. From the repo root (with the stack running):\n\n```bash\nexport NEON_PLATFORM_PRIMARY_URL=postgresql://butterbase:butterbase_dev@localhost:5433/butterbase_control\nexport NEON_RUNTIME_PROJECT_ID_US_EAST_1=postgresql://butterbase:butterbase_dev@localhost:5437/butterbase_runtime_us\nexport BUTTERBASE_REGIONS=us-east-1\n\nnpm run migrate:all\n```\n\n### 5. Seed the local dev user\n\nWith `AUTH_ENABLED=false`, the API uses `DEV_OWNER_ID` from compose. That user must exist in `platform_users` (fresh volumes start empty):\n\n```bash\nexport NEON_PLATFORM_PRIMARY_URL=postgresql://butterbase:butterbase_dev@localhost:5433/butterbase_control\nnpm run seed:dev\n```\n\n### 6. Smoke test\n\nAuth is disabled in the local compose profile (`AUTH_ENABLED=false`):\n\n```bash\ncurl -X POST http://localhost:4000/init \\\n -H \"Content-Type: application/json\" \\\n -d '{\"name\": \"my-app\"}'\n\ncurl http://localhost:4000/apps\n```\n\n### Local endpoints\n\n| Service | URL / port |\n|---------|------------|\n| Control API | http://localhost:4000 |\n| MCP (HTTP, via control-api) | http://localhost:4000/mcp |\n| Deno runtime | http://localhost:7133 |\n| Docs site | http://localhost:4321 |\n| Control plane Postgres | `localhost:5433` |\n| Data plane Postgres | `localhost:5435` |\n| Runtime plane Postgres | `localhost:5437` |\n| LocalStack (S3) | http://localhost:4566 |\n\nFull setup (auth, MCP clients, troubleshooting, production notes): **[`SETUP.md`](./SETUP.md)**.\n\n## Architecture\n\n```\n ┌──────────────────────────────────────────┐\n │ Your app · agent · MCP client · CLI │\n └──────────────────────┬───────────────────┘\n │ REST · WebSocket · MCP\n ┌──────────────────────▼───────────────────┐\n │ control-api (Fastify) │\n │ apps · auth · schema · auto-api · RLS │\n │ storage · functions · KV · realtime │\n │ AI gateway · RAG · DOs · MCP at /mcp │\n └──┬──────┬───────┬───────┬────────┬───────┘\n │ │ │ │ │\n ┌────────▼─┐ ┌──▼───┐ ┌─▼──┐ ┌──▼─────┐ ┌▼─────────────┐\n │ Postgres │ │ S3 / │ │Redis│ │ Deno │ │ Python agent │\n │ 3 planes │ │ R2 │ │ KV │ │runtime │ │ runtime │\n └──────────┘ └──────┘ └────┘ └────────┘ └──────────────┘\n ┌──────────────────┐\n │ Cloudflare: │\n │ build-runner · │\n │ dispatch-worker │\n └──────────────────┘\n```\n\n**Three Postgres planes:**\n- **control-plane** (`db/control-plane/`) — platform metadata: users, apps, billing, audit.\n- **runtime-plane** (`db/runtime-plane/`) — hot-path runtime tables (KV expose rules, realtime channels, sessions).\n- **data-plane** (`db/data-plane/`) — per-app user data; each app gets isolated schemas with RLS.\n\n## Repo layout\n\n**Services** (`services/`)\n\n| Service | Language | What it does |\n|---|---|---|\n| `control-api` | Node.js / Fastify | Main entry point. All public APIs, embeds MCP at `/mcp`. |\n| `mcp-server` | Node.js | MCP tool implementations (built into control-api; also ships as `butterbase-mcp` stdio binary). |\n| `deno-runtime` | Deno | Executes user serverless functions in isolates. |\n| `agent-runtime` | Python (uv) | Long-running agent executor for `manage_ai` / agent tasks. |\n| `build-runner` | Cloudflare Worker | Builds frontends and edge-SSR bundles from source. |\n| `storage-indexer` | Node.js | Async indexer for uploaded objects. |\n| `docs` | Astro | Public documentation site (also served locally at `:4321`). |\n\n**Packages** (`packages/`)\n\n| Package | Description |\n|---|---|\n| `@butterbase/sdk` | Universal TypeScript SDK (browser + server). |\n| `@butterbase/cli` | `butterbase` CLI for scaffolding and backend management. |\n| `@butterbase/plugin` | Claude Code plugin — 30+ guided skills for AI-driven app building. Git submodule of [butterbase-skills](https://github.com/butterbase-ai/butterbase-skills). |\n| `@butterbase/shared` | Shared types, constants, and pluggable interfaces (`BillingProvider`, `QuotaEnforcer`, `RouterAdapter`). |\n\n**Other top-level pieces**\n- `dispatch-worker/` — Cloudflare Worker that routes per-app subdomain traffic.\n- `bb-placeholder/` — placeholder origin for unprovisioned subdomains.\n- `infra/` — `pgbouncer` and `traefik` configs for self-host.\n- `db/` — SQL migrations for the three Postgres planes.\n- `Examples/` — `todo-2026-04-02`, `grocery-list-2026-04-03`.\n- `templates/` — full production-shaped apps: `butterSupport`, `butterbaseCRM`.\n\n## What's *not* in this repo\n\nThe OSS / managed boundary is intentional. The following are private to the managed offering:\n\n- Multi-region orchestration and the cross-region scheduler.\n- Billing logic, lease-based quota math, and Stripe wire-up beyond the no-op provider.\n- Upstream AI router adapters (OpenAI / Anthropic / Bedrock provider integrations beyond the gateway interface).\n- Customer / admin dashboards, hackathon-host dashboards, and ops tooling.\n\nIf you need these for self-host, implement against the interfaces in `packages/shared` — see [`CONTRIBUTING.md`](./CONTRIBUTING.md) for the scope rules.\n\n## Documentation\n\n- [`SETUP.md`](./SETUP.md) — self-host and local development guide\n- [`CHANGELOG.md`](./CHANGELOG.md) — release notes (latest: **v0.2.0**, 2026-05-25 — KV store)\n- [`ROADMAP.md`](./ROADMAP.md) — what's next\n- [`CONTRIBUTING.md`](./CONTRIBUTING.md) — contributor workflow and OSS scope\n- [`SUBDOMAIN_IMPLEMENTATION.md`](./SUBDOMAIN_IMPLEMENTATION.md) — tenant subdomain routing\n- [`docs/runbooks/local-e2e.md`](./docs/runbooks/local-e2e.md) — multi-region E2E stack\n- [`docs/runbooks`](./docs/runbooks) — operational runbooks\n- [`Examples/`](./Examples) — small example apps (todo, grocery list)\n- [`templates/`](./templates) — full apps you can clone and run (butterSupport, butterbaseCRM)\n- Docs site (local): `http://localhost:4321` after `docker compose up`\n\n## Project status\n\nLatest release: **v0.2.0** (2026-05-25) — adds the KV store across SDK / REST / CLI / MCP. The data plane is production-tested by the managed offering; the OSS distribution is young — please file self-host issues and we'll tighten docs and defaults from feedback. See [`CHANGELOG.md`](./CHANGELOG.md) for the full history.\n\n## Community & support\n\n- **[Discord](https://discord.gg/Aq7q5mqbrt)** — chat with the team and other builders\n- **[LinkedIn](https://www.linkedin.com/company/butterbase/?trk=public_profile_following-company_profile-result-card_result-card_title)** — follow us for product updates and announcements\n- **[GitHub Issues](https://github.com/butterbase-ai/butterbase/issues)** — bug reports, feature requests\n- **Email** — [yuki@butterbase.ai](mailto:yuki@butterbase.ai) for direct contact\n\n## Contributing\n\nSee [`CONTRIBUTING.md`](./CONTRIBUTING.md). The boundary between OSS and the managed offering is intentional — please read the scope section before opening a PR that touches billing, quota math, or upstream router adapters.\n\n## Security\n\nSee [`SECURITY.md`](./SECURITY.md). Report vulnerabilities to `security@butterbase.ai`.\n\n## License\n\n[Apache-2.0](./LICENSE). Copyright 2026 NetGPT Inc.\n\n## Contributors\n\n\n \"Contributors\"\n\n\n## Star history\n\n\n \n \n \n \"Star\n \n", "bytes": 14861, "sha": "55454de63aa60765de81e6d40dde15dd034b8096f400dea6b6807516506e32ce", "repo_slug": "butterbase-ai/butterbase-oss", "fonte": "repo", "truncated": false, "api": "https://agentalog.com/api/listings/mcp_io_github_butterbase_ai_mcp_db1e93a1/readme" }