@aliyun-rds/supabase-mcp-server 1.0.6 → 1.0.8

package/README.md

@@ -70,6 +70,23 @@ For example, when you ask an AI assistant "List all tables in my database", it w
 3. Execute the tool against your Supabase instance
 4. Present the results in a human-readable format
 
+## Authentication Modes & Permission Levels
+
+The server supports three authentication modes with automatic tool filtering:
+
+- **Mode 1 – Alibaba Cloud Multi-Instance (AuthMode `aliyun`, permission `full`)**  
+  Use `--aliyun-ak`, `--aliyun-sk`, and `--aliyun-region` to discover and manage multiple Aliyun RDS Supabase instances. Grants access to all tools, including Aliyun management tools.
+- **Mode 2 – Single Instance Admin (AuthMode `admin`, permission `admin`)**  
+  Use `--supabase-url`, `--supabase-anon-key`, and `--supabase-service-role-key` for a single project. Admin-only tools stay available; Aliyun management tools are hidden.
+- **Mode 3 – Single Instance User (AuthMode `user`, permission `user`)**  
+  Use `--supabase-url`, `--supabase-anon-key`, plus `--supabase-user-email` and `--supabase-user-password`. Runs under the user’s RLS scope; admin tools and Aliyun management tools are disabled.
+
+Tool visibility is enforced automatically:
+- **Aliyun-only tools** (e.g., `list_aliyun_supabase_instances`, `connect_to_supabase_instance`, `get_current_supabase_instance`, `disconnect_supabase_instance`) require `full` permissions.
+- **Admin-only tools** (auth management, `get_service_key`, `verify_jwt_secret`, `install_execute_sql_function`, `rebuild_hooks`) require `full` or `admin` permissions.
+
+Mode selection priority: if multiple configurations are provided, the server picks Aliyun first; if Aliyun is absent and user credentials are complete, user mode is selected; otherwise admin mode is used. A warning is logged when multiple modes are detected.
+
 ## Setup and Installation
 
 ### Alibaba Cloud Mode Setup
@@ -158,16 +175,87 @@ Or use environment variables:
 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
 
-### Additional Installation Options
+### Single Instance Admin Mode Setup
+
+```bash
+npx @aliyun-rds/supabase-mcp-server \
+  --supabase-url https://<your-project>.supabase.co \
+  --supabase-anon-key <anon-key> \
+  --supabase-service-role-key <service-role-key> \
+  [--db-url <postgres-connection-string>] \
+  [--jwt-secret <jwt-secret>] \
+  [--enable-rag-agent]
+```
+
+Environment variable alternative:
+
+```bash
+SUPABASE_URL=https://<your-project>.supabase.co \
+SUPABASE_ANON_KEY=<anon-key> \
+SUPABASE_SERVICE_ROLE_KEY=<service-role-key> \
+supabase-mcp
+```
+
+Claude Desktop / Cursor JSON 示例：
+
+```json
+{
+  "mcpServers": {
+    "supabase-admin": {
+      "command": "npx",
+      "args": [
+        "@aliyun-rds/supabase-mcp-server",
+        "--supabase-url", "https://<your-project>.supabase.co",
+        "--supabase-anon-key", "<anon-key>",
+        "--supabase-service-role-key", "<service-role-key>"
+      ]
+    }
+  }
+}
+```
 
-#### Install via Smithery
+### Single Instance User Mode Setup (RLS Restricted)
 
-Install the Aliyun RDS Supabase MCP Server for Claude Desktop automatically via [Smithery](https://smithery.ai/server/@HenkDz/selfhosted-supabase-mcp):
+```bash
+npx @aliyun-rds/supabase-mcp-server \
+  --supabase-url https://<your-project>.supabase.co \
+  --supabase-anon-key <anon-key> \
+  --supabase-user-email <user-email> \
+  --supabase-user-password <user-password> \
+  [--enable-rag-agent]
+```
+
+Environment variable alternative:
 
 ```bash
-npx -y @smithery/cli install @HenkDz/selfhosted-supabase-mcp --client claude
+SUPABASE_URL=https://<your-project>.supabase.co \
+SUPABASE_ANON_KEY=<anon-key> \
+SUPABASE_USER_EMAIL=<user-email> \
+SUPABASE_USER_PASSWORD=<user-password> \
+supabase-mcp
+```
+
+Claude Desktop / Cursor JSON 示例：
+
+```json
+{
+  "mcpServers": {
+    "supabase-user": {
+      "command": "npx",
+      "args": [
+        "@aliyun-rds/supabase-mcp-server",
+        "--supabase-url", "https://<your-project>.supabase.co",
+        "--supabase-anon-key", "<anon-key>",
+        "--supabase-user-email", "<user-email>",
+        "--supabase-user-password", "<user-password>"
+      ]
+    }
+  }
+}
 ```
 
+### Additional Installation Options
+
 #### Global Installation
 
 ```bash
@@ -180,20 +268,45 @@ supabase-mcp \
 
 ## Configuration
 
-The server now relies exclusively on Alibaba Cloud credentials. Provide them via command-line arguments or environment variables (CLI arguments take precedence). Once authenticated, the MCP server automatically retrieves the Supabase URL, anon key, service key, database connection string, and JWT secret for the selected Aliyun RDS instance—no manual entry is needed.
+Choose one configuration path. CLI flags override environment variables.
+
+### Mode 1 — Alibaba Cloud Multi-Instance (permission: full)
+
+Required:
+- `--aliyun-ak <key>` or `ALIYUN_ACCESS_KEY_ID=<key>`
+- `--aliyun-sk <secret>` or `ALIYUN_ACCESS_KEY_SECRET=<secret>`
+- `--aliyun-region <region>` or `ALIYUN_REGION=<region>` (e.g., `cn-hangzhou`, `cn-beijing`; required for discovery)
+
+Behavior: pulls Supabase URL/keys/DB URL/JWT secret from Aliyun for the selected instance.
+
+### Mode 2 — Single Instance Admin (permission: admin)
+
+Required:
+- `--supabase-url <url>` or `SUPABASE_URL`
+- `--supabase-anon-key <key>` or `SUPABASE_ANON_KEY`
+- `--supabase-service-role-key <key>` or `SUPABASE_SERVICE_ROLE_KEY`
+
+Optional:
+- `--db-url <postgres-connection-string>` or `DB_URL`
+- `--jwt-secret <secret>` or `JWT_SECRET`
 
-### Required Parameters
+Legacy flag aliases are still accepted: `--url`, `--anon-key`, `--service-key`, `--db-url`, `--jwt-secret`.
 
-*   `--aliyun-ak <key>` or `ALIYUN_ACCESS_KEY_ID=<key>`: Alibaba Cloud Access Key ID.
-*   `--aliyun-sk <secret>` or `ALIYUN_ACCESS_KEY_SECRET=<secret>`: Alibaba Cloud Access Key Secret.
-*   `--aliyun-region <region>` or `ALIYUN_REGION=<region>`: **Mandatory** region where your Supabase instances live (e.g., `cn-hangzhou`, `cn-beijing`). Without this, the OpenAPI call cannot list instances. This value becomes the default region, but tools like `list_aliyun_supabase_instances` accept a `region_id` parameter so you can query other regions on demand.
+### Mode 3 — Single Instance User (permission: user, RLS enforced)
 
-### Optional Parameters
+Required:
+- `--supabase-url <url>` or `SUPABASE_URL`
+- `--supabase-anon-key <key>` or `SUPABASE_ANON_KEY`
+- `--supabase-user-email <email>` or `SUPABASE_USER_EMAIL`
+- `--supabase-user-password <password>` or `SUPABASE_USER_PASSWORD`
 
-*   `--tools-config <path>`: JSON file specifying which tools to enable (whitelist). Format: `{"enabledTools": ["tool_name_1", "tool_name_2"]}`.
-*   `--enable-rag-agent` or `ENABLE_RAG_AGENT=true`: Enable RAG Agent MCP integration. When enabled, the server resolves the Supabase host/port from the selected instance and uses the retrieved anon key as the API key for rag-agent; no manual `--url` or `--anon-key` flags are needed.
+Behavior: operates under the provided user's RLS policies; admin-only and Aliyun management tools are filtered out.
 
-Legacy CLI options (`--url`, `--anon-key`, `--service-key`, `--db-url`, `--jwt-secret`) have been removed from the user-facing surface because Aliyun RDS now supplies those details automatically.
+### Common Options
+
+- `--tools-config <path>`: JSON file specifying which tools to enable (whitelist). Format: `{"enabledTools": ["tool_name_1", "tool_name_2"]}`.
+- `--enable-rag-agent` or `ENABLE_RAG_AGENT=true`: Enable RAG Agent MCP integration. When enabled, the server resolves the Supabase host/port from the selected instance and uses the retrieved anon key as the API key for rag-agent.
+- `--workspace-path <path>`: Workspace root for file operations (optional).
 
 ### RAG Agent Integration
 
@@ -234,7 +347,10 @@ npx @aliyun-rds/supabase-mcp-server \
 ### Cursor
 
 1.  Create or open the file `.cursor/mcp.json` in your project root.
-2.  Add the following configuration:
+2.  Add one of the following configurations based on your authentication mode:
+
+    **Mode 1 (Aliyun multi-instance, permission: full)**  
+    Grants all tools, including Aliyun management.
 
     ```json
     {
@@ -243,12 +359,9 @@ npx @aliyun-rds/supabase-mcp-server \
           "command": "npx",
           "args": [
             "@aliyun-rds/supabase-mcp-server",
-            "--aliyun-ak",
-            "<your-access-key-id>",
-            "--aliyun-sk",
-            "<your-access-key-secret>",
-            "--aliyun-region",
-            "cn-hangzhou",
+            "--aliyun-ak", "<your-access-key-id>",
+            "--aliyun-sk", "<your-access-key-secret>",
+            "--aliyun-region", "cn-hangzhou",
             "--enable-rag-agent"
           ],
           "env": {
@@ -261,6 +374,47 @@ npx @aliyun-rds/supabase-mcp-server \
     }
     ```
 
+    **Mode 2 (Single instance admin, permission: admin)**  
+    Admin tools available; Aliyun management tools hidden.
+
+    ```json
+    {
+      "mcpServers": {
+        "supabase-admin": {
+          "command": "npx",
+          "args": [
+            "@aliyun-rds/supabase-mcp-server",
+            "--supabase-url", "https://<your-project>.supabase.co",
+            "--supabase-anon-key", "<anon-key>",
+            "--supabase-service-role-key", "<service-role-key>",
+            "--enable-rag-agent"
+          ]
+        }
+      }
+    }
+    ```
+
+    **Mode 3 (Single instance user, permission: user, RLS enforced)**  
+    Runs under user RLS; admin/Aliyun tools disabled.
+
+    ```json
+    {
+      "mcpServers": {
+        "supabase-user": {
+          "command": "npx",
+          "args": [
+            "@aliyun-rds/supabase-mcp-server",
+            "--supabase-url", "https://<your-project>.supabase.co",
+            "--supabase-anon-key", "<anon-key>",
+            "--supabase-user-email", "<user-email>",
+            "--supabase-user-password", "<user-password>",
+            "--enable-rag-agent"
+          ]
+        }
+      }
+    }
+    ```
+
 **Important Notes for RAG Agent:**
 - RAG Agent tools stay inactive until you call `connect_to_supabase_instance` and select an Aliyun RDS Supabase project.
 - Switching instances automatically re-initializes the rag-agent connection with the new host/port.
@@ -268,27 +422,56 @@ npx @aliyun-rds/supabase-mcp-server \
 
 ### Claude for Desktop
 
-For Claude Desktop, you can add the following to your configuration:
+For Claude Desktop, open Settings → Developer → enable "Custom MCP Servers", then add one configuration matching your mode:
 
-1.  Open Claude Desktop Settings
-2.  Go to "Developer" and enable "Custom MCP Servers"
-3.  Add a new server with the following configuration:
+**Mode 1 (Aliyun, permission: full)**
 
-    ```json
-    {
-      "name": "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"
-      ]
-    }
-    ```
+```json
+{
+  "name": "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"
+  ]
+}
+```
+
+**Mode 2 (Single instance admin, permission: admin)**
+
+```json
+{
+  "name": "Supabase Admin",
+  "command": "npx",
+  "args": [
+    "@aliyun-rds/supabase-mcp-server",
+    "--supabase-url", "https://<your-project>.supabase.co",
+    "--supabase-anon-key", "<anon-key>",
+    "--supabase-service-role-key", "<service-role-key>",
+    "--enable-rag-agent"
+  ]
+}
+```
+
+**Mode 3 (Single instance user, permission: user, RLS enforced)**
+
+```json
+{
+  "name": "Supabase User",
+  "command": "npx",
+  "args": [
+    "@aliyun-rds/supabase-mcp-server",
+    "--supabase-url", "https://<your-project>.supabase.co",
+    "--supabase-anon-key", "<anon-key>",
+    "--supabase-user-email", "<user-email>",
+    "--supabase-user-password", "<user-password>",
+    "--enable-rag-agent"
+  ]
+}
+```
 
 ### Other MCP-Compatible Tools