@aliyun-rds/supabase-mcp-server 1.0.2 → 1.0.4

package/README.md

@@ -4,10 +4,29 @@ MCP (Model Context Protocol) server for self-hosted Supabase instances. Allows A
 
 Originally developed by [HenkDz](https://github.com/HenkDz), now maintained by lemontreen.
 
+## 🚀 Two Modes of Operation
+
+This server supports two modes:
+
+### 1. **Alibaba Cloud Mode** (Recommended for Alibaba Cloud RDS AI users)
+- Automatically fetches Supabase credentials from Alibaba Cloud OpenAPI
+- Only requires Alibaba Cloud AccessKey (AK) and SecretKey (SK)
+- Supports multiple Supabase instances with interactive selection
+- No need to manually configure `anon-key`, `service-key`, or `jwt-secret`
+
+### 2. **Legacy Mode** (For standard self-hosted Supabase)
+- Requires manual configuration of Supabase URL and keys
+- Compatible with any self-hosted Supabase instance
+
 ## Features
 
 This server exposes a rich set of tools for interacting with your self-hosted Supabase instance:
 
+*   **Alibaba Cloud Management** (Alibaba Cloud Mode only)
+    *   `list_aliyun_supabase_instances`: Lists all Supabase instances from Alibaba Cloud RDS AI.
+    *   `connect_to_supabase_instance`: Connects to a specific Supabase instance by name.
+    *   `get_current_supabase_instance`: Shows the currently connected instance.
+    *   `disconnect_supabase_instance`: Disconnects from the current instance.
 *   **Database Schema**
     *   `list_tables`: Lists all tables in the `public` schema.
     *   `list_extensions`: Lists installed PostgreSQL extensions.
@@ -15,7 +34,7 @@ This server exposes a rich set of tools for interacting with your self-hosted Su
     *   `get_database_stats`: Gets database statistics (e.g., table sizes).
 *   **Migrations & SQL**
     *   `list_migrations`: Lists applied migrations from the `supabase_migrations` schema.
-    *   `apply_migration`: Applies a new SQL migration (Requires direct DB access).
+    *   `apply_migration`: Applies a new SQL migration via RPC.
     *   `execute_sql`: Executes arbitrary SQL (Requires helper function in DB or direct DB access).
     *   `generate_typescript_types`: Generates TypeScript types from the database schema.
 *   **Project Configuration**
@@ -28,9 +47,9 @@ This server exposes a rich set of tools for interacting with your self-hosted Su
 *   **Auth User Management**
     *   `list_auth_users`: Lists users from `auth.users`.
     *   `get_auth_user`: Retrieves details for a specific user.
-    *   `create_auth_user`: Creates a new user (Requires direct DB access, insecure password handling).
-    *   `delete_auth_user`: Deletes a user (Requires direct DB access).
-    *   `update_auth_user`: Updates user details (Requires direct DB access, insecure password handling).
+    *   `create_auth_user`: Creates a new user using Supabase Admin API.
+    *   `delete_auth_user`: Deletes a user using Supabase Admin API.
+    *   `update_auth_user`: Updates user details using Supabase Admin API.
 *   **Storage Insights**
     *   `list_storage_buckets`: Lists all storage buckets.
     *   `list_storage_objects`: Lists objects within a specific bucket.
@@ -51,12 +70,98 @@ For example, when you ask an AI assistant "List all tables in my database", it w
 
 ## Setup and Installation
 
-### Method 1: Using npx (Recommended)
+### Alibaba Cloud Mode Setup
+
+#### Quick Start with npx
+
+```bash
+npx @aliyun-rds/supabase-mcp-server \
+  --aliyun-ak YOUR_ACCESS_KEY_ID \
+  --aliyun-sk YOUR_ACCESS_KEY_SECRET \
+  --aliyun-region cn-hangzhou
+```
+
+**Important**: The `--aliyun-region` parameter is **required**. Without it, the API will return empty instance lists even though no error is reported. Common regions include:
+- `cn-hangzhou` (China East 1)
+- `cn-beijing` (China North 2)
+- `cn-shanghai` (China East 2)
+- `cn-shenzhen` (China South 1)
+
+#### Configuration for Claude Desktop
+
+Add to your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "aliyun-supabase": {
+      "command": "npx",
+      "args": [
+        "@aliyun-rds/supabase-mcp-server",
+        "--aliyun-ak", "YOUR_ACCESS_KEY_ID",
+        "--aliyun-sk", "YOUR_ACCESS_KEY_SECRET",
+        "--aliyun-region", "cn-hangzhou"
+      ]
+    }
+  }
+}
+```
+
+**With RAG Agent integration:**
+
+```json
+{
+  "mcpServers": {
+    "aliyun-supabase": {
+      "command": "npx",
+      "args": [
+        "@aliyun-rds/supabase-mcp-server",
+        "--aliyun-ak", "YOUR_ACCESS_KEY_ID",
+        "--aliyun-sk", "YOUR_ACCESS_KEY_SECRET",
+        "--aliyun-region", "cn-hangzhou",
+        "--enable-rag-agent"
+      ]
+    }
+  }
+}
+```
+
+Or use environment variables:
+
+```json
+{
+  "mcpServers": {
+    "aliyun-supabase": {
+      "command": "npx",
+      "args": [
+        "@aliyun-rds/supabase-mcp-server",
+        "--enable-rag-agent"
+      ],
+      "env": {
+        "ALIYUN_ACCESS_KEY_ID": "YOUR_ACCESS_KEY_ID",
+        "ALIYUN_ACCESS_KEY_SECRET": "YOUR_ACCESS_KEY_SECRET",
+        "ALIYUN_REGION": "cn-hangzhou"
+      }
+    }
+  }
+}
+```
+
+#### Usage Workflow
+
+1. **List instances**: Use `list_aliyun_supabase_instances` to see all your Supabase instances
+2. **Connect**: Use `connect_to_supabase_instance` with the instance name
+3. **Use tools**: Now you can use all Supabase tools (list_tables, execute_sql, etc.)
+4. **Disconnect** (optional): Use `disconnect_supabase_instance` to switch instances
+
+### Legacy Mode Setup
+
+#### Method 1: Using npx (Recommended)
 
 The easiest way to use this server is via npx, which requires no installation:
 
 ```bash
