Merge pull request #56 from alexander-zuev/feat/log-tools

feat(logs): introduce retrieve_logs tool

Author: alexander-zuev

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

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

.gitignore

@@ -64,7 +64,8 @@ Icon
 # Local development
 
 *.log
-logs/
+# Only ignore logs directory in the root, not in the package
+/logs/
 
 
 # Ignore local assets

.pre-commit-config.yaml

@@ -120,10 +120,10 @@ repos:
         pass_filenames: false
         args: [
           "--no-header",
-          "-v",
           "--quiet",
           "--no-summary",
-          "--show-capture=no"
+          "--show-capture=no",
+          "--tb=line"  # Show only one line per failure
         ]
         stages: [pre-commit, pre-push]
 

CHANGELOG.MD

@@ -5,6 +5,17 @@ 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.12] - 2025-03-12
+### Added
+- Implemented a new `retrieve_logs` tool that allows retrieval of logs from any Supabase log collection - Postgres, PostgREST, Auth, Edge Functions and others. Provides a way to query and filter
+- Implemented log rotation to prevent unbounded log file growth (5MB limit with 3 backup files)
+
+### Changed
+- Improved region configuration with clearer error messages for region mismatches
+- Updated smithery.yaml to reduce configuration error rate (Tenant not found)
+- Improved PostgreSQL client connection error handling with specific guidance for "Tenant or user not found" errors
+
+
 ## [0.3.11] - 2025-03-10
 ### Fixed
 - Fixed an error with creating a migration file when a user doesn't have `supabase_migrations` schema

README.md

@@ -120,14 +120,16 @@ The server uses the following environment variables:
 
 | Variable | Required | Default | Description |
 |----------|----------|---------|-------------|
-| `SUPABASE_PROJECT_REF` | No | `127.0.0.1:54322` | Your Supabase project reference ID (or local host:port) |
-| `SUPABASE_DB_PASSWORD` | No | `postgres` | Your database password |
-| `SUPABASE_REGION` | No | `us-east-1` | AWS region where your Supabase project is hosted |
+| `SUPABASE_PROJECT_REF` | Yes | `127.0.0.1:54322` | Your Supabase project reference ID (or local host:port) |
+| `SUPABASE_DB_PASSWORD` | Yes | `postgres` | Your database password |
+| `SUPABASE_REGION` | Yes* | `us-east-1` | AWS region where your Supabase project is hosted |
 | `SUPABASE_ACCESS_TOKEN` | No | None | Personal access token for Supabase Management API |
 | `SUPABASE_SERVICE_ROLE_KEY` | No | None | Service role key for Auth Admin SDK |
 
 > **Note**: The default values are configured for local Supabase development. For remote Supabase projects, you must provide your own values for `SUPABASE_PROJECT_REF` and `SUPABASE_DB_PASSWORD`.
 
+> 🚨 **CRITICAL CONFIGURATION NOTE**: For remote Supabase projects, you MUST specify the correct region where your project is hosted using `SUPABASE_REGION`. If you encounter a "Tenant or user not found" error, this is almost certainly because your region setting doesn't match your project's actual region. You can find your project's region in the Supabase dashboard under Project Settings.
+
 #### Connection Types
 
 ##### Database Connection
@@ -492,6 +494,28 @@ The Auth Admin SDK provides several key advantages over direct SQL manipulation:
     - Error handling: The server provides detailed error messages from the Supabase API, which may differ from the dashboard interface
     - Method availability: Some methods like `delete_factor` are exposed in the API but not fully implemented in the SDK
 
+### Logs & Analytics
+
+The server provides access to Supabase logs and analytics data, making it easier to monitor and troubleshoot your applications:
+
+- **Available Tool**: `retrieve_logs` - Access logs from any Supabase service
+
+- **Log Collections**:
+  - `postgres`: Database server logs
+  - `api_gateway`: API gateway requests
+  - `auth`: Authentication events
+  - `postgrest`: RESTful API service logs
+  - `pooler`: Connection pooling logs
+  - `storage`: Object storage operations
+  - `realtime`: WebSocket subscription logs
+  - `edge_functions`: Serverless function executions
+  - `cron`: Scheduled job logs
+  - `pgbouncer`: Connection pooler logs
+
+- **Features**: Filter by time, search text, apply field filters, or use custom SQL queries
+
+Simplifies debugging across your Supabase stack without switching between interfaces or writing complex queries.
+
 ### Automatic Versioning of Database Changes
 
 "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:

smithery.yaml

@@ -10,6 +10,7 @@ startCommand:
     required:
       - supabaseProjectRef
       - supabaseDbPassword
+      - supabaseRegion
     properties:
       supabaseProjectRef:
         type: string
@@ -21,8 +22,7 @@ startCommand:
         default: "postgres"
       supabaseRegion:
         type: string
-        description: "(optional) - AWS region where your Supabase project is hosted - Default: us-east-1"
-        default: "us-east-1"
+        description: "(required) - AWS region where your Supabase project is hosted - Default: us-east-1"
       supabaseAccessToken:
         type: string
         description: "(optional) - Personal access token for Supabase Management API - Default: none"

