---
name: contributing
description: Use when contributing to the Butterbase codebase, adding new MCP tools, creating API routes, writing migrations, or understanding the monorepo architecture
---

## 1. Overview

Contributor guide for the Butterbase monorepo. Covers architecture, how to add MCP tools, API routes, database migrations, and coding conventions.

---

## 2. Monorepo Map

| Directory | Package | Purpose |
|-----------|---------|---------|
| `packages/cli` | `@butterbase/cli` (v0.1.3) | Published CLI tool (Commander.js). Commands: init, apps, schema, functions, storage, deploy, data, env, keys, realtime, status, open |
| `packages/sdk` | `@butterbase/sdk` (v1.2.1) | Published TypeScript SDK. Modules: auth, storage, functions, AI, billing, realtime, admin |
| `packages/shared` | `@butterbase/shared` | Internal shared types, constants, schema DSL, error types |
| `packages/plugin` | `@butterbase/plugin` | Claude Code plugin (this package — skills for AI agents) |
| `services/control-api` | `@butterbase/control-api` | Fastify API server — the brain. Routes, plugins, services. Port 4000 |
| `services/mcp-server` | `@butterbase/mcp-server` | MCP server with ~28 tools (consolidated `manage_*` action-based tools + a few standalone ones like `init_app`, `deploy_function`, `select_rows`). Runs via stdio or HTTP (served by control-api at `/mcp`) |
| `services/deno-runtime` | — | Serverless function executor. Deno-based worker isolation. Port 7133 |
| `services/cron-scheduler` | `@butterbase/cron-scheduler` | Cron job runner using node-cron + cron-parser |
| `services/dashboard` | — | React management UI (Vite + Radix UI) |
| `services/dashboard-api` | — | Dashboard backend proxy. Port 4100 |
| `services/docs` | `@butterbase/docs` | Astro/Starlight documentation site |
| `services/storage-indexer` | — | Cloudflare Worker for S3 event indexing |
| `db/control-plane` | — | SQL migrations (sequential numbering, `001_` upward). Control plane database schema |
| `db/data-plane` | — | Per-app database initialization scripts |

---

## 3. Adding a New MCP Tool (4 Steps)

### Step 1: Create tool file at `services/mcp-server/src/tools/my-new-tool.ts`

Decide whether the new capability is a standalone tool (single, self-contained operation like `init_app`) or another action on an existing umbrella tool (`manage_schema`, `manage_function`, etc). Most new operations should be added as actions on an existing `manage_*` tool — this keeps the surface area small for AI agents.

For a brand-new standalone tool, follow the pattern from `init-app.ts`:

```typescript
import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { z } from 'zod';
import { apiPost } from '../api-client.js';

interface MyResponse {
  // response shape
}

export function registerMyNewTool(server: McpServer) {
  server.tool(
    'my_new_tool',      // snake_case name
    `Tool description.   // Multi-line description with examples

Example:
  Input: { ... }
  Output: { ... }

Common errors:
  - ERROR_CODE: Description`,
    {
      // Zod schema for parameters
      app_id: z.string().describe('The app ID'),
      param: z.string().describe('Parameter description'),
    },
    async ({ app_id, param }) => {
      const result = await apiPost<MyResponse>(`/v1/${app_id}/my-endpoint`, { param });
      return {
        content: [{
          type: 'text' as const,
          text: JSON.stringify(result, null, 2),
        }],
      };
    }
  );
}
```

API client functions available: `apiGet`, `apiPost`, `apiPatch`, `apiDelete` (from `../api-client.js`).

### Step 2: Register in `services/mcp-server/src/create-server.ts`

```typescript
import { registerMyNewTool } from './tools/my-new-tool.js';
// ...
registerMyNewTool(server);
```

### Step 3: Create the backing API route in `services/control-api/src/routes/`

- Fastify route handler matching the endpoint your tool calls
- Register in `services/control-api/src/index.ts`

### Step 4: Update documentation in `services/mcp-server/src/docs/user-documentation.ts`

- Add tool to the relevant section's table in the `SECTIONS` object

---

## 4. Adding a Database Migration

- **IMPORTANT**: Use `scripts/migrate.ts` or `scripts/backfill-migrations.ts`, NEVER raw `psql`
- Migration files: `db/control-plane/NNN_description.sql` (sequential numbering, starting at `001_initial_schema.sql`)
- Pick the next free three-digit prefix; never edit a committed migration
- Run migrations: `npx tsx scripts/migrate.ts`

---

## 5. Coding Conventions

| Convention | Example |
|-----------|---------|
| MCP tool names | `snake_case`. Two flavours: standalone (`init_app`, `deploy_function`, `select_rows`) and `manage_*` umbrella tools that take an `action` enum (`manage_schema`, `manage_rls`, `manage_function`, `manage_frontend`, etc.) |
| App IDs | `app_` prefix: `app_abc123` |
| Service keys | `bb_sk_` prefix: `bb_sk_a1b2c3...` |
| Environment variables | `BUTTERBASE_` prefix: `BUTTERBASE_API_KEY` |
| Response metadata | `_meta.next_actions` (suggested next tool calls), `_meta.resource_info` (quota/state) |
| Error codes | `UPPERCASE_WITH_UNDERSCORES`: `AUTH_RLS_POLICY_VIOLATION`, `QUOTA_TABLE_LIMIT` |
| Domain | `butterbase.ai` (never "nira") |

---

## 6. Running Locally

```bash
docker-compose -f docker-compose.local.yml up
```

| Service | Port | URL |
|---------|------|-----|
| Control API | 4000 | `http://localhost:4000` |
| Dashboard API | 4100 | `http://localhost:4100` |
| Deno Runtime | 7133 | `http://localhost:7133` |
| Control Plane DB | 5433 | `postgres://localhost:5433` |
| Data Plane DB | 5435 | `postgres://localhost:5435` |
| PgBouncer | 6432 | `postgres://localhost:6432` |
| LocalStack (S3) | 4566 | `http://localhost:4566` |

---

## 7. Testing

- Framework: Vitest
- Run tests per workspace: `cd services/control-api && npm test`
- Test files: `__tests__/` directory or co-located `*.test.ts`
- Build all workspaces: `npm run build` (from repo root)
- Type check: `npx tsc --noEmit` in each workspace