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

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

Operation	Default	Write Gate
SELECT queries	Allowed	Bounded (max rows, timeout)
Schema inspection	Allowed	Read-only
Storage read	Allowed	Bounded
INSERT/UPDATE/DELETE	Allowed with token	`APPLY_SUPABASE_CHANGES` or per-operation token
DDL (migrations)	Owner-gated	Separate confirmation, dry-run default
Edge Function invoke	Allowed with scope	Function allowlist
Realtime subscribe	Allowed	Channel allowlist

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

MCP is a thin transport — Business logic lives in the application layer, not in MCP tools
Project/environment targeting — Every operation requires explicit project reference
Read-first authority — Read operations default; mutations require explicit enablement
Dry-run before mutations — Migrations default to dry-run
Post-change read-back — Mutations return evidence of applied changes
No arbitrary REST, shell, SQL, or filesystem passthrough — All operations validated against allowlists

License

Private — AI Projects portfolio internal use.