supabase_mcp/core/container.py

@@ -5,6 +5,7 @@
 from supabase_mcp.services.api.api_manager import SupabaseApiManager
 from supabase_mcp.services.database.postgres_client import PostgresClient
 from supabase_mcp.services.database.query_manager import QueryManager
+from supabase_mcp.services.logs.log_manager import LogManager
 from supabase_mcp.services.safety.safety_manager import SafetyManager
 from supabase_mcp.services.sdk.sdk_client import SupabaseSDKClient
 from supabase_mcp.settings import Settings
@@ -22,6 +23,7 @@ def __init__(
         safety_manager: SafetyManager | None = None,
         query_manager: QueryManager | None = None,
         tool_manager: ToolManager | None = None,
+        log_manager: LogManager | None = None,
     ) -> None:
         """Create a new container container reference"""
         self.mcp_server = mcp_server
@@ -32,6 +34,7 @@ def __init__(
         self.safety_manager = safety_manager
         self.query_manager = query_manager
         self.tool_manager = tool_manager
+        self.log_manager = log_manager
 
     def initialize(self, settings: Settings) -> "Container":
         """Initializes all services in a synchronous manner to satisfy MCP runtime requirements"""

supabase_mcp/logger.py

@@ -1,9 +1,10 @@
 import logging
+import logging.handlers
 from pathlib import Path
 
 
 def setup_logger() -> logging.Logger:
-    """Configure logging for the MCP server."""
+    """Configure logging for the MCP server with log rotation."""
     logger = logging.getLogger("supabase-mcp")
 
     # Remove existing handlers to avoid duplicate logs
@@ -17,8 +18,15 @@ def setup_logger() -> logging.Logger:
     # Define the log file path
     log_file = log_dir / "mcp_server.log"
 
-    # Create a file handler (only logs to file, no stdout)
-    file_handler = logging.FileHandler(log_file)
+    # Create a rotating file handler
+    # - Rotate when log reaches 5MB
+    # - Keep 3 backup files
+    file_handler = logging.handlers.RotatingFileHandler(
+        log_file,
+        maxBytes=5 * 1024 * 1024,  # 5MB
+        backupCount=3,
+        encoding="utf-8",
+    )
 
     # Create formatter
     formatter = logging.Formatter("[%(asctime)s] %(levelname)-8s %(message)s", datefmt="%y/%m/%d %H:%M:%S")

supabase_mcp/services/api/api_manager.py

@@ -6,6 +6,7 @@
 from supabase_mcp.logger import logger
 from supabase_mcp.services.api.api_client import ManagementAPIClient
 from supabase_mcp.services.api.spec_manager import ApiSpecManager
+from supabase_mcp.services.logs.log_manager import LogManager
 from supabase_mcp.services.safety.models import ClientType
 from supabase_mcp.services.safety.safety_manager import SafetyManager
 from supabase_mcp.settings import settings
@@ -35,11 +36,13 @@ def __init__(
         api_client: ManagementAPIClient,
         safety_manager: SafetyManager,
         spec_manager: ApiSpecManager | None = None,
+        log_manager: LogManager | None = None,
     ) -> None:
         """Initialize the API manager."""
         self.spec_manager = spec_manager or ApiSpecManager()  # this is so that I don't have to pass it
         self.client = api_client
         self.safety_manager = safety_manager
+        self.log_manager = log_manager or LogManager()
 
     @classmethod
     def get_instance(
@@ -288,3 +291,57 @@ async def handle_spec_request(
         # Option 3: Get all domains (default)
         else:
             return {"domains": spec_manager.get_all_domains()}
+
+    async def retrieve_logs(
+        self,
+        collection: str,
+        limit: int = 20,
+        hours_ago: int | None = 1,
+        filters: list[dict[str, Any]] | None = None,
+        search: str | None = None,
+        custom_query: str | None = None,
+    ) -> dict[str, Any]:
+        """Retrieve logs from a Supabase service.
+
+        Args:
+            collection: The log collection to query
+            limit: Maximum number of log entries to return
+            hours_ago: Retrieve logs from the last N hours
+            filters: List of filter objects with field, operator, and value
+            search: Text to search for in event messages
+            custom_query: Complete custom SQL query to execute
+
+        Returns:
+            The query result
+
+        Raises:
+            ValueError: If the collection is unknown
+        """
+        log_manager = self.log_manager
+
+        # Build the SQL query using LogManager
+        sql = log_manager.build_logs_query(
+            collection=collection,
+            limit=limit,
+            hours_ago=hours_ago,
+            filters=filters,
+            search=search,
+            custom_query=custom_query,
+        )
+
+        logger.debug(f"Executing log query: {sql}")
+
+        # Make the API request
+        try:
+            response = await self.execute_request(
+                method="GET",
+                path="/v1/projects/{ref}/analytics/endpoints/logs.all",
+                path_params={},
+                request_params={"sql": sql},
+                request_body={},
+            )
+
+            return response
+        except Exception as e:
+            logger.error(f"Error retrieving logs: {e}")
+            raise

supabase_mcp/services/database/postgres_client.py

@@ -77,7 +77,12 @@ def __init__(
         self.db_url = self._build_connection_string()
         self.sql_validator: SQLValidator = SQLValidator()
 
-        logger.info(f"Initialized PostgresClient with project ref: {self.project_ref}")
+        # Only log once during initialization with clear project info
+        is_local = self.project_ref.startswith("127.0.0.1")
+        logger.info(
+            f"PostgreSQL client initialized for {'local' if is_local else 'remote'} "
+            f"project: {self.project_ref} (region: {self.db_region})"
+        )
 
     @classmethod
     def get_instance(
@@ -118,15 +123,13 @@ def _build_connection_string(self) -> str:
         if self.project_ref.startswith("127.0.0.1"):
             # Local development
             connection_string = f"postgresql://postgres:{encoded_password}@{self.project_ref}/postgres"
-            logger.debug("Using local development connection string")
             return connection_string
 
         # Production Supabase - via transaction pooler
         connection_string = (
             f"postgresql://postgres.{self.project_ref}:{encoded_password}"
             f"@aws-0-{self._settings.supabase_region}.pooler.supabase.com:6543/postgres"
         )
-        logger.debug(f"Using production connection string for region: {self._settings.supabase_region}")
         return connection_string
 
     @retry(
@@ -152,7 +155,7 @@ async def create_pool(self) -> asyncpg.Pool[asyncpg.Record]:
             ConnectionError: If unable to establish a connection to the database
         """
         try:
-            logger.debug(f"Creating asyncpg connection pool for: {self.db_url.split('@')[1]}")
+            logger.debug(f"Creating connection pool for project: {self.project_ref}")
 
             # Create the pool with optimal settings
             pool = await asyncpg.create_pool(
@@ -167,14 +170,61 @@ async def create_pool(self) -> asyncpg.Pool[asyncpg.Record]:
             # Test the connection with a simple query
             async with pool.acquire() as conn:
                 await conn.execute("SELECT 1")
-                logger.debug("Connection test successful")
 
-            logger.info("✓ Created PostgreSQL connection pool with asyncpg")
+            logger.info("✓ Database connection established successfully")
             return pool
 
-        except (asyncpg.PostgresError, OSError) as e:
+        except asyncpg.PostgresError as e:
+            # Extract connection details for better error reporting
+            host_part = self.db_url.split("@")[1].split("/")[0] if "@" in self.db_url else "unknown"
+
+            # Check specifically for the "Tenant or user not found" error which is often caused by region mismatch
+            if "Tenant or user not found" in str(e):
+                error_message = (
+                    "CONNECTION ERROR: Region mismatch detected!\n\n"
+                    f"Could not connect to Supabase project '{self.project_ref}'.\n\n"
+                    "This error typically occurs when your SUPABASE_REGION setting doesn't match your project's actual region.\n"
+                    f"Your configuration is using region: '{self.db_region}' (default: us-east-1)\n\n"
+                    "ACTION REQUIRED: Please set the correct SUPABASE_REGION in your MCP server configuration.\n"
+                    "You can find your project's region in the Supabase dashboard under Project Settings."
+                )
+            else:
+                error_message = (
+                    f"Could not connect to database: {e}\n"
+                    f"Connection attempted to: {host_part}\n via Transaction Pooler\n"
+                    f"Project ref: {self.project_ref}\n"
+                    f"Region: {self.db_region}\n\n"
+                    f"Please check:\n"
+                    f"1. Your Supabase project reference is correct\n"
+                    f"2. Your database password is correct\n"
+                    f"3. Your region setting matches your Supabase project region\n"
+                    f"4. Your Supabase project is active and the database is online\n"
+                )
+
             logger.error(f"Failed to connect to database: {e}")
-            raise ConnectionError(f"Could not connect to database: {e}") from e
+            logger.error(f"Connection details: {host_part}, Project: {self.project_ref}, Region: {self.db_region}")
+
+            raise ConnectionError(error_message) from e
+
+        except OSError as e:
+            # For network-related errors, provide a different message that clearly indicates
+            # this is a network/system issue rather than a database configuration problem
+            host_part = self.db_url.split("@")[1].split("/")[0] if "@" in self.db_url else "unknown"
+
+            error_message = (
+                f"Network error while connecting to database: {e}\n"
+                f"Connection attempted to: {host_part}\n\n"
+                f"This appears to be a network or system issue rather than a database configuration problem.\n"
+                f"Please check:\n"
+                f"1. Your internet connection is working\n"
+                f"2. Any firewalls or network security settings allow connections to {host_part}\n"
+                f"3. DNS resolution is working correctly\n"
+                f"4. The Supabase service is not experiencing an outage\n"
+            )
+
+            logger.error(f"Network error connecting to database: {e}")
+            logger.error(f"Connection details: {host_part}")
+            raise ConnectionError(error_message) from e
 
     async def ensure_pool(self) -> None:
         """Ensure a valid connection pool exists.