-npx @lemontreen/rds-supabase-mcp-server --url http://localhost:8000 --anon-key YOUR_ANON_KEY
+npx @aliyun-rds/supabase-mcp-server --url http://localhost:8000 --anon-key YOUR_ANON_KEY
 ```
 
 ### Method 2: Installing via Smithery
@@ -72,7 +177,7 @@ npx -y @smithery/cli install @HenkDz/selfhosted-supabase-mcp --client claude
 Install the package globally:
 
 ```bash
-npm install -g @lemontreen/rds-supabase-mcp-server
+npm install -g @aliyun-rds/supabase-mcp-server
 supabase-mcp --url http://localhost:8000 --anon-key YOUR_ANON_KEY
 ```
 
@@ -107,6 +212,16 @@ If you want to build from source:
 
 The server requires configuration details for your Supabase instance. These can be provided via command-line arguments or environment variables. CLI arguments take precedence.
 
+### Alibaba Cloud Mode Parameters
+
+**Required:**
+
+*   `--aliyun-ak <key>` or `ALIYUN_ACCESS_KEY_ID=<key>`: Your Alibaba Cloud Access Key ID.
+*   `--aliyun-sk <secret>` or `ALIYUN_ACCESS_KEY_SECRET=<secret>`: Your Alibaba Cloud Access Key Secret.
+*   `--aliyun-region <region>` or `ALIYUN_REGION=<region>`: **Required**. The Alibaba Cloud region where your Supabase instances are deployed (e.g., `cn-hangzhou`, `cn-beijing`). Without this parameter, the API will return empty instance lists.
+
+### Legacy Mode Parameters
+
 **Required:**
 
 *   `--url <url>` or `SUPABASE_URL=<url>`: The main HTTP URL of your Supabase project (e.g., `http://localhost:8000`).
@@ -118,11 +233,53 @@ The server requires configuration details for your Supabase instance. These can
 *   `--db-url <url>` or `DATABASE_URL=<url>`: The direct PostgreSQL connection string for your Supabase database (e.g., `postgresql://postgres:password@localhost:5432/postgres`). Required for tools needing direct database access or transactions (`apply_migration`, Auth tools, Storage tools, querying `pg_catalog`, etc.).
 *   `--jwt-secret <secret>` or `SUPABASE_AUTH_JWT_SECRET=<secret>`: Your Supabase project's JWT secret. Needed for tools like `verify_jwt_secret`.
 *   `--tools-config <path>`: Path to a JSON file specifying which tools to enable (whitelist). If omitted, all tools defined in the server are enabled. The file should have the format `{"enabledTools": ["tool_name_1", "tool_name_2"]}`.
