@aliyun-rds/supabase-mcp-server 1.0.3 → 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,7 +70,93 @@ 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:
 
@@ -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`).
@@ -126,15 +241,25 @@ This server can integrate with [rag-agent-mcp](https://pypi.org/project/rag-agen
 
 **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://8.161.141.95:80` → host: `8.161.141.95`, port: `80`)
+- 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_search`, `rag_index`)
+- 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://8.161.141.95:80 \
-  --anon-key "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..." \
+  --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
 ```
 
@@ -143,6 +268,10 @@ npx @aliyun-rds/supabase-mcp-server \
 - `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.
@@ -198,14 +327,14 @@ If you want to use this server with both Supabase and RAG Agent tools, configure
     "remote-selfhosted-supabase": {
       "command": "ssh",
       "args": [
-        "root@8.161.141.95",
-        "cd /root/selfhosted-supabase-mcp && node dist/index.js",
+        "user@your-server-ip",
+        "cd /path/to/selfhosted-supabase-mcp && node dist/index.js",
         "--url",
-        "http://8.161.141.95:80",
+        "http://your-supabase-url:port",
         "--anon-key",
-        "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJzdXBhYmFzZSIsInJvbGUiOiJhbm9uIiwiaWF0IjoxNzYwNDIwNjM5LCJleHAiOjEzMjcxMDYwNjM5fQ.ZV2geUEdh096snzWaCnKXFTyQbyJxLbur8zZooZkY88",
+        "your-anon-key-here",
         "--service-key",
-        "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJzdXBhYmFzZSIsInJvbGUiOiJzZXJ2aWNlX3JvbGUiLCJpYXQiOjE3NjA0MjA2MzksImV4cCI6MTMyNzEwNjA2Mzl9.4wqKCLqJqQqQqQqQqQqQqQqQqQqQqQqQqQqQqQqQqQQ",
+        "your-service-key-here",
         "--enable-rag-agent"
       ]
     }
@@ -215,9 +344,15 @@ If you want to use this server with both Supabase and RAG Agent tools, configure
 
 In this configuration:
 - The server runs on a remote machine via SSH
-- It connects to Supabase at `http://8.161.141.95:80`
-- RAG Agent integration is enabled and will connect to the same host:port
+- 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