feat(infrastructure): streamline services startup and testing patterns

This commit enhances the project's infrastructure and testing capabilities:

- Updated CHANGELOG.md with new infrastructure improvements
- Modified pyproject.toml to adjust pytest asyncio fixture scope
- Refactored core container initialization to support synchronous startup
- Updated services to support clean singleton instance reset
- Improved test fixtures and integration test coverage
- Restructured project test directories for better organization
- Added comprehensive integration tests for various services

Author: alexander-zuev

.github/workflows/ci.yaml

@@ -17,6 +17,7 @@ jobs:
       SUPABASE_PROJECT_REF: ${{ secrets.SUPABASE_PROJECT_REF }}
       SUPABASE_DB_PASSWORD: ${{ secrets.SUPABASE_DB_PASSWORD }}
       SUPABASE_ACCESS_TOKEN: ${{ secrets.SUPABASE_ACCESS_TOKEN }}
+      SUPABASE_SERVICE_ROLE_KEY: ${{ secrets.SUPABASE_SERVICE_ROLE_KEY }}
     steps:
       - uses: actions/checkout@v4
 

.github/workflows/docs/release-checklist.md

@@ -16,6 +16,23 @@ Post-release
 - Clean install from PyPi works
 
 
+## v0.3.8 - 2025-03-07
+
+Pre-release
+1. Tests pass - [X]
+2. CI passes - [X]
+3. Build succeeds - [X]
+4. Documentation is up to date - [X]
+5. Changelog is up to date - [X]
+6. Tag and release on GitHub
+7. Release is published to PyPI
+8. Update dockerfile - [X]
+9. Update .env.example (if necessary) - [X]
+
+Post-release
+10. Clean install from PyPi works
+
+
 
 ## v0.3.0 - 2025-02-22
 

CHANGELOG.MD

@@ -5,41 +5,34 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 
-## [0.3.8] - Planned
-## Added
-1. Runtime SQL query validation
-2. Automatic versioning of database changes
-3. Improvement of SQL execution safety mode
-  - Categorizes all queries into three safety levels:
-    - `safe` - includes all read operations, plus basic postgres commands which do not modify the data or database structure. Always allowed.
-    - `write` - includes write operations. Requires `write` db_client mode to be enabled for use.
-    - `destructive` - include operations which modify database structure, or can lead to data loss. Require 2-step confirmation to be executed AND a `write` mode enabled.
-4. Exception
-5. More modern postgresql client - `asyncpg`
-6. Eliminated depenente on PostgreSQL client libary
-7. Documentation
-- Management API uses encrytpedHTTPS for connecting
-8. Reliability
-- Implemented retry logic for
-  - Establishing connection to the database or API
-  - Sending requests / executing statements
-- Improved API management spec tool:
-  - return all domains
-  - return a specific path and method
-  - return all paths and emthods
-- Added code coverage
-9. Infra:
-- Streamlined dependency injection for easier testing
-
-## Changed
-- Updated README.md with detailed feature description.
+## [0.3.8] - 2025-03-07
+### Added
+- SQL query validation using PostgreSQL's parser (pglast v7.3+)
+- Automatic migration script generation for schema changes
+- Universal safety system with standardized risk levels (Low/Medium/High/Extreme)
+- Switched to asyncpg v0.30.0+ from psycopg2
+- Enhanced API spec tool with multiple query modes and risk assessment
+- Connection retry logic for database and API operations
+- Code coverage with pytest-cov
+- SQL linting with SQLFluff
+- Added pyyaml v6.0.2+ for configuration
+
+### Changed
+- Refactored to use dependency injection pattern
+- Standardized service initialization to synchronous pattern
+- Improved SQL safety categorization:
+  - `safe`: Read-only operations (always allowed)
+  - `write`: Data modification (requires unsafe mode)
+  - `destructive`: Schema changes (requires unsafe mode + confirmation)
+- Updated Ruff to v0.9.9
+- Added asyncpg-stubs and pytest-mock for testing
 
 ## [0.3.7] - 2025-03-02
-### Fixed:
-- fixed various documentation inaccuracies
+### Fixed
+- Documentation inaccuracies
 
 ### Added
-- enabled auth admin SDK use with local Supabase instances
+- Auth admin SDK support for local Supabase instances
 
 
 ## [0.3.6] - 2025-02-26

README.md

@@ -45,23 +45,28 @@ A feature-rich MCP server that enables Cursor and Windsurf to safely interact wi
 ## ✨ Key features
 - 💻 Compatible with Cursor, Windsurf, Cline and other MCP clients supporting `stdio` protocol
 - 🔐 Control read-only and read-write modes of SQL query execution
+- 🔍 Runtime SQL query validation with risk level assessment
+- 🛡️ Three-tier safety system for SQL operations: safe, write, and destructive
 - 🔄 Robust transaction handling for both direct and pooled database connections
+- 📝 Automatic versioning of database schema changes
 - 💻 Manage your Supabase projects with Supabase Management API
 - 🧑‍💻 Manage users with Supabase Auth Admin methods via Python SDK
 - 🔨 Pre-built tools to help Cursor & Windsurf work with MCP more effectively
 - 📦 Dead-simple install & setup via package manager (uv, pipx, etc.)
 
+
 ## Getting Started
 
 ### Prerequisites
 Installing the server requires the following on your system:
 - Python 3.12+
-- PostgresSQL 16+
 
 If you plan to install via `uv`, ensure it's [installed](https://docs.astral.sh/uv/getting-started/installation/#__tabbed_1_1).
 
 ### PostgreSQL Installation
-> ⚠️ **Important**: PostgreSQL must be installed BEFORE installing project dependencies, as psycopg2 requires PostgreSQL development libraries during compilation.
+PostgreSQL installation is no longer required for the MCP server itself, as it now uses asyncpg which doesn't depend on PostgreSQL development libraries.
+
+However, you'll still need PostgreSQL if you're running a local Supabase instance:
 
 **MacOS**
 ```bash
@@ -86,9 +91,7 @@ uv pip install supabase-mcp-server
 
 `pipx` is recommended because it creates isolated environments for each package.
 
-You can also install the server manually by cloning the repository and running `pipx` install -editable . from the root directory.
-
-> ⚠️ If you run into psycopg2 compilation issues, you might be missing PostgreSQL development packages. See above.
+You can also install the server manually by cloning the repository and running `pipx install -e .` from the root directory.
 
 #### Installing from source
 If you would like to install from source, for example for local development:
@@ -116,11 +119,10 @@ npx -y @smithery/cli install @alexander-zuev/supabase-mcp --client claude
 After installing the package, you'll need to configure your database connection settings. The server supports both local and remote Supabase instances.
 
 #### Local Supabase instance (Default)
- Server is pre-configured to connect to the local Supabase instance using default settings:
+Server is pre-configured to connect to the local Supabase instance using default settings:
 - `Host`: 127.0.0.1:54322
 - `Password`: postgres
-- `API URL` : http://127.0.0.1:54321
-
+- `API URL`: http://127.0.0.1:54321
 
 >💡 As long as you didn't modify the default settings and you want to connect to the local instance, you don't need to set environment variables.
 
@@ -156,14 +158,21 @@ The server supports all Supabase regions:
 - `ap-southeast-2` - Oceania (Sydney)
 - `sa-east-1` - South America (São Paulo)
 
-Method of MCP configuration differs between Cursor and Windsurf. Read the relevant section to understand how to configure connection.
+#### Configuration Methods
+
+The server looks for configuration in this order:
+1. Environment variables (highest priority)
+2. Local `.env` file in current directory
+3. Global config file:
+   - Windows: `%APPDATA%/supabase-mcp/.env`
+   - macOS/Linux: `~/.config/supabase-mcp/.env`
+4. Default settings (local development)
 
 ##### Cursor
-Since v0.46 there are two ways to configure MCP servers in Cursor:
+Since Cursor v0.46 there are two ways to configure MCP servers:
 - per project basis -> create `mcp.json` in your project / repo folder and `.env` to configure connection
 - globally -> create an MCP server in Settings and configure using `.env` which is supported by this MCP server only
 
-
 You can create project-specific MCP by:
 - creating .cursor folder in your repo, if doesn't exist
 - creating or updating `mcp.json` file with the following settings
@@ -333,76 +342,69 @@ A super useful tool to help debug MCP server issues is MCP Inspector. If you ins
 
 ### Database query tools
 
-Since v0.3.0 server supports both read-only and data modification operations:
-
-- **Read operations**: SELECT queries for data retrieval
-- **Data Manipulation Language (DML)**: INSERT, UPDATE, DELETE operations for data changes
-- **Data Definition Language (DDL)**: CREATE, ALTER, DROP operations for schema changes*
-
-*Note: DDL operations require:
-1. Read-write mode enabled via `live_dangerously`
-2. Sufficient permissions for the connected database role
-
-#### Transaction Handling
-
-The server supports two approaches for executing write operations:
-
-1. **Explicit Transaction Control** (Recommended):
-   ```sql
-   BEGIN;
-   CREATE TABLE public.test_table (id SERIAL PRIMARY KEY, name TEXT);
-   COMMIT;
-   ```
-
-2. **Single Statements**:
-   ```sql
-   CREATE TABLE public.test_table (id SERIAL PRIMARY KEY, name TEXT);
-   ```
-
-For DDL operations (CREATE/ALTER/DROP), tool description appropriately guides Cursor/Windsurft to use explicit transaction control with BEGIN/COMMIT blocks.
-
-#### Connection Types
-
-This MCP server uses::
-- **Direct Database Connection**: when connecting to a local Supabase instance
-- **Transaction Pooler Connections**: when connecting to a remote Supabase instance
-
-
-When connecting via Supabase's Transaction Pooler, some complex transaction patterns may not work as expected. For schema changes in these environments, use explicit transaction blocks or consider using Supabase migrations or the SQL Editor in the dashboard.
-
-Available database tools:
-- `get_db_schemas` - Lists all database schemas with their sizes and table counts
-- `get_tables` - Lists all tables in a schema with their sizes, row counts, and metadata
-- `get_table_schema` - Gets detailed table structure including columns, keys, and relationships
-- `execute_sql_query` - Executes raw SQL queries with comprehensive support for all PostgreSQL operations:
-  - Supports all query types (SELECT, INSERT, UPDATE, DELETE, CREATE, ALTER, DROP, etc.)
-  - Handles transaction control statements (BEGIN, COMMIT, ROLLBACK)
-
-
-- Supported modes:
-  - `read-only` - only read-only queries are allowed (default mode)
-  - `read-write` - all SQL operations are allowed when explicitly enabled
-- Safety features:
-  - Starts in read-only mode by default
-  - Requires explicit mode switch for write operations
-  - Automatically resets to read-only mode after write operations
-  - Intelligent transaction state detection to prevent errors
-  - SQL query validation [TODO]
+Since v0.3+ server provides comprehensive database management capabilities with built-in safety controls:
+
+- **SQL Query Execution**: Execute any PostgreSQL query with intelligent risk assessment
+  - **Three-tier safety system**:
+    - `safe`: Read-only operations (SELECT, EXPLAIN) - always allowed
+    - `write`: Data modification operations (INSERT, UPDATE, DELETE) - require unsafe mode
+    - `destructive`: Schema-changing operations (DROP, TRUNCATE) - require unsafe mode and confirmation
+
+- **SQL Parsing and Validation**:
+  - Uses PostgreSQL's own parser (via pglast) for accurate query analysis
+  - Precisely identifies query types and potential risks
+  - Validates syntax before execution to prevent errors
+  - Categorizes statements into DQL, DML, DDL, DCL, and TCL types
+  - Provides detailed feedback on query safety and required permissions
+
+- **Automatic Migration Versioning**:
+  - All schema-changing operations (DDL) are automatically versioned
+  - Creates timestamped migration entries in Supabase's migration system
+  - Generates descriptive migration names based on operation type and target
+  - Includes CREATE, ALTER, DROP, GRANT, REVOKE operations
+  - Maintains a complete history of schema changes for better tracking and rollback capabilities
+
+- **Safety Controls**:
+  - All database tools start in SAFE mode by default (only read-only operations are allowed)
+  - All statements are executed in transaction mode by the `asyncpg` client
+  - 2-step confirmation is required for high-risk / destructive operations
+
+- **Available Tools**:
+  - `get_schemas`: Lists all database schemas with their sizes and table counts
+  - `get_tables`: Lists tables, foreign tables, and views in a schema with metadata
+  - `get_table_schema`: Gets detailed table structure including columns, keys, and relationships
+  - `execute_postgresql`: Executes PostgreSQL statements against your Supabase database
+  - `confirm_destructive_operation`: Executes high-risk operations after explicit confirmation
+  - `retrieve_migrations`: Gets all migrations from the supabase_migrations schema
+  - `live_dangerously`: Toggles between safe and unsafe operation modes
 
 ### Management API tools
-Since v0.3.0 server supports sending arbitrary requests to Supabase Management API with auto-injection of project ref and safety mode control:
-  - Includes the following tools:
-    - `send_management_api_request` to send arbitrary requests to Supabase Management API, with auto-injection of project ref and safety mode control
-    - `get_management_api_spec` to get the enriched API specification with safety information
-    - `get_management_api_safety_rules` to get all safety rules including blocked and unsafe operations with human-readable explanations
-    - `live_dangerously` to switch between safe and unsafe modes
-  - Safety features:
-    - Divides API methods into `safe`, `unsafe` and `blocked` categories based on the risk of the operation
-    - Allows to switch between safe and unsafe modes dynamically
-    - Blocked operations (delete project, delete database) are not allowed regardless of the mode
-  - **Note**: Management API tools only work with remote Supabase instances and are not compatible with local Supabase development setups.
+
+Since v0.3.0 server provides secure access to the Supabase Management API with built-in safety controls:
+
+- **Available Tools**:
+  - `send_management_api_request`: Sends arbitrary requests to Supabase Management API with auto-injection of project ref
+  - `get_management_api_spec`: Gets the enriched API specification with safety information
+    - Supports multiple query modes: by domain, by specific path/method, or all paths
+    - Includes risk assessment information for each endpoint
+    - Provides detailed parameter requirements and response formats
+    - Helps LLMs understand the full capabilities of the Supabase Management API
+  - `get_management_api_safety_rules`: Gets all safety rules with human-readable explanations
+  - `live_dangerously`: Toggles between safe and unsafe operation modes
+
+- **Safety Controls**:
+  - Uses the same safety manager as database operations for consistent risk management
+  - Operations categorized by risk level:
+    - `safe`: Read-only operations (GET) - always allowed
+    - `unsafe`: State-changing operations (POST, PUT, PATCH, DELETE) - require unsafe mode
+    - `blocked`: Destructive operations (delete project, etc.) - never allowed
+  - Default safe mode prevents accidental state changes
+  - Path-based pattern matching for precise safety rules
+
+**Note**: Management API tools only work with remote Supabase instances and are not compatible with local Supabase development setups.
 
 ### Auth Admin tools
+
 I was planning to add support for Python SDK methods to the MCP server. Upon consideration I decided to only add support for Auth admin methods as I often found myself manually creating test users which was prone to errors and time consuming. Now I can just ask Cursor to create a test user and it will be done seamlessly. Check out the full Auth Admin SDK method docs to know what it can do.
 
 Since v0.3.6 server supports direct access to Supabase Auth Admin methods via Python SDK:
@@ -440,13 +442,29 @@ The Auth Admin SDK provides several key advantages over direct SQL manipulation:
 
 ### Automatic Versioning of Database Changes
 
-"With great power comes great responsibility." While `execute_sql_query` tool coupled with aptly named `live_dangerously` tool provide a powerful and simple way to manage your Supabase database, it also means that dropping a table or modifying one is one chat message away. In order to reduce the risk of irreversible changes, since v0.3.8 the server supports:
+"With great power comes great responsibility." While `execute_postgresql` tool coupled with aptly named `live_dangerously` tool provide a powerful and simple way to manage your Supabase database, it also means that dropping a table or modifying one is one chat message away. In order to reduce the risk of irreversible changes, since v0.3.8 the server supports:
 - automatic creation of migration scripts for all write & destructive sql operations executed on the database
 - improved safety mode of query execution, in which all queries are categorized in:
   - `safe` type: always allowed. Includes all read-only ops.
   - `write`type: requires `write` mode to be enabled by the user.
   - `destructive` type: requires `write` mode to be enabled by the user AND a 2-step confirmation of query execution for clients that do not execute tools automatically.
 
+### Universal Safety Mode
+Since v0.3.8 Safety Mode has been standardized across all services (database, API, SDK) using a universal safety manager. This provides consistent risk management and a unified interface for controlling safety settings across the entire MCP server.
+
+All operations (SQL queries, API requests, SDK methods) are categorized into risk levels:
+- `Low` risk: Read-only operations that don't modify data or structure (SELECT queries, GET API requests)
+- `Medium` risk: Write operations that modify data but not structure (INSERT/UPDATE/DELETE, most POST/PUT API requests)
+- `High` risk: Destructive operations that modify database structure or could cause data loss (DROP/TRUNCATE, DELETE API endpoints)
+- `Extreme` risk: Operations with severe consequences that are blocked entirely (deleting projects)
+
+Safety controls are applied based on risk level:
+- Low risk operations are always allowed
+- Medium risk operations require unsafe mode to be enabled
+- High risk operations require unsafe mode AND explicit confirmation
+- Extreme risk operations are never allowed
+
+This universal approach ensures consistent protection across all server components while providing flexibility for legitimate operations when needed.
 
 ## Feature Changelog
 
@@ -457,12 +475,10 @@ The Auth Admin SDK provides several key advantages over direct SQL manipulation:
 - 🔄 Robust transaction handling for both direct and pooled connections - ✅ (v0.3.2)
 - 🐍 Support methods and objects available in native Python SDK - ✅ (v0.3.6)
 - 🔍 Stronger SQL query validation ✅ (v0.3.8)
-- 📝 Automatic versioning of DDL queries ✅ (v0.3.8)
+- 📝 Automatic versioning of database changes ✅ (v0.3.8)
+- 📖 Radically improved knowledge and tools of api spec ✅ (v0.3.8)
 - 🪵 Tools / resources to more easily access database, edge functions logs (?)
-- 👨‍💻 Supabase CLI integration (?)
-- 📖 Radically improved knowledge and tools of api spec
-  - Resources to more easily access and check api spec
-  - Atomic url paths and ops (right now LLM trips more often then not)
+
 
 For a more detailed roadmap, please see this [discussion](github.com) on GitHub.
 

pyproject.toml

@@ -114,14 +114,11 @@ python_classes = ["Test*"]
 python_functions = ["test_*"]
 addopts = "-v --no-header --tb=short"
 
-# addopts = "-v --no-header --tb=short --showlocals --log-cli-level=INFO"
 
 [tool.pytest.ini_options]
-# log_cli = true
-# log_cli_format = "%(asctime)s [%(levelname)8s] %(message)s (%(filename)s:%(lineno)s)"
-# log_cli_date_format = "%Y-%m-%d %H:%M:%S"
 asyncio_mode = "auto"
-asyncio_default_fixture_loop_scope = "function"
+asyncio_default_fixture_loop_scope = "module"
+
 markers = [
     "unit: marks a test as a unit test",
     "integration: marks a test as an integration test that requires database access"

supabase_mcp/core/container.py

@@ -57,7 +57,3 @@ def initialize(self, settings: Settings) -> "Container":
 
         logger.info("✓ All services initialized successfully.")
         return self
-
-    async def shutdown(self) -> None:
-        """Shuts down all services in a synchronous manner to satisfy MCP runtime requirements"""
-        await self.postgres_client.close()