+*   `--enable-rag-agent` or `ENABLE_RAG_AGENT=true`: Enable RAG Agent MCP integration. When enabled, this server will connect to a rag-agent MCP server and expose its tools alongside the Supabase tools. The host and port are extracted from `--url`, and `--anon-key` is used as the API key for rag-agent.
+
+### RAG Agent Integration
+
+This server can integrate with [rag-agent-mcp](https://pypi.org/project/rag-agent-mcp/) to provide RAG (Retrieval-Augmented Generation) capabilities alongside your Supabase database tools.
+
+**How it works:**
+- When `--enable-rag-agent` is set, the server automatically connects to a rag-agent MCP server
+- The host and port are extracted from your `--url` parameter (e.g., `http://your-server:8080` → host: `your-server`, port: `8080`)
+- The `--anon-key` value is used as the API key for authenticating with rag-agent
+- All rag-agent tools are prefixed with `rag_` to avoid naming conflicts (e.g., `rag_create_collection`, `rag_add_documents`, `rag_query`)
+
+**Example configuration:**
+```bash
+npx @aliyun-rds/supabase-mcp-server \
+  --url http://your-supabase-url:port \
+  --anon-key "your-anon-key-here" \
+  --service-key "your-service-key-here" \
+  --enable-rag-agent
+```
+
+**Alibaba Cloud Mode with RAG Agent:**
+```bash
+npx @aliyun-rds/supabase-mcp-server \
+  --aliyun-ak YOUR_ACCESS_KEY_ID \
+  --aliyun-sk YOUR_ACCESS_KEY_SECRET \
+  --aliyun-region cn-hangzhou \
+  --enable-rag-agent
+```
+
+**Requirements:**
+- `uvx` must be installed on your system
+- `rag-agent-mcp` package must be available via `uvx`
+- The rag-agent service must be running at the specified host and port
+
+**Behavior Differences:**
+- **Legacy Mode**: RAG Agent tools are initialized immediately and available after server startup
+- **Alibaba Cloud Mode**: RAG Agent tools are listed at startup but only become functional after connecting to a Supabase instance using `connect_to_supabase_instance` tool
 
 ### Important Notes:
 
 *   **`execute_sql` Helper Function:** Many tools rely on a `public.execute_sql` function within your Supabase database for secure and efficient SQL execution via RPC. The server attempts to check for this function on startup. If it's missing *and* a `service-key` (or `SUPABASE_SERVICE_ROLE_KEY`) *and* `db-url` (or `DATABASE_URL`) are provided, it will attempt to create the function and grant necessary permissions. If creation fails or keys aren't provided, tools relying solely on RPC may fail.
 *   **Direct Database Access:** Tools interacting directly with privileged schemas (`auth`, `storage`) or system catalogs (`pg_catalog`) generally require the `DATABASE_URL` to be configured for a direct `pg` connection.
+*   **Database URL Special Characters:** If your database password or username contains special characters (such as `#`, `$`, etc.), they need to be properly URL encoded to prevent connection issues. The server automatically handles common special characters in the database URL:
+    *   `#` is automatically encoded as `%23`
+    *   `$` is automatically encoded as `%24`
+    *   Note: The `@` symbol is not encoded as it serves as a delimiter in the URL between credentials and hostname
 
 ## Using with AI Assistant Tools
 
@@ -134,10 +291,10 @@ The server requires configuration details for your Supabase instance. These can
     ```json
     {
       "mcpServers": {
-        "selfhosted-supabase": { 
+        "selfhosted-supabase": {
           "command": "npx",
           "args": [
-            "@lemontreen/rds-supabase-mcp-server",
+            "@aliyun-rds/supabase-mcp-server",
             "--url",
             "<your-supabase-url>", // e.g., "http://localhost:8000"
             "--anon-key",
@@ -151,13 +308,53 @@ The server requires configuration details for your Supabase instance. These can
             "<your-jwt-secret>",
             // Optional - Whitelist specific tools
             "--tools-config",
-            "<path-to-tools-config.json>"
+            "<path-to-tools-config.json>",
+            // Optional - Enable RAG Agent integration
+            "--enable-rag-agent"
           ]
         }
       }
     }
     ```
 
+**Example with RAG Agent integration:**
+
+If you want to use this server with both Supabase and RAG Agent tools, configure it like this:
+
+```json
+{
+  "mcpServers": {
+    "remote-selfhosted-supabase": {
+      "command": "ssh",
+      "args": [
+        "user@your-server-ip",
+        "cd /path/to/selfhosted-supabase-mcp && node dist/index.js",
+        "--url",
+        "http://your-supabase-url:port",
+        "--anon-key",
+        "your-anon-key-here",
+        "--service-key",
+        "your-service-key-here",
+        "--enable-rag-agent"
+      ]
+    }
+  }
+}
+```
+
+In this configuration:
+- The server runs on a remote machine via SSH
+- It connects to Supabase at the specified URL
+- `--enable-rag-agent` enables RAG Agent integration
+- RAG Agent will automatically connect to the same host:port extracted from `--url`
+- Both Supabase and RAG Agent tools will be available to your AI assistant
+
+**Important Notes for RAG Agent:**
+- In **Legacy Mode**: RAG Agent tools are available immediately after server startup
+- In **Alibaba Cloud Mode**: RAG Agent tools are listed at startup but only work after connecting to a Supabase instance using `connect_to_supabase_instance`
+- All RAG Agent tools are prefixed with `rag_` (e.g., `rag_create_collection`, `rag_add_documents`, `rag_query`)
+    ```
+
 ### Claude for Desktop
 
 For Claude Desktop, you can add the following to your configuration: