bubble-mcp: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Commands

npm run build        # Compile TypeScript to dist/
npm run dev          # Run from source via tsx (no build needed)
npm run setup <id>   # Browser auth for editor access (first-time)
npm test             # Run all 472+ tests (vitest)
npm run test:watch   # Tests in watch mode
npm run lint         # ESLint
npm run lint:fix     # ESLint with auto-fix
npm run format       # Prettier (write)
npm run typecheck    # tsc --noEmit

# Run a single test file
npx vitest run tests/tools/core/search.test.ts

# Auth with branch support
npm run setup <app-id> -- --version <branch-id>
npm run setup <app-id> -- --branch <branch-name>

Architecture

This is an MCP server for Bubble.io that exposes 65 tools over stdio transport. Tools are organized in three layers (plus optional editor tools) with a hierarchical permission model.

Entry Flow

src/index.ts loads config, creates the server, and connects to StdioServerTransport. All logging goes to stderr (stdout is reserved for MCP JSON-RPC).

Tool Lifecycle

1. Config (src/config.ts) — loads from env vars or bubble.config.json
2. Server (src/server.ts) — collects tools from 3 layers, filters by mode, registers each with the MCP SDK
3. Middleware chain wraps every tool handler:
   • RateLimiter — token bucket (configurable req/min)
   • mode-gate — filters tools based on read-only < read-write < admin hierarchy
   • error-handler — catches errors, returns { error, code, hint } with isError: true
4. successResult() — returns data directly as JSON (no wrapper), applies truncateResponse if over 50KB

Tool Layers

Layer	Directory	Count	Purpose
Core	src/tools/core/	11	CRUD, search, schema, workflows, swagger
Compound	src/tools/compound/	7	Multi-step analysis (privacy audit, orphans, field usage)
Developer	src/tools/developer/	10	TDD validation, migration planning, seed data
Editor Read	src/tools/core/	12	App structure, pages, elements, workflows, data types, styles (requires browser auth)
Editor Write	src/tools/core/	17	Create/update types, fields, pages, elements, workflows, privacy rules
Analysis	src/tools/core/	8	App review, 6 category audits, auto-learner (requires editor auth)