project-supabase-api

Controlled AI-to-Supabase integration layer for the AI Projects portfolio.

Not a generic Supabase client library. The official SDKs (@supabase/supabase-js, supabase-py) already solve that. This repo adds the AI adapter layer: safety-bounded operations, agent-purpose-built MCP server, migration tooling, and reusable schema contracts.

Canonical Architecture: API-149 (Supabase API Integration Layer)

What It Does

• Bounded client — Wraps @supabase/supabase-js with table allowlists, row limits, query validation, and write confirmation gates

• MCP server — Thin transport over application layer; exposes read-only (default) and gated-write tools for AI agent consumption

• Python CLI — Zero-dependency CLI for agent scripts where Node isn't available

• Migration tooling — Standardized DDL with prefix validation, collision detection, dry-run, and planning

• Schema contracts — Typed table interfaces for the shared project's 50+ tables

• Capability reporting — Doctor command qualifies supported/unavailable/plan-gated/experimental capabilities

• Security audit — RLS status, grants inspection, protected schema validation

• Project/environment targeting — Every operation requires explicit project reference; production never inferred

Related MCP server: Supabase MCP Server

Scope

This repo targets the shared Supabase project (buobojrsaanekrbobgwc) used by:

• project-dashboard

• project-setness-consulting

• project-cpe

• project-munoz

• project-politics

• (future) Albert ledger, LevelBest, Nathan

Quick Start

TypeScript

npm install
npm run verify

Python

pip install -e ".[dev]"
python -m pytest

Safety Model

Repository Structure

src/
├── ts/              # TypeScript source (primary)
│   ├── client/      # Bounded client wrapper
│   ├── auth/        # Session/token management, RLS
│   ├── database/    # Query builder, schema inspector, contracts
│   ├── storage/     # Storage adapter
│   ├── edge-functions/  # Functions adapter
│   ├── realtime/    # Realtime adapter
│   ├── migrations/  # DDL runner, naming validation
│   ├── safety/      # Allowlists, write gates, audit
│   └── mcp/         # MCP server and tools
└── python/          # Python CLI (zero-dep)
    └── supabase_api/

Documentation

• ARCHITECTURE.md — Module layout, dependency direction, trust boundaries

• SECURITY.md — Token handling, write gates, incident response

• STATUS.md — Current lifecycle state and verification results

• AGENTS.md — Agent instructions and hard rules

• CHANGELOG.md — Versioned changes

• docs/PLATFORM-COMPATIBILITY.md — Current Supabase platform requirements

• docs/CONSUMER-ADOPTION.md — Adoption guide for consumer repositories

• docs/ARCHITECTURAL-DECISION-API149-CANONICAL.md — API-149 canonical, API-128 superseded

Architecture Principles

1. MCP is a thin transport — Business logic lives in the application layer, not in MCP tools

2. Project/environment targeting — Every operation requires explicit project reference

3. Read-first authority — Read operations default; mutations require explicit enablement

4. Dry-run before mutations — Migrations default to dry-run

5. Post-change read-back — Mutations return evidence of applied changes

6. No arbitrary REST, shell, SQL, or filesystem passthrough — All operations validated against allowlists

License

Private — AI Projects portfolio internal use.