Skip to content
Skills Library
Programming · Building & coding

contributing

/contributing

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

Licence
MIT
Last repository change
25.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
4
Deprecation

No signals detected. Repository changed on 25.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

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

Original author description

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

How it works

  1. 1. Overview
  2. 2. Monorepo Map
  3. 3. Adding a New MCP Tool (4 Steps)
  4. 4. Adding a Database Migration
  5. 5. Coding Conventions
  6. 6. Running Locally
  7. 7. Testing
Original SKILL.md headings · 144 lines, 760 words
SKILL.md preview
---
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

Versions

RepositoryScoreLicence
This page · butterbase-ai/butterbase-skills100MIT
cloudflare/cloudflare-docs100CC-BY-4.0
blaizzy/mlx-vlm100MIT
emmgeede/gridselect100MIT
Jeff-Kazzee/github-skills100MIT
googlecloudplatform/race-condition100Apache-2.0
Dqz00116/skill-lib100MIT
iowarp/clio-core84BSD-3-Clause

Database snapshot: 13.11.2026 · package version 6c0046d6eb23 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 95build-app
    Use when building a new Butterbase app from scratch, creating a full-stack application, or when the user asks to set up a complete backend with database, auth, and deployment
  • 100contributing-guide-creator
    Create contributing guide creator operations. Auto-activating skill for Technical Documentation. Triggers on: contributing guide creator, contributing guide creator Part of the Technical Documentation skill category. Use when working with contributing guide creator…
  • 100function-dev
    Use when developing, deploying, or debugging Butterbase serverless functions, or when the user needs to add backend logic like webhooks, scheduled jobs, or custom API endpoints
  • 100shipping
    Use this skill when contributing changes to the FAST monorepo — creating pull requests, generating change files, writing PR descriptions, and keeping documentation up to date.
  • 95agents-contributing-setup-repo
    Set up a repository to receive help from AI agents under the AGENTS-CONTRIBUTING spec. Use when a repository owner asks to accept agent contributions, add AGENTS-CONTRIBUTING.md, or open their repo to donated AI capacity.
  • 100codebase-summary
    Analyze a codebase and generate comprehensive documentation including architecture, components, interfaces, workflows, and dependencies. Creates an AI-optimized knowledge base (index.md) and can consolidate into AGENTS.md, README.md, or CONTRIBUTING.md. Use when the user wants…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.