contributing

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

---

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:

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

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

---

6. Running Locally

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

---

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