Merge pull request #17 from alexander-zuev/feat/auth-sdk

Feat/auth sdk

Author: alexander-zuev

CHANGELOG.MD

@@ -5,6 +5,15 @@ 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.6] - 2025-02-26
+### Added
+- Added `call_auth_admin_method` which enables MCP server to manage users in your database (create, update, delete, confirm). All Auth SDK methods are supported
+- Added `get_auth_admin_methods_spec` to retrieve documentation for all available Auth Admin methods. Response objects now use attribute access (dot notation) instead of dictionary access.
+
+### Fixed
+- Fixed an issue with improper encoding of database passwords. Previously passwords containing "%" symbol led to connection failures
+
+
 ## [0.3.5] - 2025-02-26
 ### Fixed
 - Fixed an issue with `get_tables` so that it reliably returns foreign tables and views

README.md

@@ -46,6 +46,7 @@ A feature-rich MCP server that enables Cursor and Windsurf to safely interact wi
 - 🔐 Control read-only and read-write modes of SQL query execution
 - 🔄 Robust transaction handling for both direct and pooled database connections
 - 💻 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.)
 
@@ -122,7 +123,7 @@ After installing the package, you'll need to configure your database connection
 
 #### Remote Supabase instance
 
-> ⚠️ **IMPORTANT WARNING**: Session pooling connections are NOT supported yet. Use  transaction pooling and direct connections instead. I'm planning to add / modify connection to support this in v0.4 (soon).
+> ⚠️ **IMPORTANT WARNING**: Session pooling connections are not supported and there are no plans to support it yet. Let me know if you feel there is a use case for supporting this in an MCP server
 
 ![Session pool connections are not supported yet](https://github.com/user-attachments/assets/c01e0e06-8fdc-4632-bde5-922c7a527897)
 
@@ -354,7 +355,6 @@ This MCP server uses::
 - **Direct Database Connection**: when connecting to a local Supabase instance
 - **Transaction Pooler Connections**: when connecting to a remote Supabase instance
 
-> ⚠️ **IMPORTANT WARNING**: Session pooling connections are NOT SUPPORTED. Use  transaction pooling and direct connections instead. I'm planning to add / modify connection to support this in v0.4 (soon).
 
 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.
 
@@ -389,6 +389,41 @@ Since v0.3.0 server supports sending arbitrary requests to Supabase Management A
     - Allows to switch between safe and unsafe modes dynamically
     - Blocked operations (delete project, delete database) are not allowed regardless of the mode
 
+### 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:
+  - Includes the following tools:
+    - `get_auth_admin_methods_spec` to retrieve documentation for all available Auth Admin methods
+    - `call_auth_admin_method` to directly invoke Auth Admin methods with proper parameter handling
+  - Supported methods:
+    - `get_user_by_id`: Retrieve a user by their ID
+    - `list_users`: List all users with pagination
+    - `create_user`: Create a new user
+    - `delete_user`: Delete a user by their ID
+    - `invite_user_by_email`: Send an invite link to a user's email
+    - `generate_link`: Generate an email link for various authentication purposes
+    - `update_user_by_id`: Update user attributes by ID
+    - `delete_factor`: Delete a factor on a user (currently not implemented in SDK)
+
+#### Why use Auth Admin SDK instead of raw SQL queries?
+
+The Auth Admin SDK provides several key advantages over direct SQL manipulation:
+- **Functionality**: Enables operations not possible with SQL alone (invites, magic links, MFA)
+- **Accuracy**: More reliable then creating and executing raw SQL queries on auth schemas
+- **Simplicity**: Offers clear methods with proper validation and error handling
+
+  - Response format:
+    - All methods return structured Python objects instead of raw dictionaries
+    - Object attributes can be accessed using dot notation (e.g., `user.id` instead of `user["id"]`)
+  - Edge cases and limitations:
+    - UUID validation: Many methods require valid UUID format for user IDs and will return specific validation errors
+    - Email configuration: Methods like `invite_user_by_email` and `generate_link` require email sending to be configured in your Supabase project
+    - Link types: When generating links, different link types have different requirements:
+      - `signup` links don't require the user to exist
+      - `magiclink` and `recovery` links require the user to already exist in the system
+    - 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
 
 ## Roadmap
 
@@ -397,14 +432,13 @@ Since v0.3.0 server supports sending arbitrary requests to Supabase Management A
 - 🎮 Programmatic access to Supabase management API with safety controls - ✅ (v0.3.0)
 - 👷‍♂️ Read and read-write database SQL queries with safety controls - ✅ (v0.3.0)
 - 🔄 Robust transaction handling for both direct and pooled connections - ✅ (v0.3.2)
-- 🐍 Support methods and objects available in native Python SDK
+- 🐍 Support methods and objects available in native Python SDK - ✅ (v0.3.6)
 - 🔍 Strong SQL query validation
 - 📝 Connect to db logs to help debug errors (Pull in [edge functions logs](https://supabase.com/dashboard/project/drmzszdytvvfbcytltsw/logs/edge-logs))
 - 👨‍💻 Supabase CLI integration? (if necessary)
+- 🚧 Create a migration file automatically if a migration has been run successfully on the databasae?
 
-### Support of Python SDK methods
 
-I'm planning to add support for Auth methods from Python SDK as it would allow Cursor to create test users for me, which might be handy.
 
 ### Connect to Supabase logs
 

supabase_mcp/api_manager/api_manager.py

@@ -16,7 +16,7 @@
 )
 
 from supabase_mcp.api_manager.api_safety_config import SafetyConfig, SafetyLevel
-from supabase_mcp.api_manager.spec_manager import SpecManager
+from supabase_mcp.api_manager.api_spec_manager import ApiSpecManager
 from supabase_mcp.exceptions import (
     APIClientError,
     APIConnectionError,
@@ -46,7 +46,7 @@ def __init__(self):
     async def create(cls) -> SupabaseApiManager:
         """Factory method to create and initialize an API manager"""
         manager = cls()
-        manager.spec_manager = await SpecManager.create()  # Use the running event loop
+        manager.spec_manager = await ApiSpecManager.create()  # Use the running event loop
         return manager
 
     @classmethod

supabase_mcp/api_manager/spec_manager.py renamed to supabase_mcp/api_manager/api_spec_manager.py

@@ -22,7 +22,7 @@ class ValidationResult:
     operation_info: dict | None = None
 
 
-class SpecManager:
+class ApiSpecManager:
     """
     Manages the OpenAPI specification for the Supabase Management API.
     Handles spec loading, caching, and validation.
@@ -33,8 +33,8 @@ def __init__(self):
         self.spec: dict | None = None
 
     @classmethod
-    async def create(cls) -> "SpecManager":
-        """Async factory method to create and initialize a SpecManager"""
+    async def create(cls) -> "ApiSpecManager":
+        """Async factory method to create and initialize a ApiSpecManager"""
         manager = cls()
         await manager.on_startup()
         return manager

supabase_mcp/exceptions.py

@@ -60,6 +60,12 @@ class APIConnectionError(APIError):
     pass
 
 
+class PythonSDKError(Exception):
+    """Failed to create Python SDK client or call Python SDK method"""
+
+    pass
+
+
 class APIResponseError(APIError):
     """Failed to process API response"""
 

supabase_mcp/main.py

@@ -9,6 +9,7 @@
 from supabase_mcp.db_client.db_safety_config import DbSafetyLevel
 from supabase_mcp.logger import logger
 from supabase_mcp.queries import PreBuiltQueries
+from supabase_mcp.sdk_client.python_client import SupabaseSDKClient
 from supabase_mcp.settings import settings
 from supabase_mcp.validators import (
     validate_schema_name,
@@ -70,6 +71,8 @@ async def get_table_schema(schema_name: str, table: str):
 3. NEVER mix READ and WRITE operations in the same query
 4. NEVER use single DDL statements without transaction control
 5. Remember to enable unsafe mode first with live_dangerously('database', True)
+6. For auth operations (primarily creating, updating, deleting users, generating links, etc), prefer using the Auth Admin SDK methods 
+   instead of direct SQL manipulation to ensure correctness and prevent security issues
 
 TRANSACTION HANDLING:
 - The server detects BEGIN/COMMIT/ROLLBACK keywords to respect your transaction control
@@ -190,6 +193,73 @@ async def get_management_api_safety_rules() -> dict:
     return api_manager.get_safety_rules()
 
 
+@mcp.tool(
+    description="""
+Get Python SDK methods specification for Auth Admin. Returns a python dictionary of all Auth Python SDK methods.
+Use this to understand the available methods and their required parameters.
+"""
+)
+async def get_auth_admin_methods_spec() -> dict:
+    """Returns the Python SDK spec"""
+    sdk_client = await SupabaseSDKClient.get_instance()
+    return sdk_client.return_python_sdk_spec()
+
+
+@mcp.tool(
+    description="""
+Call an Auth Admin method from Supabase Python SDK. Returns the result of the method call.
+
+Available methods:
+- get_user_by_id: Retrieve a user by their ID
+- list_users: List all users with pagination
+- create_user: Create a new user
+- delete_user: Delete a user by their ID
+- invite_user_by_email: Send an invite link to a user's email
+- generate_link: Generate an email link for various authentication purposes
+- update_user_by_id: Update user attributes by ID
+- delete_factor: Delete a factor on a user
+
+Each method requires specific parameters. For nested parameters, follow the structure exactly:
+
+Examples:
+1. Get user by ID:
+   method: "get_user_by_id"
+   params: {"uid": "user-uuid-here"}
+
+2. Create user:
+   method: "create_user"
+   params: {
+     "attributes": {
+       "email": "user@example.com",
+       "password": "secure-password",
+       "email_confirm": true,
+       "user_metadata": {"name": "John Doe"}
+     }
+   }
+
+3. Generate link:
+   method: "generate_link"
+   params: {
+     "params": {
+       "type": "signup",
+       "email": "user@example.com",
+       "password": "secure-password",
+       "options": {
+         "data": {"name": "John Doe"},
+         "redirect_to": "https://example.com/welcome"
+       }
+     }
+   }
+
+Use get_auth_admin_methods_spec() to see full documentation for all methods.
+"""
+)
+async def call_auth_admin_method(method: str, params: dict) -> dict:
+    """Calls a method of the Python SDK client"""
+    sdk_client = await SupabaseSDKClient.get_instance()
+    return await sdk_client.call_auth_admin_method(method, params)
+
+
 def run():
     """Run the Supabase MCP server."""
     if settings.supabase_project_ref.startswith("127.0.0.1"):
@@ -205,6 +275,8 @@ def run():
         )
     if settings.supabase_access_token:
         logger.info("Personal access token detected - using for Management API")
+    if settings.supabase_service_role_key:
+        logger.info("Service role key detected - using for Python SDK")
     mcp.run()
 
 

supabase_mcp/sdk_client/__init__.py

@@ -0,0 +1,95 @@
+from typing import Any, Literal
+
+from pydantic import BaseModel, model_validator
+
+
+class GetUserByIdParams(BaseModel):
+    uid: str
+
+
+class ListUsersParams(BaseModel):
+    page: int | None = 1
+    per_page: int | None = 50
+
+
+class CreateUserParams(BaseModel):
+    email: str | None = None
+    password: str | None = None
+    email_confirm: bool | None = False
+    phone: str | None = None
+    phone_confirm: bool | None = False
+    user_metadata: dict[str, Any] | None = None
+    app_metadata: dict[str, Any] | None = None
+    role: str | None = None
+    ban_duration: str | None = None
+    nonce: str | None = None
+
+    @model_validator(mode="after")
+    def check_email_or_phone(self) -> "CreateUserParams":
+        if not self.email and not self.phone:
+            raise ValueError("Either email or phone must be provided")
+        return self
+
+
+class DeleteUserParams(BaseModel):
+    id: str
+    should_soft_delete: bool | None = False
+
+
+class InviteUserByEmailParams(BaseModel):
+    email: str
+    options: dict[str, Any] | None = None
+
+
+class GenerateLinkParams(BaseModel):
+    type: Literal[
+        "signup", "invite", "magiclink", "recovery", "email_change_current", "email_change_new", "phone_change"
+    ]
+    email: str
+    password: str | None = None
+    new_email: str | None = None
+    options: dict[str, Any] | None = None
+
+    @model_validator(mode="after")
+    def validate_required_fields(self) -> "GenerateLinkParams":
+        # Check password for signup
+        if self.type == "signup" and not self.password:
+            raise ValueError("Password is required for signup links")
+
+        # Check new_email for email change
+        if self.type in ["email_change_current", "email_change_new"] and not self.new_email:
+            raise ValueError("new_email is required for email change links")
+
+        return self
+
+
+class UpdateUserByIdParams(BaseModel):
+    uid: str
+    email: str | None = None
+    password: str | None = None
+    email_confirm: bool | None = False
+    phone: str | None = None
+    phone_confirm: bool | None = False
+    user_metadata: dict[str, Any] | None = None
+    app_metadata: dict[str, Any] | None = None
+    role: str | None = None
+    ban_duration: str | None = None
+    nonce: str | None = None
+
+
+class DeleteFactorParams(BaseModel):
+    id: str
+    user_id: str
+
+
+# Map method names to their parameter models
+PARAM_MODELS = {
+    "get_user_by_id": GetUserByIdParams,
+    "list_users": ListUsersParams,
+    "create_user": CreateUserParams,
+    "delete_user": DeleteUserParams,
+    "invite_user_by_email": InviteUserByEmailParams,
+    "generate_link": GenerateLinkParams,
+    "update_user_by_id": UpdateUserByIdParams,
+    "delete_factor": DeleteFactorParams,
+}